Merge PR #224 updates into prose cleanup

packages/core/agent/README.md

@@ -8,30 +8,30 @@ Tracks live agents so UI, hook, and orchestrator plugins can find them without i
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher every agent-subject event goes through (carrier + injected subject in one move); `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while the factory keeps the agent and session unpublished; creation awaits setup and a same-turn owner-unload checkpoint before either creation notification or the first assembly. Setup composes, it never drives: the concrete loop rejects driving verbs until the `agent/session-start` boundary.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 - `ctx.agents.register(agent: Agent): () => Promise<void> | void` — record an **already-constructed** agent. Disposed with the calling fiber.
-- Advanced ordered lifecycle: `enter(agent): () => void` inserts without announcing, and `announce(agent)` emits `agent/created` only for that exact live entry. The async factory uses this split after setup; ordinary plugins use `register()`.
+- Advanced ordered lifecycle: `enter(agent): () => void` performs the authoritative ID collision check and inserts without announcing; `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.
 - `ctx.agents.get(id: AgentId): Agent | undefined`
 - `ctx.agents.list(): Agent[]`
 
 #### Factory seam (creation)
 
-Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package.
+Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
 
 - `ctx.agents.setFactory(factory: AgentFactory): () => Promise<void> | void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
-- `ctx.agents.create(options: CreateAgentOptions): Promise<AgentHandle>` — snapshot caller-owned IDs/options/metadata/seed, construct and await optional setup while unpublished, insert and announce both session and agent, open the `agent/session-start` driving boundary, then start a new loop on the caller-supplied `sessionId`. Agent/session IDs are reserved across setup; setup rejection or owner unload publishes nothing. Publication is rollback-covered: if a creation listener throws, entries and scope unwind but effects of already-delivered notifications remain observable; an agent whose announcement began emits `agent/disposed` during that rollback. Rejects if no factory is registered.
-- `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — snapshot caller-owned IDs/options, load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), mint a fresh agent scope, await optional setup while unpublished, then follow the same insert → announce → session-start → loop-start boundary. The IDs are reserved across persistence load and setup; load/setup rejection or owner unload publishes nothing. Rejects if no factory is registered or session persistence is unconfigured.
+- `ctx.agents.create(options: CreateAgentOptions): Promise<AgentHandle>` — create a session and agent, await optional setup while unpublished, then publish through final `SessionStore.enter()` and `AgentRegistry.enter()` checks. Concurrent same-ID creation is unsupported: more than one operation may prepare, but only one can enter; every loser rolls its private scope/session/driver back. An optional creation-only `signal` cancels unpublished setup and is detached before the handle is returned; later cancellation uses `handle.dispose()` or `agent.cancel()`. Publication is rollback-covered and every delivered creation edge is paired during rollback. Rejects if no factory is registered.
+- `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), mint a fresh unpublished agent scope, await optional setup, and use the same final-entry publication sequence. Its optional `signal` is likewise creation-only. Rejects if no factory is registered or session persistence is unconfigured.
 
-`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit plus every outstanding idle-injection flush (quiescence — NOT just the `disposed` status flip), unregisters the agent, removes its session from the store, and finally unwinds its scoped world. This order captures every agent-started `session/flush` before the session is detached and keeps scoped listeners alive through those checkpoints. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge and in-process subagent backends are production consumers; config-created agents are owned by the loop fiber and never need a handle.
+`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **consumer capability** — no observer holding the bare registry entry can tear the agent down. The caller fiber and the registered factory provider are structural co-owners: caller unload enforces structured ownership, while factory unload must stop old instances because their scoped dependency surface belongs to that provider. `dispose()` from any owner reaches one memoized quiescence boundary: it stops the loop, `await`s its exit plus every outstanding idle-injection flush (not just the `disposed` status flip), unregisters the agent, removes its session from the store, and finally unwinds its scoped world. This order captures every agent-started `session/flush` before the session is detached and keeps scoped listeners alive through those checkpoints. `ctx.agents.get(id)` still returns a bare `Agent`; the ACP bridge and in-process subagent backends hold consumer handles, while config-created agents are already owned by the loop fiber.
 
 ### Live events
 
 `dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
 
-The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist, but concrete driving remains locked until the immediately following `agent/session-start`; that non-vetoing notification is the first supported startup injection point. `agent/disposed` runs after the driver is quiescent and the agent leaves the registry, while ordered teardown may still be detaching its session and unwinding its scope.
+The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
-Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the owner-final exception: it runs after ordinary continuation and steering folding, and its terminal state remains through turn close and flush so steering from those later listeners cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in [the agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#owner-final-policy-boundaries).
+Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the owner-final exception: it runs after ordinary continuation and steering folding, and its terminal state remains through turn close and flush so steering from those later listeners cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#owner-final-policy-four-narrow-boundaries).
 
 Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md).
 
@@ -39,8 +39,8 @@ Turn and step boundaries and the model token stream are durable `session/event`
 
 The handle every plugin programs against:
 
-- `agent.send(content, options?)` — queue a message; starts a turn when idle
-- `agent.steer(content, options?)` — steer a running turn (inject between steps); behaves like `send` when idle
+- `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content).
+- `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle
 - `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
 - `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.

packages/core/agent/src/dispatch.ts

@@ -1,5 +1,14 @@
 /**
- * Fused scope-carrier dispatch for agent-subject events, plus the assembly context builder.
+ * Fused scope-carrier dispatch for agent-subject operations, plus the assembly
+ * context builder. The sanctioned ordinary spelling is
+ * `agentEvents(ctx, agent).waterfall('agent/request', …)`: it builds the scope
+ * carrier ({@link scopeTarget} keyed by the agent) AND injects the subject as
+ * the first argument in one move, so a site cannot name a different subject.
+ * The registry lifecycle pair is the deliberate exception: `enter()` captures
+ * one stable carrier before commit and `announce()`/detach dispatch through it
+ * directly, so both lifecycle edges use the same routing identity. The dev
+ * scoped-dispatch invariant checks both shapes.
+ *
  * @module @deepseek-ai/dsh-agent/dispatch
  */
 
