docs: align prose with runtime contracts

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

@@ -934,11 +934,9 @@ describe('agent scope lifecycle', () => {
       order.push(`session-still-stored=${ctx.sessions.get(SessionId('o1-s')) !== undefined}`)
     })
 
-    // Open a turn so the drain has real work: the loop must finish it BEFORE
-    // the registry entry goes away (the agent/disposed contract: "its fiber
-    // and any in-flight turn have been torn down"). Wait for the turn to be
-    // OPEN in the log — a dispose landing in the pre-step window would drop
-    // the queued prompt without ever opening a turn.
+    // Open a turn so disposal must drain real work before registry removal.
+    // Waiting for turn/start avoids pre-step disposal dropping the queued prompt
+    // before a turn opens.
     const turnOpen = new Promise<void>((resolve) => {
       const off = ctx.on('session/event', (_s, event) => {
         if (event.type === 'turn/start') { off(); resolve() }

packages/core/agent/src/index.ts

@@ -170,6 +170,7 @@ export class AgentRegistry extends Service {
 
   /**
    * Create and publish an owned agent and session through the active factory.
+   * Rejects if no factory is registered or creation, setup, or publication fails.
    * @param options - agent id, session id/seed/metadata, and agent options.
    * @returns the handle after setup, rollback-covered publication, and loop start complete.
    */

packages/core/agent/src/types.ts

@@ -138,8 +138,9 @@ declare module 'cordis' {
      */
     'agent/created'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * An agent left the registry. AgentLoop emits this after driver quiescence;
-     * custom registry users own their driver-ordering contract.
+     * An agent left the registry; AgentLoop emits this after driver quiescence
+     * but before session detachment and scoped-registration unwind. Custom
+     * registry users own their driver-ordering contract.
      * @param agent - the exact agent removed from the registry.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
@@ -182,11 +183,12 @@ declare module 'cordis' {
 
     // ---- step/request extension seams (serial + waterfall) ----
     /**
-     * Awaited serial checkpoint after prompt assembly and before `step/start`.
-     * Listeners may mutate the session surface outside the pending step; the loop
-     * derives history once afterward, so compaction records and replacements are
-     * included without rewriting an assembled request. The prompt and prefix are
-     * the exact pressure inputs for that request, and `signal` cancels listener work.
+     * Awaited serial checkpoint for session-surface mutation after prompt
+     * assembly and before `step/start`; appends land outside the pending step.
+     * The loop derives history once afterward, so compaction records and
+     * replacements are included without rewriting an assembled request. The
+     * prompt and prefix are the exact pressure inputs for that request, and
+     * `signal` cancels listener work.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @param agent - the agent opening the step.
      * @param turn - the open turn number.
@@ -258,7 +260,8 @@ declare module 'cordis' {
     'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
     /**
      * Monotonic terminal-stop checkpoint after continuation and steering are
-     * folded. A stop discards pending steering.
+     * folded; a stop remains authoritative through turn close and flush:
+     * steering queued in that window is discarded, while ordinary sends survive.
      * @param agent - the agent whose composed continuation outcome may be stopped.
      * @param turn - the turn at its terminal-stop checkpoint.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.