Merge remote-tracking branch 'origin/master' into worktree/tui-session-controls

# Conflicts:
#	docs/config-catalog.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	packages/ui/acp/src/index.ts
#	packages/ui/tui/README.md
#	packages/ui/tui/src/index.ts
#	packages/ui/tui/tests/harness.ts
#	packages/ui/tui/tests/plugin-shape.spec.ts
#	packages/ui/tui/tests/snapshots/disposed-terminal.expected.txt
#	packages/ui/tui/tests/snapshots/errors-and-help.expected.txt
#	packages/ui/tui/tests/tui.spec.ts

packages/core/agent/src/types.ts

@@ -25,7 +25,10 @@ export interface AgentOptions {
   model?: string
 }
 
-/** Message options; an omitted source resolves to `{ kind: 'user' }`, so plugins must label their own content. */
+/**
+ * Message options. An omitted source attests direct human input as `{ kind: 'user' }`
+ * and may authorize policy consumers, so non-human producers must label their content.
+ */
 export interface SendOptions {
   source?: MessageSource
 }
@@ -122,10 +125,10 @@ export interface Agent {
 
   /**
    * Clear all queued and steering work, including items waiting to start, and
-   * abort the active step. The supplied reason is preserved across pre-step
-   * and active cancellation windows, and `whenIdle()` resolves after
-   * cancellation reaches quiescence. Idle cancellation is a no-op and does not
-   * arm a later cancel.
+   * abort the active step. An effective call first emits `agent/cancel-requested`
+   * with the resolved reason. That reason is preserved across pre-step and active
+   * cancellation windows, and `whenIdle()` resolves after cancellation reaches
+   * quiescence. Idle cancellation is a no-op and does not arm a later cancel.
    */
   cancel(reason?: string): void
 
@@ -176,6 +179,16 @@ declare module 'cordis' {
      * @mode emit
      */
     'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
+    /**
+     * Effective broad cancellation was requested, before queued/steering work
+     * is cleared or the active step is aborted. This observe-only notification
+     * cannot veto cancellation; listener failures are contained.
+     * @param agent - the agent whose current work is being cancelled.
+     * @param reason - resolved cancellation reason, including the default.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @mode emit
+     */
+    'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, reason: string): void
 
     // ---- session lifecycle (emit) ----
     /**