@@ -37,7 +46,10 @@ type Tail<K extends AgentSubjectEvent> = Params<Events[K]> extends [Agent, ...in
  */
 export interface AgentEventDispatch {
   /**
-   * Fire-and-forget notification (Cordis `emit`) in the agent's scope.
+   * Fire-and-forget notification in the agent's scope. Every listener is
+   * invoked; synchronous throws and returned-promise rejections are logged and
+   * contained per listener, so a notification cannot veto lifecycle progress
+   * or starve a later observer.
    * @param name - the agent-subject event to emit.
    * @param rest - the event's arguments after the injected agent.
    */
@@ -49,16 +61,6 @@ export interface AgentEventDispatch {
    * @returns the serial chain's result (the first bail value, if any).
    */
   serial<K extends AgentSubjectEvent>(name: K, ...rest: Tail<K>): Promise<Awaited<Return<Events[K]>>>
-  /**
-   * Await listeners in order and return the first value other than `undefined`.
-   * Unlike Cordis `serial`, this does not silently treat `null` or `false` as
-   * abstentions. Use it for a runtime-validated public boundary whose declared
-   * abstention is exactly `undefined` (currently `agent/turn-stop`).
-   * @param name - the agent-subject event to dispatch.
-   * @param rest - the event's arguments after the injected agent.
-   * @returns the first non-undefined listener result, or undefined.
-   */
-  strictSerial<K extends AgentSubjectEvent>(name: K, ...rest: Tail<K>): Promise<Awaited<Return<Events[K]>>>
   /**
    * Around-middleware dispatch (Cordis `waterfall`) in the agent's scope. The
    * declared event parameters already end with the `next` callback, so `rest`
@@ -81,32 +83,35 @@ export interface AgentEventDispatch {
  */
 export function agentEvents(ctx: Context, agent: Agent): AgentEventDispatch {
   const carrier: Scoped<Agent> = scopeTarget(agent, agent)
-  // The ordinary dispatch methods forward through Cordis' variadic mixins.
+  // The ordinary dispatch methods forward through Cordis' variadic mixins. The
+  // fused (carrier, name, agent, ...rest) tuple is provably a valid argument
+  // list for the matching thisArg overload, but TypeScript cannot relate the
+  // generic Tail<K> spread back to that overload's conditional parameter
+  // tuple — hence one contained, shape-preserving cast per method.
   return {
     emit(name, ...rest) {
-      // eslint-disable-next-line @typescript-eslint/unbound-method -- the events mixin accessor returns a pre-bound function
-      const emit = ctx.emit as (thisArg: Scoped<Agent>, name: string, ...args: unknown[]) => void
-      emit(carrier, name, agent, ...rest)
+      // Cordis emit invokes callbacks through Array.map: one synchronous throw
+      // starves later listeners, and returned promises are discarded. Agent
+      // notifications are non-vetoing, so resolve the same filtered callback
+      // set ourselves and contain both failure modes independently.
+      const args: unknown[] = [carrier, name, agent, ...rest]
+      const callbacks = ctx.events.dispatch('emit', args)
+      for (const callback of callbacks) {
+        try {
+          const returned: unknown = callback(...args)
+          void Promise.resolve(returned).catch((error: unknown) => {
+            ctx.logger.warn(`agent event "${name}" listener rejected: ${String(error)}`)
+          })
+        } catch (error: unknown) {
+          ctx.logger.warn(`agent event "${name}" listener threw: ${String(error)}`)
+        }
+      }
     },
     async serial(name, ...rest) {
       // eslint-disable-next-line @typescript-eslint/unbound-method -- the events mixin accessor returns a pre-bound function
       const serial = ctx.serial as (thisArg: Scoped<Agent>, name: string, ...args: unknown[]) => Promise<never>
       return await serial(carrier, name, agent, ...rest)
     },
-    strictSerial(name, ...rest) {
-      return (async (): Promise<unknown> => {
-        // EventsService.dispatch applies the carrier filter and emits the same
-        // internal/dispatch instrumentation as ctx.serial, then mutates `args` down to the
-        // actual listener parameters.
-        const args: unknown[] = [carrier, name, agent, ...rest]
-        const callbacks = ctx.events.dispatch('serial', args)
-        for (const callback of callbacks) {
-          const result: unknown = await callback(...args)
-          if (result !== undefined) return result
-        }
-        return undefined
-      })() as Promise<Awaited<Return<Events[typeof name]>>>
-    },
     waterfall(name, ...rest) {
       // eslint-disable-next-line @typescript-eslint/unbound-method -- the events mixin accessor returns a pre-bound function
       const waterfall = ctx.waterfall as (thisArg: Scoped<Agent>, name: string, ...args: unknown[]) => never

packages/core/agent/src/index.ts

@@ -5,8 +5,9 @@
  * @module @deepseek-ai/dsh-agent
  */
 
-import { Context, Service } from 'cordis'
+import { Context, getTraceable, Service, symbols } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent, AgentId, AgentOptions } from './types.ts'
 
@@ -39,35 +40,52 @@ declare module 'cordis' {
  */
 export interface CreateAgentOptions {
   /** The agent's id (the registry handle). */
-  agentId: AgentId
+  readonly agentId: AgentId
   /** The live session's id (NOT derived from agentId). */
-  sessionId: SessionId
+  readonly sessionId: SessionId
   /**
    * Session creation metadata: validated absolute `cwd`, `parentSession`
    * fork lineage, and the `seedLength` seed boundary. Mirrors the
    * `cwd`/`parentSession`/`seedLength` fields of
    * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
    * `createdAt`, used when reconstructing a persisted session, is deliberately
-   * excluded — a factory caller never sets it).
+   * excluded — a factory caller never sets it). This is durable session data,
+   * so the session boundary validates and snapshots it before asynchronous
+   * setup begins.
    */
-  meta?: { cwd?: string; parentSession?: SessionId; seedLength?: number }
+  readonly meta?: { readonly cwd?: string; readonly parentSession?: SessionId; readonly seedLength?: number }
   /**
    * Seed events to reconstruct the child session's log from (the fork lineage
    * primitive). When present, the factory creates the session with this event
    * prefix so `deriveMessages()`/`lastTurnNumber` continue from it — used by the
    * in-process FORK subagent backend to seed a child with a balanced
    * completed-turn prefix of the parent's log. The prefix MUST be contiguous
-   * from seq 0 and balanced (no open turn/step, no dangling tool-call), or the
-   * session constructor (and the dev-mode invariants replay) reject it. Absent
-   * for a fresh (spawn) child.
+   * from seq 0, carry only lossless-JSON data, and be balanced (no open
+   * turn/step, no dangling tool-call), or the session constructor (and the
+   * dev-mode invariants replay) reject it. The factory passes the raw seed to
+   * the session's durable validator/snapshot boundary. Absent for a fresh
+   * (spawn) child.
    */
-  seed?: SessionEvent[]
+  readonly seed?: readonly SessionEvent[]
   /** Per-agent options (model, …). */
-  agentOptions?: AgentOptions
+  readonly agentOptions?: AgentOptions
+  /** Optional creation-only cancellation signal; detached before the returned handle becomes visible. */
+  readonly signal?: AbortSignal
   /**
-   * Creation-time composition of the agent's scoped world.
+   * Creation-time composition of the agent's scoped world. The factory awaits
+   * setup after minting `agentCtx` but BEFORE inserting or announcing either
+   * the session or agent, so observers can never see a partially configured
+   * world. Everything registered through `agentCtx` (scoped tools, prompt
+   * sections/variables, `restrict()`, listeners, awaited child plugins) exists
+   * before `session/created`, `agent/created`, `agent/session-start`, and the
+   * first prompt assembly. A throw/rejection or owner disposal rolls the scope
+   * back without publishing either id.
+   *
+   * **Setup composes, it never drives**: the callback is trusted same-process
+   * code and receives the full scoped context, so this is a contract rather
+   * than a runtime restriction. Drive the agent only after creation resolves.
    */
-  setup?: (agentCtx: Context) => Promise<void> | void
+  readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
 
 /**
@@ -76,26 +94,42 @@ export interface CreateAgentOptions {
  */
 export interface ResumeAgentOptions {
   /** The agent's id (the registry handle). */
-  agentId: AgentId
+  readonly agentId: AgentId
   /** The persisted session id to load and resume on. */
-  resumeSessionId: SessionId
+  readonly resumeSessionId: SessionId
   /** Per-agent options (model, …). */
-  agentOptions?: AgentOptions
+  readonly agentOptions?: AgentOptions
+  /** Optional creation-only cancellation signal for persistence load/setup; detached before return. */
+  readonly signal?: AbortSignal
   /**
    * Resume-time composition of the agent's fresh scoped world. Persistence is
    * loaded first; the factory then mints `agentCtx` and awaits setup while the
    * reconstructed session and agent remain unpublished. The callback has the
-   * same composition-only contract as {@link CreateAgentOptions.setup}: all
-   * registrations exist before either creation announcement, driving verbs are
-   * unavailable until the session-start boundary, and rejection or owner
-   * disposal rolls the transaction back without publishing either id.
+   * same trusted composition-only contract as
+   * {@link CreateAgentOptions.setup}: all registrations exist before either
+   * creation announcement, and rejection or owner disposal rolls the
+   * transaction back without publishing either id.
    */
-  setup?: (agentCtx: Context) => Promise<void> | void
+  readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
 
 /**
- * An owned agent plus its disposer, returned by {@link AgentRegistry.create} / {@link
- * AgentRegistry.resume}.
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit and every outstanding
+ * idle-injection flush (quiescence — NOT just the `disposed`
+ * status flip), unregisters the agent, removes its session from the store, and
+ * finally unwinds its scoped world. This order captures every agent-started
+ * `session/flush` before the session is detached and keeps scoped listeners
+ * alive through those checkpoints.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
  */
 export interface AgentHandle {
   agent: Agent
@@ -110,27 +144,55 @@ export interface AgentHandle {
  */
 export interface AgentFactory {
   /**
-   * Create a new agent on a caller-supplied session id.
-   *
+   * Create a new agent on a caller-supplied session id. Async because creation
+   * awaits unpublished setup, inserts both session and agent, emits their
+   * creation notifications in order, emits `agent/session-start`, and only
+   * then starts the loop. The sequence is
+   * rollback-covered, but notifications delivered before a later listener
+   * failure remain observable; every agent or session creation announcement
+   * that began is paired by `agent/disposed` or `session/disposed` during
+   * rollback. The owner disposes the resolved handle to stop/drain,
+   * unregister, remove the session, and unwind the scope.
+   * The registry passes a context carrying the `create()` caller's fiber and
+   * scope as `ownerCtx`. The implementation attaches the unpublished
+   * transaction and resulting lifecycle to that owner; it must not infer
+   * ownership from the factory object's registration context.
+   * @param ownerCtx - caller-bound context that owns the transaction and live handle.
    * @param options - agent/session identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
    */
-  createAgent(options: CreateAgentOptions): Promise<AgentHandle>
+  createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
   /**
    * Load a persisted session and resume an agent on it. Async because it awaits
    * both `ctx.sessionPersistence.load` and the optional unpublished setup
    * transaction; must be called after that service exists (consumers inject
-   * `sessionPersistence`). Publication and drive unlocking follow the same
-   * ordered boundary as {@link createAgent}.
+   * `sessionPersistence`). Publication follows the same ordered boundary as
+   * {@link createAgent}.
+   * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
    * @param options - persisted identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
    */
-  resume(options: ResumeAgentOptions): Promise<AgentHandle>
+  resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
 }
 
 /** Thrown when create/resume is called before an agent factory is registered. */
 const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plugin)'
 
+/** All mutable lifecycle state for one exact registry entry. */
+interface AgentEntry {
+  readonly id: AgentId
+  readonly agent: Agent
+  readonly carrier: Scoped<Agent>
+  announced: boolean
+  announcing: boolean
+  detachRequested: boolean
+}
+
+/** Plain holder prevents Cordis from tracing the factory field before the caller context is known. */
+interface FactorySlot {
+  readonly target: AgentFactory
+}
+
 /**
  * Agent registry (`ctx.agents`): tracks live agents so UI, hook, and
  * orchestrator plugins can find them without depending on the concrete loop
@@ -139,22 +201,28 @@ const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plug
  * {@link setFactory}.
  */
 export class AgentRegistry extends Service {
-  private store = new Map<AgentId, Agent>()
-  /** Entries whose `agent/created` announcement phase began. */
-  private announced = new WeakSet<Agent>()
-  private factory: AgentFactory | undefined
+  private store = new Map<AgentId, AgentEntry>()
+  private entries = new WeakMap<Agent, AgentEntry>()
+  private factory: FactorySlot | undefined
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
-    // The `ctx.agent` DX accessor: default `undefined` on every context, so a plain plugin
-    // context reads cleanly instead of hitting the Cordis unknown-property throw.
+    // The `ctx.agent` DX accessor: default `undefined` on every context, so a
+    // plain plugin context reads cleanly instead of hitting the Cordis
+    // unknown-property throw. Each Agent.ctx shadows it with an own property
+    // (own properties resolve before the context proxy is consulted), so the
+    // accessor body never needs to resolve a scope itself. Effect-scoped:
+    // unwinds with this service's fiber.
     ctx.accessor('agent', { get: () => undefined })
   }
 
   /**
    * Register the agent-creation factory (the loop calls this on construction,
-   * effect-scoped). Throws if a factory is already registered. Returns the
-   * disposer; on dispose the factory slot is cleared.
+   * effect-scoped). A traced Cordis service is canonicalized to its concrete
+   * target; each create/resume call is then traced through that caller's
+   * context so ownership follows the caller without stacking proxy layers.
+   * Throws if a factory is already registered. Returns the disposer; on
+   * dispose the factory slot is cleared.
    * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
    * @returns the disposer that clears the factory slot. The exact
    *   Cordis effect disposer (single-shot): composite (generator) effects may
@@ -163,13 +231,26 @@ export class AgentRegistry extends Service {
   setFactory(factory: AgentFactory): () => Promise<void> | void {
     const dispose = this.ctx.effect(() => {
       if (this.factory !== undefined) throw new Error('an agent factory is already registered')
-      this.factory = factory
+      // Avoid stacking two Cordis shadow layers when a caller passes a Service
+      // already read through a context. Calls are re-traced through their
+      // actual owner context below.
+      const target = (factory as AgentFactory & { [symbols.original]?: AgentFactory })[symbols.original] ?? factory
+      this.factory = { target }
       return () => { this.factory = undefined }
     }, 'agents.setFactory()')
-    // Return the exact Cordis disposer to preserve teardown nesting.
+    // The exact cordis effect disposer (the agents.register() convention): a
+    // caller's composite effect can yield it for in-order teardown; the
+    // loop's constructor effect returns it directly, identity-nesting the
+    // registration under that effect.
     return dispose
   }
 
+  /** Return the active creation factory. */
+  private requireFactory(): FactorySlot {
+    if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
+    return this.factory
+  }
+
   /**
    * Create and publish a new agent through the registered factory.
    * Distinct from {@link register} (which records an already-constructed
@@ -180,8 +261,15 @@ export class AgentRegistry extends Service {
    * @returns the handle after setup, rollback-covered publication, and loop start complete.
    */
   async create(options: CreateAgentOptions): Promise<AgentHandle> {
-    if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
-    return this.factory.createAgent(options)
+    const ownerCtx = this.ctx
+    // Re-trace a Service-backed factory through the accessing context
+    // explicitly. This preserves AgentLoop's dependency origin while binding
+    // its effects to ownerCtx; plain factories receive ownerCtx as an explicit
+    // capability and need no Cordis tracker magic.
+    const { target } = this.requireFactory()
+    const receiver = getTraceable(ownerCtx, target)
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Reflect.apply intentionally supplies the caller-traced receiver
+    return Reflect.apply(target.createAgent, receiver, [ownerCtx, options])
   }
 
   /**
@@ -192,16 +280,30 @@ export class AgentRegistry extends Service {
    * @returns the handle after setup, rollback-covered publication, and loop start complete.
    */
   async resume(options: ResumeAgentOptions): Promise<AgentHandle> {
-    if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
-    return this.factory.resume(options)
+    const ownerCtx = this.ctx
+    const { target } = this.requireFactory()
+    const receiver = getTraceable(ownerCtx, target)
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Reflect.apply intentionally supplies the caller-traced receiver
+    return Reflect.apply(target.resume, receiver, [ownerCtx, options])
   }
 
   /**
-   * Register a live agent.
-   *
+   * Register a live agent. Throws if an agent with the same id is already
+   * registered. Emits `agent/created` on registration and `agent/disposed`
+   * when the calling fiber is disposed — both with the agent's scope carrier
+   * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+   * emits are scope-filtered regardless of which context invoked `register`
+   * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+   * requires passing the carrier). Returns the disposer.
    * @param agent - the already-constructed agent to record in the store.
-   * @returns the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined
-   *   without awaiting an in-flight teardown).
+   * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+   *   returns undefined without awaiting an in-flight teardown). Exact
+   *   identity is load-bearing: a composite (generator) effect that owns a
+   *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+   *   function so Cordis nests the unregistration at that yield position;
+   *   yielding a wrapper would leave it disposing as a concurrent sibling on
+   *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+   *   while its final turn is still draining.
    */
   register(agent: Agent): () => Promise<void> | void {
     const dispose = this.ctx.effect(function* (this: AgentRegistry) {
@@ -219,25 +321,72 @@ export class AgentRegistry extends Service {
    * calling {@link announce}. Ordinary callers use {@link register}.
    * @param agent - the prepared, unpublished agent.
    * @returns an idempotent closure that removes this exact entry and emits
-   *   `agent/disposed` with listener failures contained.
+   *   `agent/disposed` with listener failures contained. When called from a
+   *   synchronous `agent/created` listener, removal and disposal wait until
+   *   that creation dispatch unwinds.
    */
   enter(agent: Agent): () => void {
-    if (this.store.has(agent.id)) {
-      throw new Error(`agent "${agent.id}" is already registered`)
+    const id = agent.id
+    const carrier = scopeTarget(agent, agent)
+    // This is the authoritative collision boundary. Concurrent create/resume
+    // operations may both prepare, but only one exact entry can publish.
+    if (this.entries.has(agent) || this.store.has(id)) throw new Error(`agent "${id}" is already registered`)
+    const entry: AgentEntry = {
+      id,
+      agent,
+      carrier,
+      announced: false,
+      announcing: false,
+      detachRequested: false,
     }
-    this.store.set(agent.id, agent)
+    this.store.set(id, entry)
+    this.entries.set(agent, entry)
     let entered = true
-    return () => {
+    const detach = (): void => {
       if (!entered) return
       entered = false
-      this.store.delete(agent.id)
-      // An insertion rolled back before announce was never externally created, so emitting
-      // disposed would invent an impossible lifecycle edge.
-      if (!this.announced.delete(agent)) return
+      // Every callback reached by this creation dispatch must observe the same
+      // live entry, and disposal must follow creation. A listener may own
+      // the advanced detach capability, so make that ordering structural:
+      // visibility and the paired disposal are deferred until announce()'s
+      // synchronous dispatch has unwound.
+      if (entry.announcing) {
+        entry.detachRequested = true
+        return
+      }
+      this.detachEntered(entry)
+    }
+    return detach
+  }
+
+  /** Remove one exact entered agent and emit its paired disposal when announced. */
+  private detachEntered(entry: AgentEntry): void {
+    entry.detachRequested = false
+    // A stale capability can never delete a later same-id lifecycle. The
+    // captured entry identity is the final boundary.
+    /* v8 ignore next -- enter() rejects replacement while this single-shot detach capability is live. */
+    if (this.store.get(entry.id) !== entry) return
+    this.store.delete(entry.id)
+    this.entries.delete(entry.agent)
+    // An insertion rolled back before announce was never externally created,
+    // so emitting disposed would invent an impossible lifecycle edge. Marking
+    // happens before the created emit: if a later created listener throws,
+    // earlier listeners may already have observed it and must see disposal.
+    if (!entry.announced) return
+    this.emitDisposed(entry)
+  }
+
+  /** Emit the paired disposal edge through the entry's stable carrier. */
+  private emitDisposed(entry: AgentEntry): void {
+    const args: unknown[] = [entry.carrier, 'agent/disposed', entry.agent]
+    for (const callback of this.ctx.events.dispatch('emit', args)) {
       try {
-        this.ctx.emit(scopeTarget(agent, agent), 'agent/disposed', agent)
+        const returned: unknown = callback(...args)
+        void Promise.resolve(returned).catch((error: unknown) => {
+          this.ctx.logger.warn(`agent "${entry.id}": agent/disposed listener rejected: ${String(error)}`)
+        })
       } catch (error: unknown) {
-        this.ctx.logger.warn(`agent "${agent.id}": agent/disposed listener threw: ${String(error)}`)
+        this.ctx.logger.warn(`agent "${entry.id}": agent/disposed listener threw: ${String(error)}`)
       }
     }
   }
@@ -245,14 +394,37 @@ export class AgentRegistry extends Service {
   /**
    * Announce an agent previously inserted with {@link enter}.
    * @param agent - the live inserted agent to announce.
-   * @throws if `agent` is not the exact live registry entry for its id.
+   * @throws if `agent` is not the exact live registry entry for its id, or its
+   *   creation announcement already began (including a reentrant call from a
+   *   creation listener).
    */
   announce(agent: Agent): void {
-    if (this.store.get(agent.id) !== agent) {
+    const entry = this.entries.get(agent)
+    if (entry === undefined || this.store.get(entry.id) !== entry) {
       throw new Error(`agent "${agent.id}" is not live in this registry`)
     }
-    this.announced.add(agent)
-    this.ctx.emit(scopeTarget(agent, agent), 'agent/created', agent)
+    if (entry.announced || entry.announcing) {
+      throw new Error(`agent "${entry.id}" was already announced`)
+    }
+    // Mark before dispatch so a listener cannot recursively create a second
+    // lifecycle edge; detach still pairs a partially delivered first edge.
+    entry.announcing = true
+    entry.announced = true
+    const args: unknown[] = [entry.carrier, 'agent/created', entry.agent]
+    try {
+      for (const callback of this.ctx.events.dispatch('emit', args)) {
+        // A synchronous creation failure vetoes publication and rolls back.
+        // Returned-promise rejection happens after this synchronous boundary, so
+        // observe and report it instead of leaking an unhandled rejection.
+        const returned: unknown = callback(...args)
+        void Promise.resolve(returned).catch((error: unknown) => {
+          this.ctx.logger.warn(`agent "${entry.id}": agent/created listener rejected: ${String(error)}`)
+        })
+      }
+    } finally {
+      entry.announcing = false
+      if (entry.detachRequested) this.detachEntered(entry)
+    }
   }
 
   /**
@@ -261,7 +433,7 @@ export class AgentRegistry extends Service {
    * @returns the agent, or undefined when no live agent has that id.
    */
   get(id: AgentId): Agent | undefined {
-    return this.store.get(id)
+    return this.store.get(id)?.agent
   }
 
   /**
@@ -269,7 +441,7 @@ export class AgentRegistry extends Service {
    * @returns a fresh array; mutating it does not affect the registry.
    */
   list(): Agent[] {
-    return [...this.store.values()]
+    return [...this.store.values()].map(entry => entry.agent)
   }
 }
 

packages/core/agent/src/types.ts

@@ -1,7 +1,47 @@
 /**
- * Agent interface and event taxonomy. Every plugin programs against the `Agent` handle defined
- * here; the concrete implementation lives in `@deepseek-ai/dsh-agent-loop`.
- * Scope-filtered dispatch: keyed to `agent`.
+ * Agent interface and event taxonomy. Every plugin programs against the
+ * `Agent` handle defined here; the concrete implementation lives in
+ * `@deepseek-ai/dsh-agent-loop`.
+ *
+ * Merge-extensible: `AgentOptions` supports declaration merging for
+ * plugin-specific creation options.
+ *
+ * ## Event-domain semantics (the boundary rule)
+ *
+ * The harness has three event domains, each with one job:
+ *
+ * - **`session/*`** (`@deepseek-ai/dsh-session`) — the DURABLE, replayable FACT
+ *   log. Owns `SessionEventMap`; every entry is JSON-only (no live objects).
+ *   One `session/event` emit per append, plus the `session/flush` parallel
+ *   durability checkpoint. Answers "what happened, durably/replayably." A
+ *   consumer that wants the live transcript subscribes here.
+ * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the
+ *   live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/
+ *   `agent/request`/`agent/session-prefix`/`agent/step-result`/
+ *   `agent/turn-continuation` waterfalls and the serial `agent/pre-step` /
+ *   `agent/turn-stop` checkpoints) that mutate/veto, and TRANSIENT emits
+ *   (`agent/status`, `agent/error`, `agent/created`/
+ *   `agent/disposed`, `agent/queued`, `agent/session-start`)
+ *   that notify with the `Agent` in hand. Turn/step boundaries are NOT here —
+ *   they are durable `session/event` records. Answers "right now, with the agent
+ *   object — intercept or observe."
+ * - **`tools/*`** (`@deepseek-ai/dsh-tools`) — the tool registry + execution.
+ *
+ * **The rule:** a durable, replayable fact is a SessionEvent; a live
+ * interception or a transient/live-object signal is an `agent`/`tools` Cordis
+ * event. A turn/step boundary is a durable fact: it lives in the session log
+ * and is read off the `session/event` feed — it is NOT mirrored as an `agent/*`
+ * emit. A consumer that needs the `Agent` handle (or its short id) at a boundary
+ * keeps a session-id→agent map from `agent/created`/`agent/disposed`.
+ * See `docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md`
+ * and `docs/rfc/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md`.
+ *
+ * The interception waterfalls here (`agent/prompt-submit`, `agent/request`,
+ * `agent/step-result`, `agent/turn-continuation`) each return a typed Decision;
+ * the terminal serial `agent/turn-stop` returns the stop-only subset. The
+ * convention is pinned by
+ * `docs/rfc/implemented/feature/2026-06-30-interception-seams.md`.
+ *
  * @module @deepseek-ai/dsh-agent/types
  */
 
@@ -70,22 +110,54 @@ export interface SendOptions {
  */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
-/** Model-facing injected context with an explicit, non-defaulted source. */
+/**
+ * Model-facing context an interception listener wants the agent to SEE on the
+ * next request — the canonical shape behind every "inject extra context"
+ * decision ({@link PromptDecision}, {@link PostToolDecision},
+ * {@link ContinuationDecision}). It is `agent.inject()`ed as a
+ * `context/message`, so it carries a REQUIRED {@link MessageSource}: `inject()`
+ * defaults a missing source to `{kind:'user'}`, which would MISLABEL plugin
+ * context as a user prompt and corrupt derived history. A bridge sets
+ * `{kind:'plugin', plugin:'…'}`; a native plugin names itself. Required, not
+ * optional — the label is load-bearing, never defaulted here.
+ */
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
 }
 
 /**
- * The decision an {@link Agent} `agent/prompt-submit` waterfall listener returns for one
- * drained queued message, before it becomes a `user/message`. Maps onto the Claude Code
- * `UserPromptSubmit` hook's allow/block + `additionalContext`.
+ * The decision an {@link Agent} `agent/prompt-submit` waterfall listener returns
+ * for ONE drained queued message, before it becomes a `user/message`. Maps onto
+ * the Claude Code `UserPromptSubmit` hook's allow/block + `additionalContext`.
+ *
+ * - `allow` proceeds with the prompt; optional `content` REPLACES the prompt
+ *   bytes (a rewrite), and optional `additionalContext` is `inject()`ed as a
+ *   separate `context/message` the next request also sees.
+ * - `block` drops the prompt (it never becomes a `user/message`); `reason` is
+ *   the durable record of why. The loop appends a `prompt/blocked` session event
+ *   (carrying the original content, source, and `reason`) in place of the
+ *   dropped `user/message`, so the veto survives replay even in a MIXED batch
+ *   where a sibling prompt is allowed. A batch whose EVERY prompt is blocked
+ *   additionally opens a zero-step turn that ends with {@link TurnEndReason}
+ *   `rejected` (so the boundary stays balanced and a UI can render "blocked by
+ *   hook").
  */
 export type PromptDecision =
   | { kind: 'allow'; content?: ContentBlock[]; additionalContext?: HookContext }
   | { kind: 'block'; reason: string }
 
-/** Continuation override; a continue reason is recorded as next-step steering. */
+/**
+ * The decision an {@link Agent} `agent/turn-continuation` waterfall listener
+ * returns. The loop computes the default (`continue` when the step had tool
+ * calls or steering was injected, else `stop`); listeners override it to
+ * force-continue (`/goal`, `/loop`) or force-stop (budget guards).
+ *
+ * A `continue` may carry a `reason`: model-facing context recorded as next-STEP
+ * steering within the SAME turn (the loop enqueues it through the steering
+ * channel, so the continued turn's next step sees it). This is the typed twin of
+ * the existing "steer from a step/end listener" `/goal` pattern.
+ */
 export type ContinuationDecision =
   | { action: 'stop' }
   | { action: 'continue'; reason?: HookContext }
@@ -130,140 +202,333 @@ export interface Agent {
    */
   readonly ctx: Context
 
-  /** Queue a user message. Starts a turn when idle; otherwise waits for the next turn. */
+  /**
+   * Queue a user message. Starts a turn when idle; otherwise waits for the next
+   * turn. Content and the resolved source are accepted as one detached,
+   * deeply-frozen lossless-JSON record before notification or enqueue, so
+   * caller or `agent/queued` listener in-place mutation cannot change later
+   * log/model input. Throws synchronously when either value is not losslessly
+   * JSON-serializable; `agent/prompt-submit` may still return an explicit
+   * replacement.
+   */
   send(content: ContentBlock[], options?: SendOptions): void
 
   /**
    * Steer a running turn: content is injected between steps of the current
-   * turn. When idle, behaves like {@link send}.
+   * turn. Uses the same owned-value and synchronous-validation boundary as
+   * {@link send}; when idle, behaves exactly like that method.
    */
   steer(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Inject in-session context (file-change notices, skill content, cron notifications, …):
-   * appends a `context/message` session event the next model request sees at its chronological
-   * position, rendered as tagged synthetic context rather than a user prompt. Does not run the
-   * model.
+   * Inject in-session context (file-change notices, skill content, cron
+   * notifications, …): appends a `context/message` session event the next model
+   * request sees at its chronological position, rendered as tagged synthetic
+   * context rather than a user prompt. Does not run the model.
+   *
+   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
+   * an inject while idle wraps its `context/message` in a one-shot `injection`
+   * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
+   * durability, so every event stays inside a turn and a persistence backend
+   * never loses a between-turn notice. The idle checkpoint is fire-and-forget
+   * from this synchronous method, but lifecycle disposal awaits it before
+   * unregistering the agent or detaching its session. A failing flush is
+   * reported via `agent/error` (step `0`) and the logger, never thrown into the
+   * caller.
+   *
+   * Live-adapter review has validated the tagged-envelope rendering against
+   * current DeepSeek behavior; provider-specific mismatches belong in that
+   * adapter, not in the canonical session vocabulary.
    */
   inject(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Cancel ALL pending work for the agent. `cancel()`.
+   * Cancel ALL pending work for the agent. `cancel()`:
+   *
+   * - clears the queued FIFO (un-started prompts never run) and the steering
+   *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
+   * - aborts the in-flight step if one is running (the turn ends `aborted`);
+   * - drops a turn that is about to start (a `cancel()` landing in the
+   *   pre-step window — after a `send()` queued but before the loop flips to
+   *   `running`, or after `running` is emitted but before the first step) so
+   *   that queued prompt does not run and cannot be batched into the cancelled
+   *   turn.
+   *
+   * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state.
+   * `cancel()` on an idle agent with nothing queued or running is a safe no-op
+   * — it does NOT arm anything that would drop a later legitimate prompt.
    */
   cancel(reason?: string): void
 
   /**
-   * Resolve once the agent has reached quiescence after settling out of `running`, or
-   * immediately if it is already idle with no queued work.
+   * Resolve once the agent has reached quiescence after settling out of
+   * `running`, or immediately if it is already idle with no queued work. A
+   * non-owner's quiescence-observation hook: a consumer that does NOT own the
+   * agent's lifecycle awaits this to proceed only after queued/running work has
+   * fully stopped, rather than returning while the driver is still streaming or
+   * about to start a queued turn — without itself tearing the agent down. (A
+   * lifecycle OWNER does not need it: `AgentHandle.dispose()` already awaits the
+   * loop-exit promise directly as part of stopping and unregistering. So this is
+   * for a non-owning observer — e.g. a test awaiting a turn to settle, or a
+   * monitor — that wants the settle signal but must not dispose the agent.)
+   *
+   * "Quiescence", not merely "status changed": a disposed agent emits
+   * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop
+   * has unwound — so `whenIdle()` resolving on `disposed` must wait for the loop
+   * to actually exit (the implementation chains the loop-exit promise), not just
+   * observe the status flip. A mid-step disposal that never reaches `idle` still
+   * unblocks the await this way.
    */
   whenIdle(): Promise<void>
 
-  // Subagent backends create ordinary child Agent handles through the subagent seam.
+  // Subagent delegation is realized on top of this interface by the
+  // `@deepseek-ai/dsh-subagent` seam, not by a method here: a backend creates
+  // the child through `ctx.agents.create` (fork seeds the child Session with a
+  // balanced prefix of the parent's log via `CreateAgentOptions.seed`; spawn
+  // starts fresh) and drives it as an ordinary Agent handle, so steer() and
+  // event subscription work uniformly. See docs/core-data-structures/subagent.md.
 }
 
 declare module 'cordis' {
   interface Events {
     // ---- lifecycle (emit) ----
     /**
-     * An agent's fully composed scoped world was published in the {@link AgentRegistry}.
-     *
+     * An agent's fully composed scoped world was published in the
+     * {@link AgentRegistry}. Its session is already live in the session store.
+     * Setup is composition-only by contract; the subsequent
+     * `agent/session-start` boundary is the first supported place to inject or
+     * queue startup work. A synchronous listener throw
+     * vetoes publication and rollback emits the matching disposal edges;
+     * returned-promise rejection is observed and logged but cannot
+     * retroactively veto this synchronous boundary. A synchronous listener
+     * that requests the advanced registry detach does not remove the entry
+     * immediately: removal and the paired `agent/disposed` edge wait until the
+     * creation dispatch unwinds, so no later creation listener observes a
+     * disposal that preceded its own creation callback.
      * @param agent - the newly registered agent with its live session and completed setup.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/created'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * An agent was removed from the registry after its driver and any in-flight turn
-     * reached quiescence.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
-     * @param agent - the deregistered agent; its driving handle is now inert.
+     * An agent was removed from the registry. The concrete AgentLoop lifecycle
+     * emits this only after its driver and any in-flight turn reach quiescence;
+     * a custom agent registered through the public registry owns its own driver
+     * contract, which the registry cannot infer. Ordered teardown may still be
+     * detaching the session and unwinding scoped registrations when this runs.
+     * @param agent - the exact agent removed from the registry.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * Agent status changed (`idle` ⇄ `running`, or → `disposed`).
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive
+     * lifecycle off this transition, never off a status you just requested —
+     * `send()` does not flip status to `running` before it returns.
      * @param agent - the agent whose status flipped.
      * @param status - the status just entered (the transition's destination).
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
     /**
-     * A message entered the agent's inbox (queued or steering). `source` is the resolved
-     * source (defaults applied), not the caller's raw options.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * A message entered the agent's inbox (queued or steering). Content and the
+     * resolved source are the detached, deeply-frozen values retained by the
+     * inbox. `source` has defaults applied and is not the caller's raw options.
      * @param agent - the agent whose inbox received the message.
-     * @param content - the enqueued content blocks, verbatim.
-     * @param info - the resolved source plus whether it entered as steering.
+     * @param content - the accepted content blocks retained by the inbox.
+     * @param info - the accepted source plus whether it entered as steering.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
 
     // ---- session lifecycle (emit) ----
     /**
-     * The agent's session lifecycle began, fired once before its first turn. `source` says why
-     * ({@link SessionStartSource}: fresh startup, a resumed persisted session, …).
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * The agent's session lifecycle began, fired once before its first turn.
+     * `source` says why ({@link SessionStartSource}: fresh startup, a resumed
+     * persisted session, …). A pure NOTIFICATION (emit, not waterfall): a
+     * listener cannot veto by returning a decision or throwing. A listener that
+     * wants to seed context does so via `agent.inject()` (a `context/message` the
+     * first request sees). A lifecycle owner can still dispose its structural
+     * ownership edge during this notification; publication rechecks liveness and
+     * then aborts before the driver starts.
      * @param agent - the agent whose session lifecycle began.
      * @param source - why the session started (fresh startup, resume, …).
-     * Dispatch is scoped to `agent`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 
-    // Turn and step boundaries are not mirrored as agent/* emits: a consumer that needs them
-    // reads the durable `turn/start`/`turn/end`/`step/start`/ `step/end` session events off the
-    // `session/event` feed (the session log is the live transcript feed).
+    // Turn and step boundaries are NOT mirrored as agent/* emits: a consumer
+    // that needs them reads the durable `turn/start`/`turn/end`/`step/start`/
+    // `step/end` session events off the `session/event` feed (the session log is
+    // the live transcript feed). See the module doc's three-domain rule and the
+    // "remove agent boundary mirror events" RFC.
 
     // ---- step/request extension seams (serial + waterfall) ----
     /**
-     * Awaited checkpoint for surface mutation before `step/start` snapshots request history.
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Awaited pre-step surface-mutation checkpoint, fired once per step AFTER
+     * `turn/start` (and after the prior step closed) but BEFORE this step's
+     * `step/start` — so anything a listener appends lands OUTSIDE the step,
+     * between `turn/start`/`step/end` and the upcoming `step/start`. `step` is
+     * the number of the step about to start. The loop awaits
+     * `ctx.serial('agent/pre-step', …)` after assembling the system prompt, then
+     * opens the step and derives the request history ONCE from whatever the
+     * surface now holds. This is where compaction belongs: it mutates the session
+     * surface in place (shadowing an older range with a summary node) with its
+     * log-only `compact/*` records cleanly outside any step, and the single
+     * subsequent derive reflects the mutation — so there is no double-derive and
+     * no listener can see (or be expected to act on) an assembled `messages`
+     * array that does not exist yet.
+     *
+     * Serial (awaited in registration order), not a waterfall: a listener
+     * mutates the surface as a side effect; there is nothing to transform, but
+     * the loop must wait for the mutation to complete before opening the step
+     * and deriving. Cordis `serial` bails early if a listener returns a bail
+     * value; this event is typed and documented as `void`, so listeners must not
+     * return a semantic veto value. `fullSystemPrompt` is the assembled prompt a
+     * listener needs to measure pressure (the system prompt counts toward the
+     * budget), and `sessionPrefix` is the instance's composed
+     * {@link agent/session-prefix} product for the same reason — every request
+     * carries it in front of the derived history, and it is composed BEFORE
+     * this seam fires precisely so a pressure gate counts the prefix the
+     * request will actually send (never a stale logged one). `signal` cancels
+     * any in-flight work a listener starts (e.g. a
+     * summarization model call).
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @param agent - the agent about to open the step.
-     * @param turn - open turn number.
-     * @param step - upcoming step number.
+     * @param turn - the already-open turn this step belongs to.
+     * @param step - the number of the step about to start.
      * @param fullSystemPrompt - the assembled prompt, for measuring token pressure.
-     * @param sessionPrefix - frozen prefix for the same measurement.
+     * @param sessionPrefix - the instance's frozen session prefix, for the same measurement.
      * @param signal - aborts in-flight listener work when the turn is torn down.
      * @mode serial
      */
-    // TODO: move prompt-pressure inputs behind compaction if no second consumer appears.
+    // TODO: `fullSystemPrompt`/`sessionPrefix` are a smell on a generic
+    // per-step seam — compaction
+    // is their only consumer, so a wide event carries payloads just one listener
+    // reads. Revisit if no second consumer appears: e.g. hand listeners a lazy
+    // prompt provider, or move token-pressure measurement behind a
+    // compaction-specific seam instead of the shared pre-step checkpoint.
     'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
     /**
-     * Waterfall: decide what happens to one drained queued message before it becomes a
-     * `user/message` — allow (optionally rewriting the prompt bytes or attaching
-     * `additionalContext`) or block it.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Waterfall: decide what happens to ONE drained queued message before it
+     * becomes a `user/message` — allow (optionally rewriting the prompt bytes or
+     * attaching `additionalContext`) or block it. Fires inside the already-open
+     * turn, per drained message. Maps onto Claude Code's `UserPromptSubmit` hook.
+     * Call `next()` to delegate to the default (allow unchanged), or return a
+     * {@link PromptDecision} without calling `next()` to short-circuit.
      * @param agent - the agent draining its inbox.
      * @param content - the drained message's blocks, as queued.
      * @param source - the message's resolved source.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode waterfall
      */
     'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>
     /**
-     * Waterfall: shape the step's call configuration — model switching, sampling overrides
-     * — by returning a replacement {@link LlmCallConfig} (the frozen seed is the config the
-     * loop would otherwise use).
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Waterfall: shape the step's call configuration — model switching,
+     * sampling overrides — by returning a replacement {@link LlmCallConfig}
+     * (the frozen seed is the config the loop would otherwise use). Config is
+     * ALL a listener shapes here: every request is a pure function of the
+     * session log (the reconstructability RFC), so model-visible content
+     * flows through the log channels — `inject()`, steering, prompt-submit
+     * `additionalContext`, prompt sections via `system-prompt/assemble`, or
+     * the header-logged session prefix via {@link agent/session-prefix}
+     * — never through request mutation, and the loop records whatever config
+     * the request actually uses as a `request/header*` event before dispatch.
+     * The step's messages are already snapshotted when this fires (the
+     * `step/start` boundary): an `inject()` from a listener here lands in the
+     * log but joins the NEXT request. For surface mutation that must precede
+     * the snapshot (compaction), use {@link agent/pre-step}. Call `next()` to
+     * delegate, or return an {@link LlmCallConfig} without it to
+     * short-circuit.
      * @param agent - the agent making the model call.
      * @param turn - the open turn number.
      * @param step - the step whose request this is.
-     * @param config - the config the loop would use (frozen); return a replacement to
-     *   switch.
+     * @param config - the config the loop would use (frozen); return a replacement to switch.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode waterfall
      */
     'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
     /**
-     * Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the
-     * entire derived history (directly after the provider's system slot) on every request this
-     * loop instance sends.
+     * Waterfall: compose the SESSION PREFIX — request-only messages placed in
+     * front of the ENTIRE derived history (directly after the provider's
+     * system slot) on every request this loop instance sends. Fired ONCE per
+     * loop instance, lazily before its first step's {@link agent/pre-step}
+     * seam — BEFORE the pre-step so a token-pressure gate (compaction) counts
+     * the prefix this instance will actually send, never a previous
+     * instance's logged one. The composed
+     * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the
+     * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused
+     * verbatim for every subsequent request — never recomputed mid-session,
+     * so the provider prefix cache holds by construction (a process restart
+     * or `ctx.agents.resume()` is a new instance: it recomposes, and any
+     * drift lands attributably on the `'resume'` snapshot). Composition runs
+     * outside the step, before the boundary snapshot: a composing listener's
+     * session append joins the CURRENT request's derived history. A
+     * composition interrupted by a cancel/dispose landing inside the
+     * waterfall is discarded — never cached, logged, or sent — and the next
+     * turn recomposes under a live signal, so an abort-aware listener's
+     * degraded fallback cannot leak into later requests.
      *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * This is the home for session-stable openers the model must always see
+     * but that must NOT become durable history — a skills catalog, an
+     * AGENTS.md digest, a workspace baseline: `Session.deriveMessages()`
+     * never returns the prefix, and the header events are its only durable
+     * record, so the request stays reconstructable from the log. Content
+     * that CHANGES mid-session belongs in the append-only history channels
+     * instead — `agent.inject()`, a `tools/post-execute` decision's
+     * `additionalContext`, prompt-submit `additionalContext` — each a
+     * durable `context/message` paid once and prefix-cached thereafter.
+     *
+     * The seed is a frozen empty list; a contributing listener returns a NEW
+     * array — never an in-place push. The canonical contribution is a
+     * PREPEND, `[mine, ...await next()]`: the waterfall unwinds
+     * innermost-first (the LAST-registered listener's `next()` resolves
+     * first), so prepending yields registration order on the wire, and every
+     * plugin using it composes deterministically. The append form
+     * `[...await next(), mine]` is legal but places a contribution AFTER
+     * every later-registered plugin's — reverse registration order when all
+     * contributors append. Call `next()` to
+     * delegate, or return a list without it to short-circuit.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @param agent - the agent whose session prefix is being composed.
      * @param prefix - the frozen empty seed; return an extended replacement to contribute.
      * @param signal - aborts in-flight listener work (e.g. a discovery scan) when the step is torn down.
@@ -271,49 +536,71 @@ declare module 'cordis' {
      */
     'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
     /**
-     * Waterfall: post-process the assembled assistant {@link Message} before tool dispatch
-     * (validation, content rewriting, …).
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Waterfall: post-process the assembled assistant {@link Message} before
+     * tool dispatch (validation, content rewriting, …).
      * @param agent - the agent that received the step's response.
      * @param turn - the open turn number.
      * @param step - the step that produced the message.
      * @param message - the assistant message as assembled from the stream.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode waterfall
      */
     'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
     /**
-     * Waterfall: override the turn-continuation decision via a typed {@link
-     * ContinuationDecision}.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Waterfall: override the turn-continuation decision via a typed
+     * {@link ContinuationDecision}. The loop's `defaultDecision` is `continue`
+     * when the step had tool calls or steering was injected, else `stop`.
+     * Listeners force-continue (`/goal`, `/loop` — optionally attaching a
+     * `reason` recorded as next-step steering) or force-stop (budget guards).
+     * Call `next()` to delegate to the default, or return a decision to override.
      * @param agent - the agent deciding whether to run another step.
      * @param turn - the turn being continued or stopped.
      * @param defaultDecision - what the loop would do absent an override.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode waterfall
      */
     'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
     /**
-     * Serial terminal-stop checkpoint after the ordinary `agent/turn-continuation` waterfall,
-     * any `continue.reason`, and the pending-steering continuation override have been folded.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * Serial terminal-stop checkpoint after the ordinary
+     * `agent/turn-continuation` waterfall, any `continue.reason`, and the
+     * pending-steering continuation override have been folded. A listener
+     * returns `{ action: 'stop' }` to make this turn terminal, or `undefined`
+     * to abstain. Terminal stop is monotonic: listener order and steering
+     * cannot resume the turn, and pending steering is discarded rather than
+     * becoming another step or turn. A malformed non-undefined result fails
+     * the turn closed.
      * @param agent - the agent whose composed continuation outcome may be stopped.
      * @param turn - the turn at its terminal-stop checkpoint.
-     * Dispatch is scoped to `agent`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode serial
      */
     'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): Promise<ContinuationStop | undefined> | ContinuationStop | undefined
 
     // ---- error notifications (emit) ----
     /**
-     * A step or turn errored.
-     *
-     * Scope-filtered dispatch: keyed to `agent`.
+     * A step or turn errored. The loop reports a failure here (plus the logger)
+     * even when the error has no in-turn position for a session `error` event.
      * @param agent - the agent whose turn errored.
      * @param turn - the turn in which the failure surfaced.
      * @param step - the step at which the failure surfaced.
      * @param error - the failure, verbatim.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
+     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
+     * plain plugin context fires for every agent. The dispatch `this` is the
+     * scope carrier (`Scoped<Agent>`), built by the emitting side via
+     * `scopeTarget`/`agentEvents`.
      * @mode emit
      */
     'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void

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

@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
+import { Context, Service, symbols } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { AgentId, agentEvents } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentFactory, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent'
 
 function stubAgent(rawId: string): Agent {
   const id = AgentId(rawId)
@@ -10,8 +11,6 @@ function stubAgent(rawId: string): Agent {
     options: {},
     session: new Session(SessionId(`${id}-session`)),
     status: 'idle',
-    // A bare context stands in for the agent scope: registry tests never
-    // register through it, they only need the field present.
     ctx: new Context(),
     send() {},
     steer() {},
@@ -22,150 +21,203 @@ function stubAgent(rawId: string): Agent {
 }
 
 describe('AgentRegistry', () => {
-  it('registers agents and emits created/disposed events', async () => {
+  it('registers exact entries, emits lifecycle events, and unregisters on owner disposal', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-
-    const created: string[] = []
-    const disposed: string[] = []
-    ctx.on('agent/created', agent => void created.push(agent.id))
-    ctx.on('agent/disposed', agent => void disposed.push(agent.id))
+    const lifecycle: string[] = []
+    ctx.on('agent/created', agent => void lifecycle.push(`created:${agent.id}`))
+    ctx.on('agent/disposed', agent => void lifecycle.push(`disposed:${agent.id}`))
 
     const agent = stubAgent('a1')
     const dispose = ctx.agents.register(agent)
-    expect(created).toEqual(['a1'])
-    expect(ctx.agents.get(AgentId('a1'))).toBe(agent)
+    expect(ctx.agents.get(agent.id)).toBe(agent)
     expect(ctx.agents.list()).toEqual([agent])
+    expect(() => ctx.agents.register(stubAgent('a1'))).toThrow(/already registered/)
 
     await dispose()
-    expect(disposed).toEqual(['a1'])
-    expect(ctx.agents.get(AgentId('a1'))).toBeUndefined()
+    expect(ctx.agents.get(agent.id)).toBeUndefined()
+    expect(lifecycle).toEqual(['created:a1', 'disposed:a1'])
   })
 
-  it('rejects duplicate ids and unregisters on fiber dispose (HMR safety)', async () => {
+  it('rolls an entry back and pairs a partially delivered creation when a listener throws', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-    ctx.agents.register(stubAgent('main'))
-    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('already registered')
+    const lifecycle: string[] = []
+    ctx.on('agent/created', agent => void lifecycle.push(`created:${agent.id}`))
+    ctx.on('agent/created', () => { throw new Error('creation veto') })
+    ctx.on('agent/disposed', agent => void lifecycle.push(`disposed:${agent.id}`))
 
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.agents.register(stubAgent('scoped'))
-    }, { inject: ['agents'] }))
-    expect(ctx.agents.list().map(a => a.id)).toEqual(['main', 'scoped'])
-
-    await fiber.dispose()
-    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+    expect(() => ctx.agents.register(stubAgent('vetoed'))).toThrow('creation veto')
+    expect(ctx.agents.get(AgentId('vetoed'))).toBeUndefined()
+    expect(lifecycle).toEqual(['created:vetoed', 'disposed:vetoed'])
   })
 
-  it('rolls back the agent entry when an agent/created listener throws (P1-1)', async () => {
+  it('contains asynchronous creation rejection and every disposal-listener failure', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
+    const warnings: string[] = []
+    const heard: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+    ctx.on('agent/created', () => Promise.reject(new Error('created async')) as never)
+    ctx.on('agent/disposed', () => { throw new Error('disposed sync') })
+    ctx.on('agent/disposed', () => Promise.reject(new Error('disposed async')) as never)
+    ctx.on('agent/disposed', agent => void heard.push(agent.id))
 
-    let threw = false
-    ctx.on('agent/created', () => {
-      if (!threw) { threw = true; throw new Error('boom created listener') }
-    })
-
-    // The throwing emit must roll the entry back, not leak it.
-    expect(() => ctx.agents.register(stubAgent('main'))).toThrow('boom created listener')
-    expect(ctx.agents.get(AgentId('main'))).toBeUndefined() // rolled back, not leaked
-
-    // A subsequent listener-free register of the SAME id succeeds and is
-    // tracked exactly once (the duplicate-id check is not wedged).
-    const dispose = ctx.agents.register(stubAgent('main'))
-    expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
+    const dispose = ctx.agents.register(stubAgent('contained'))
+    await Promise.resolve()
     await dispose()
-    expect(ctx.agents.get(AgentId('main'))).toBeUndefined()
+    await Promise.resolve()
+
+    expect(heard).toEqual(['contained'])
+    expect(warnings).toEqual([
+      'agent "contained": agent/created listener rejected: Error: created async',
+      'agent "contained": agent/disposed listener threw: Error: disposed sync',
+      'agent "contained": agent/disposed listener rejected: Error: disposed async',
+    ])
   })
 
-  it('splits insertion from announcement and makes the detach exact/idempotent', async () => {
+  it('separates entry from announcement and stale/idempotent detach cannot remove a replacement', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-    const created: Agent[] = []
-    const disposed: Agent[] = []
-    ctx.on('agent/created', agent => void created.push(agent))
-    ctx.on('agent/disposed', agent => void disposed.push(agent))
+    const lifecycle: string[] = []
+    ctx.on('agent/created', agent => void lifecycle.push(`created:${agent.id}`))
+    ctx.on('agent/disposed', agent => void lifecycle.push(`disposed:${agent.id}`))
 
     const first = stubAgent('split')
     const detachFirst = ctx.agents.enter(first)
-    expect(ctx.agents.get(first.id)).toBe(first)
-    expect(created).toEqual([])
+    expect(lifecycle).toEqual([])
     ctx.agents.announce(first)
-    expect(created).toEqual([first])
+    expect(() => { ctx.agents.announce(first) }).toThrow(/already announced/)
     detachFirst()
     detachFirst()
-    expect(disposed).toEqual([first])
 
     const replacement = stubAgent('split')
     const detachReplacement = ctx.agents.enter(replacement)
-    // A stale repeated detach cannot remove the replacement.
     detachFirst()
     expect(ctx.agents.get(replacement.id)).toBe(replacement)
     expect(() => { ctx.agents.announce(first) }).toThrow(/not live/)
     detachReplacement()
-    // The replacement was inserted but never announced, so rollback produces
-    // no disposed-without-created notification.
-    expect(disposed).toEqual([first])
+    expect(lifecycle).toEqual(['created:split', 'disposed:split'])
+  })
+
+  it('defers detach requested by a creation listener until that dispatch unwinds', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const order: string[] = []
+    const agent = stubAgent('reentrant')
+    ctx.on('agent/created', () => {
+      order.push(`first:${ctx.agents.get(agent.id) === agent}`)
+      detach()
+      order.push(`after-detach:${ctx.agents.get(agent.id) === agent}`)
+    })
+    ctx.on('agent/created', () => void order.push(`second:${ctx.agents.get(agent.id) === agent}`))
+    ctx.on('agent/disposed', () => void order.push('disposed'))
+    const detach = ctx.agents.enter(agent)
+    ctx.agents.announce(agent)
+    expect(order).toEqual(['first:true', 'after-detach:true', 'second:true', 'disposed'])
+    expect(ctx.agents.get(agent.id)).toBeUndefined()
+  })
+})
+
+describe('agentEvents()', () => {
+  it('contains each synchronous throw and returned-promise rejection', async () => {
+    const ctx = new Context()
+    const warnings: string[] = []
+    const heard: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+    const agent = stubAgent('event')
+    ctx.on('agent/status', () => { throw new Error('sync listener') })
+    ctx.on('agent/status', () => Promise.reject(new Error('async listener')) as never)
+    ctx.on('agent/status', (_agent, status) => void heard.push(status))
+
+    agentEvents(ctx, agent).emit('agent/status', 'running')
+    await Promise.resolve()
+    expect(heard).toEqual(['running'])
+    expect(warnings).toEqual([
+      'agent event "agent/status" listener threw: Error: sync listener',
+      'agent event "agent/status" listener rejected: Error: async listener',
+    ])
   })
 })
 
 describe('AgentRegistry factory seam', () => {
-  /** A stub AgentFactory that records calls and returns a stub agent. */
   function stubFactory() {
-    const calls: { create: unknown[]; resume: unknown[] } = { create: [], resume: [] }
-    const factory: import('@deepseek-ai/dsh-agent').AgentFactory = {
-      async createAgent(options) {
-        calls.create.push(options)
+    const calls: {
+      create: Array<{ ownerCtx: Context; options: CreateAgentOptions }>
+      resume: Array<{ ownerCtx: Context; options: ResumeAgentOptions }>
+    } = { create: [], resume: [] }
+    const factory: AgentFactory = {
+      async createAgent(ownerCtx, options) {
+        calls.create.push({ ownerCtx, options })
         return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
       },
-      resume(options) {
-        calls.resume.push(options)
-        return Promise.resolve({ agent: stubAgent(options.agentId), dispose: () => Promise.resolve() })
+      async resume(ownerCtx, options) {
+        calls.resume.push({ ownerCtx, options })
+        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
       },
     }
     return { factory, calls }
   }
 
-  it('create()/resume() throw when no factory is registered', async () => {
+  it('requires a factory and delegates through the calling context', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await expect(ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
-    await expect(ctx.agents.resume({ agentId: AgentId('a'), resumeSessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
-  })
-
-  it('setFactory registers a factory; create/resume delegate to it', async () => {
-    const ctx = new Context()
-    await ctx.plugin(AgentRegistry)
     const { factory, calls } = stubFactory()
     ctx.agents.setFactory(factory)
 
-    const created = await ctx.agents.create({ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } })
-    expect(created.agent.id).toBe('c1')
-    expect(calls.create).toEqual([{ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } }])
-
-    const resumed = await ctx.agents.resume({ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') })
-    expect(resumed.agent.id).toBe('r1')
-    expect(calls.resume).toEqual([{ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') }])
-  })
-
-  it('setFactory rejects a second factory', async () => {
-    const ctx = new Context()
-    await ctx.plugin(AgentRegistry)
-    ctx.agents.setFactory(stubFactory().factory)
-    expect(() => ctx.agents.setFactory(stubFactory().factory)).toThrow(/already registered/)
-  })
-
-  it('disposing the setFactory fiber clears the factory (HMR safety)', async () => {
-    const ctx = new Context()
-    await ctx.plugin(AgentRegistry)
-    let dispose!: () => Promise<void> | void
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      dispose = inner.agents.setFactory(stubFactory().factory)
+    let callerFiber: Context['fiber'] | undefined
+    await ctx.plugin(Object.assign(async (inner: Context) => {
+      callerFiber = inner.fiber
+      await inner.agents.create({ agentId: AgentId('create'), sessionId: SessionId('create-s') })
+      await inner.agents.resume({ agentId: AgentId('resume'), resumeSessionId: SessionId('resume-s') })
     }, { inject: ['agents'] }))
-    await expect(ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).resolves.toBeDefined()
-    void dispose
-    await fiber.dispose()
-    // factory slot cleared → create throws again
-    await expect(ctx.agents.create({ agentId: AgentId('a2'), sessionId: SessionId('s2') })).rejects.toThrow(/no agent factory/)
+    expect(calls.create[0]?.ownerCtx.fiber).toBe(callerFiber)
+    expect(calls.resume[0]?.ownerCtx.fiber).toBe(callerFiber)
+  })
+
+  it('rejects a second factory and clears the slot with its owner (HMR)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const owner = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.agents.setFactory(stubFactory().factory)
+      expect(() => inner.agents.setFactory(stubFactory().factory)).toThrow(/already registered/)
+    }, { inject: ['agents'] }))
+    await expect(ctx.agents.create({ agentId: AgentId('before'), sessionId: SessionId('before-s') })).resolves.toBeDefined()
+    await owner.dispose()
+    await expect(ctx.agents.create({ agentId: AgentId('after'), sessionId: SessionId('after-s') })).rejects.toThrow(/no agent factory/)
+  })
+
+  it('canonicalizes an already traced Service before tracing it for the caller', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const states = new WeakMap<object, string[]>()
+    class TracedFactory extends Service implements AgentFactory {
+      constructor(inner: Context) {
+        super(inner, 'tracedFactory')
+        states.set(this, [])
+      }
+      private calls(): string[] {
+        const original = (this as unknown as { [symbols.original]?: TracedFactory })[symbols.original] ?? this
+        const calls = states.get(original)
+        if (calls === undefined) throw new Error('factory receiver was not canonicalized')
+        return calls
+      }
+      async createAgent(_ownerCtx: Context, options: CreateAgentOptions) {
+        this.calls().push('create')
+        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+      }
+      async resume(_ownerCtx: Context, options: ResumeAgentOptions) {
+        this.calls().push('resume')
+        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+      }
+    }
+    await ctx.plugin(TracedFactory)
+    const traced = (ctx as Context & { tracedFactory: TracedFactory }).tracedFactory
+    ctx.agents.setFactory(traced)
+    await ctx.agents.create({ agentId: AgentId('create'), sessionId: SessionId('create-s') })
+    await ctx.agents.resume({ agentId: AgentId('resume'), resumeSessionId: SessionId('resume-s') })
+    const raw = (traced as unknown as { [symbols.original]?: TracedFactory })[symbols.original]
+    expect(states.get(raw!)).toEqual(['create', 'resume'])
   })
 })