Merge latest master into post-step recovery

Combine agent initiator scoping and exact Cordis JSDoc inspection with post-step compaction and bounded request recovery.

Regenerate the Cordis and website API catalogs, and classify the recovery and compaction types required by the current catalog link-coverage gate.

website/zh-CN/api/harness/events.md

@@ -11,6 +11,16 @@ Every event the harness packages declare on the cordis event bus (42 total), gro
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
@@ -25,6 +35,14 @@ A fully configured agent and live session were published. Setup is composition-o
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * 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
+ */
 'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
@@ -39,6 +57,16 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * 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`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void
 ```
 
@@ -56,6 +84,17 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 **Mode:** `serial`
 
 ```ts website-api
+/**
+ * Awaited serial checkpoint after the response, real or synthetic tool
+ * results, injected context, and steering are durable but before `step/end`.
+ * A cancelled tool batch reaches this checkpoint with an aborted signal.
+ * @param agent - the agent whose step is settling.
+ * @param turn - the open turn number.
+ * @param step - the open step number.
+ * @param signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
 'agent/post-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
 ```
 
@@ -73,6 +112,17 @@ Awaited serial checkpoint after the response, real or synthetic tool results, in
 **Mode:** `serial`
 
 ```ts website-api
+/**
+ * Awaited serial checkpoint before `step/start`; appends land outside the
+ * pending step and are included when the loop derives request history.
+ * `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.
+ * @param step - the pending step number.
+ * @param signal - the turn abort signal.
+ * @mode serial
+ */
 'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
 ```
 
@@ -90,6 +140,15 @@ Awaited serial checkpoint before `step/start`; appends land outside the pending
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Allow, rewrite, or block one drained prompt before it becomes a user
+ * message. Call `next()` for the unchanged default.
+ * @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`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
@@ -106,6 +165,15 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Detached, frozen content entered the agent's inbox. Source defaults have
+ * already been applied, so these are the exact values retained for the log.
+ * @param agent - the agent whose inbox received the message.
+ * @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`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
 ```
 
@@ -122,6 +190,17 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Replace the frozen call configuration. Model-visible content must use
+ * logged channels; this seam cannot mutate messages. Injection here joins
+ * the next request because the current step boundary is already fixed.
+ * @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.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
@@ -139,6 +218,19 @@ Replace the frozen call configuration. Model-visible content must use logged cha
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Recover a model-request failure after its failed step has closed. `retry`
+ * opens a new numbered step; `fail` preserves the original request error.
+ * Call `next()` to delegate to the next recovery listener or the default.
+ * @param agent - the agent whose request failed.
+ * @param turn - the open turn number.
+ * @param step - the failed step number.
+ * @param error - the original model-request failure.
+ * @param retryAttempt - zero-based number of prior recovery retries.
+ * @param signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, retryAttempt: number, signal: AbortSignal, next: () => Promise<RequestErrorDecision>): Promise<RequestErrorDecision>
 ```
 
@@ -158,6 +250,20 @@ Recover a model-request failure after its failed step has closed. `retry` opens
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Compose request-only messages placed before derived history. The frozen
+ * result is computed once per loop instance, logged on its anchoring request
+ * header, and reused so the provider prefix remains stable. Interrupted
+ * composition is discarded. Composition precedes the first `agent/pre-step`
+ * and request boundary, so listener appends join the current request.
+ * Changing context belongs in history; contributors should prepend to
+ * `await next()` to preserve registration order.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param agent - the agent whose session prefix is being composed.
+ * @param prefix - the frozen seed; return an extended replacement.
+ * @param signal - aborts composition when the step is torn down.
+ * @mode waterfall
+ */
 'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
 ```
 
@@ -174,6 +280,16 @@ Compose request-only messages placed before derived history. The frozen result i
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
@@ -189,6 +305,14 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
+ * not enter `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
@@ -204,6 +328,16 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * 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`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
 ```
 
@@ -221,6 +355,15 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Override whether the turn continues. The default continues after tool
+ * calls or steering and stops otherwise; a continue reason becomes steering.
+ * @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`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
 ```
 
@@ -237,6 +380,15 @@ Override whether the turn continues. The default continues after tool calls or s
 **Mode:** `serial`
 
 ```ts website-api
+/**
+ * Monotonic terminal-stop checkpoint after continuation and steering are
+ * 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.
+ * @mode serial
+ */
 'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
 ```
 
@@ -254,6 +406,15 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
+ * @mode emit
+ */
 'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
@@ -271,6 +432,13 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
 'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
 ```
 
@@ -287,6 +455,13 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
@@ -302,6 +477,14 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
 'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
 ```
 
@@ -318,6 +501,14 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
@@ -335,6 +526,17 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request arrives
+ *   deep-frozen (mutation throws): its content is a pure function of the
+ *   session log (the reconstructability RFC), so listeners read it, never
+ *   rewrite it. A hand-built one-shot (compaction summarize) is the
+ *   caller's own object and stays mutable here.
+ * @mode waterfall
+ */
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
@@ -351,6 +553,17 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
@@ -365,6 +578,15 @@ Creation announcement during session publication. A synchronous throw vetoes and
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
@@ -379,6 +601,17 @@ Emitted once when an announced session leaves the store, including publication r
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
@@ -394,6 +627,15 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 **Mode:** `parallel`
 
 ```ts website-api
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Dispatch through
+ * {@link SessionStore.flush}. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
@@ -410,6 +652,14 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A ready child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
@@ -424,6 +674,11 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
@@ -438,6 +693,11 @@ A provider became resolvable in the registry.
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
 'subagent/provider-removed'(name: string): void
 ```
 
@@ -452,6 +712,16 @@ A provider left the registry. Accepted runs remain holder-owned.
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider established a ready child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and ready child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
@@ -468,6 +738,14 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Expert waterfall over the assembled sections, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
 'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
 ```
 
@@ -483,6 +761,11 @@ Expert waterfall over the assembled sections, tools, and variables. Scope-filter
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
 'system-prompt/change'(): void
 ```
 
@@ -497,6 +780,15 @@ Emitted when any prompt provider changes. This registry notification is unfilter
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
 'tools/change'(): void
 ```
 
@@ -509,6 +801,14 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
 'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
 ```
 
@@ -523,6 +823,14 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
 'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
 ```
 
@@ -538,6 +846,13 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
 'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
 ```
 
@@ -552,6 +867,13 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
 'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
@@ -569,6 +891,16 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
 ```
 
@@ -584,6 +916,15 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * One `agent()` call established a ready child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a ready run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
 ```
 
@@ -599,6 +940,15 @@ One `agent()` call established a ready child run. Paired with Events['workflow/a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
 ```
 
@@ -614,6 +964,12 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
 'workflow/log'(info: WorkflowRunInfo, message: string): void
 ```
 
@@ -629,6 +985,13 @@ The script emitted a narration line (a `log(message)` call).
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
 'workflow/phase'(info: WorkflowRunInfo, title: string): void
 ```
 
@@ -644,6 +1007,12 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
 'workflow/start'(info: WorkflowRunInfo): void
 ```