Merge remote-tracking branch 'origin/codex/enforce-tool-cancellation' into worktree/explicit-turn-signal

# Conflicts:
#	docs/architecture.md
#	docs/cordis-catalog/events.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/agent.ts
#	packages/core/agent/README.md
#	packages/core/agent/src/types.ts
#	packages/ui/acp/src/index.ts
#	packages/ui/tui/src/index.ts
#	packages/ui/tui/tests/harness.ts

packages/core/agent-loop/README.md

@@ -56,7 +56,7 @@ The driver owns one agent for its lifetime and runs inside `ctx.agents.withIniti
 
 Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history.
 
-Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and `agent/post-step` remain ordinary turn failures. Recovery receives the exact live error, immutable provider facts, and immutable prior failures after the failed step closes. A retry rebuilds from the durable log in a new numbered step, success clears the consecutive history, and exhaustion records the structured failure once on `turn/end`. AgentLoop privately owns one cancellation holder whose explicit signal spans prompt policy, assembly, every step, model and tool work, recovery, continuation, and terminal stop; it retires the holder immediately before publishing `turn/end`, while the driver may remain `running` through the durability flush. `cancel()` accepts the typed runtime-only `user | parent` cause, clears pending work, and cooperatively aborts the holder without leaking to the next prompt; durable `turn/end` remains coarse `aborted`, and undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. Disposal wins terminal classification, and work that ignores the signal must settle before quiescence. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract. Terminal continuation stops remain authoritative through turn close and durability flush.
+Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and `agent/post-step` remain ordinary turn failures. Recovery receives the exact live error, immutable provider facts, and immutable prior failures after the failed step closes. A retry rebuilds from the durable log in a new numbered step, success clears the consecutive history, and exhaustion records the structured failure once on `turn/end`. AgentLoop privately owns one cancellation holder whose explicit signal spans prompt policy, assembly, every step, model and tool work, recovery, continuation, and terminal stop; it retires the holder immediately before publishing `turn/end`, while the driver may remain `running` through the durability flush. An effective `cancel()` emits the typed runtime-only `user | parent` cause before clearing pending work and cooperatively aborting the holder; notification failures cannot veto cancellation, work queued by a notification observer is cleared, work queued by a later abort observer belongs to the next turn, and idle cancellation emits nothing. Durable `turn/end` remains coarse `aborted`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. Disposal wins terminal classification, and work that ignores the signal must settle before quiescence. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract. Terminal continuation stops remain authoritative through turn close and durability flush.
 
 Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, then drains accepted batch context before the turn closes through the normal abort path.
 

packages/core/agent-loop/src/agent.ts

@@ -325,16 +325,20 @@ export class ReactLoopAgent implements Agent {
   }
 
   cancel(cause?: AgentCancelCause): void {
-    const reason = cause ?? { kind: 'user' }
+    const resolvedCause = cause ?? { kind: 'user' }
     const cancellation = this.turnCancellation
     const preRun = cancellation === undefined && (this.#inbox.hasQueued || this.#inbox.hasSteering)
-    if (preRun) {
-      this.preRunCancelled = true
+    if (cancellation !== undefined || preRun) {
+      if (preRun) this.preRunCancelled = true
+      // Coordination consumers must update their own state before this call
+      // clears the inbox or aborts the turn. Notification failures are
+      // contained by the fused dispatcher and cannot veto cancellation.
+      agentEvents(this.loopCtx, this).emit('agent/cancel-requested', resolvedCause)
     }
     // Clear work already present before abort observers run. A replacement
     // synchronously enqueued by an observer belongs to the next turn.
     this.#inbox.clear()
-    cancellation?.request(reason)
+    cancellation?.request(resolvedCause)
   }
 
   /**

packages/core/agent-loop/tests/cancel.spec.ts

@@ -6,7 +6,7 @@
  * @module dsh-agent-loop/tests/cancel
  */
 
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
@@ -54,6 +54,33 @@ function userTexts(agent: Agent): string[] {
 }
 
 describe('Agent.cancel()', () => {
+  it('notifies every observer before clearing work and contains listener failures', async () => {
+    const adapter = new MockAdapter([textResponse('must remain unused')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('cancel-event'), { provider: 'mock', model: 'mock' })
+    const warned = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const seen: string[] = []
+    ctx.on('agent/cancel-requested', (subject, cause) => {
+      if (subject !== agent) return
+      seen.push(`first:${cause.kind}`)
+      subject.send([{ type: 'text', text: 'queued by cancel observer' }])
+      throw new Error('observer failed')
+    })
+    ctx.on('agent/cancel-requested', (subject, cause) => {
+      if (subject === agent) seen.push(`second:${cause.kind}`)
+    })
+
+    send(agent, 'drop me')
+    agent.cancel()
+    await new Promise(resolve => setTimeout(resolve, 30))
+    agent.cancel({ kind: 'parent' })
+
+    expect(seen).toEqual(['first:user', 'second:user'])
+    expect(userTexts(agent)).toEqual([])
+    expect(adapter.requests).toHaveLength(0)
+    expect(warned).toHaveBeenCalledWith(expect.stringContaining('agent/cancel-requested'))
+  })
+
   it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
@@ -519,7 +546,7 @@ describe('Agent.cancel()', () => {
     dispose()
 
     // No step streamed (the model never ran), and the turn ended aborted with
-    // the CALLER's reason — the marker carries `cancel(reason)` through even
+    // the caller's cause — the marker carries `cancel(cause)` through even
     // though no AbortController observed it in this window.
     expect(streamed).toBe(false)
     expect(reasons).toEqual([{ kind: 'aborted' }])
@@ -786,7 +813,11 @@ describe('Agent.cancel()', () => {
     const flushStarted = Promise.withResolvers<undefined>()
     const releaseFlush = Promise.withResolvers<undefined>()
     let abortedDuringTurnEnd: boolean | undefined
+    let cancelNotifications = 0
 
+    ctx.on('agent/cancel-requested', (subject) => {
+      if (subject === agent) cancelNotifications += 1
+    })
     ctx.on('session/event', (session, event) => {
       if (session !== agent.session || event.type !== 'turn/end') return
       const signal = adapter.requests[0]?.signal
@@ -809,6 +840,7 @@ describe('Agent.cancel()', () => {
 
     expect(abortedDuringTurnEnd).toBe(false)
     expect(signal.aborted).toBe(false)
+    expect(cancelNotifications).toBe(0)
     expect(agent.session.events.findLast(event => event.type === 'turn/end')).toMatchObject({
       data: { reason: { kind: 'completed' } },
     })

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -529,7 +529,7 @@ describe('steering from late extension points is never stranded', () => {
     expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('one more thing')
   })
 
-  it('steer() from a step/end session-event listener forces a SAME-TURN next step (/goal pattern)', async () => {
+  it('steer() from a step/end session-event listener forces a SAME-TURN next step', async () => {
     // Assert the same-turn shape; content alone cannot distinguish re-enqueue.
     const adapter = new MockAdapter([
       textResponse('no tools, would stop'),