feat(agent): add queue-aware Agent.cancel() primitive

abort() only kills the in-flight step, so a queued-but-not-yet-started prompt
ran to completion after a cancel and a prompt accepted right after could be
batched into the cancelled turn (the loop merges queued messages into one turn).
This closes TODO(rfc010-cancel-prestep) with a distinct cancel() verb.

cancel() clears the queued + steering FIFOs, aborts the in-flight step, and
drives a turn-scoped marker on the LoopHandle that the driver checks at EVERY
point a turn could start or continue:
- right after the idle wait (window 1): drop the about-to-run turn and settle
  whenIdle() waiters directly (no running→idle transition fires, and no
  agent/status is emitted, so an ACP listener can't see a spurious idle that
  resolves a freshly-queued prompt as cancelled);
- after the synchronous setStatus('running') emit (window 2): a running listener
  can cancel in the gap before runTurn;
- in the step-start window (before runStep, after setAbort): a synchronous
  turn-start/step-start listener can cancel before any AbortController exists;
- at the continuation gate: a cancel during the continuation waterfall (the
  finished step's controller already cleared) ends the turn aborted.

The marker is ARMED only when there is something to cancel (running, an
in-flight step, or queued/steering work) — an idle no-op cancel cannot leave it
set to drop a later prompt — and RESET unconditionally once per loop iteration,
so it governs exactly one turn and never leaks onto the next prompt (even when a
send() lands in the cancelled turn's flush window).

ACP session/cancel now maps to agent.cancel() (keeping the synchronous
settlePrompt). Teardown/disconnect still use abort('disposed') until PR D, so
the ACP README narrows the remaining best-effort window to teardown only.

Tests (agent-loop/cancel.spec.ts) cover every window unit-level (the F1 hang
guard: a whenIdle() waiter registered before a pre-step cancel resolves; the F2
leak guard: idle cancel then a prompt runs; mid-step, continuation, both
pre-step windows, turn-start-listener, steering-cleared, marker-reset). ACP
turns.spec.ts adds the through-bridge tests with NO intervening whenIdle (idle
cancel→prompt runs; mid-stream cancel→immediate next prompt runs) and updates
the stale pre-step test to the queue-aware guarantee. The existing cancel
snapshot golden is byte-identical (it drives the new cancel() path end-to-end
through the real subprocess), so no new golden is needed. 100% coverage.

packages/agent-loop/README.md

@@ -66,6 +66,8 @@ forever:
 
 Error containment: a throwing plugin ends the **turn**, never the loop. Dispose mid-turn emits `agent/status('disposed')` and ends with reason `disposed`. A step that hits the model's output-token ceiling makes the turn end `max-tokens` (the rule: any `max-tokens` step in the turn surfaces as `max-tokens`; `disposed`/`aborted`/`error` still take precedence) — distinct from a clean `completed` stop.
 
+Cancellation: `agent.abort()` aborts only the in-flight step; `agent.cancel()` is the broad verb — it clears the queued + steering FIFOs, aborts the in-flight step, and drives a turn-scoped marker the driver checks at every point a turn could start or continue (right after the idle wait, after the `running` flip, before each step, and at the continuation gate) so a turn about to start is dropped. A cancelled turn ends `aborted`; a queued-but-not-started prompt never runs and cannot be batched into the cancelled turn. The marker is reset once per loop iteration, so a cancel governs exactly one turn and never leaks onto a later prompt.
+
 ### What is NOT here
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:

packages/agent-loop/src/agent.ts

@@ -26,6 +26,14 @@ export class ReactLoopAgent implements Agent {
 
   private _status: AgentStatus = 'idle'
   private currentAbort: AbortController | undefined
+  /**
+   * Turn-scoped cancel marker, set by {@link cancel} and read/cleared by the
+   * driver loop (via the LoopHandle) at every point a turn could start or
+   * continue. Armed ONLY when there is something to cancel (a running turn, an
+   * in-flight step, or queued/steering work), so an idle no-op cancel cannot
+   * leave it set to wrongly drop a later prompt.
+   */
+  private cancelRequested = false
   private disposed: Promise<void>
   private resolveDisposed!: () => void
   /** Resolves when the driver loop has fully exited (tests/disposal). */
@@ -176,6 +184,30 @@ export class ReactLoopAgent implements Agent {
     this.currentAbort?.abort(reason ?? 'aborted')
   }
 
+  cancel(reason?: string): void {
+    // Arm-gate: only mark a cancellation when there is actually work to cancel —
+    // a running turn, an in-flight step, or queued/steering work. An idle cancel
+    // with nothing pending is a true no-op; arming the marker then would wrongly
+    // drop the NEXT legitimate prompt (the marker is consumed only at the loop's
+    // turn-decision points, which an idle parked loop does not reach until woken
+    // by a real send()). Note the gate canNOT be `status === 'running'` alone:
+    // the pre-step window (a send() queued but the loop not yet flipped to
+    // running) has status `idle` with `hasQueued` true, and the marker exists
+    // precisely to cover it.
+    if (this._status === 'running' || this.currentAbort !== undefined || this.inbox.hasQueued || this.inbox.hasSteering) {
+      this.cancelRequested = true
+    }
+    // Drop all pending queued + steering work (un-started prompts never run; the
+    // cancelled turn's steering is not re-enqueued). Cleared directly even when
+    // the loop is parked in waitForQueued — there is no turn to stop and nothing
+    // left for the parked loop to run, so no wake is needed.
+    this.inbox.clear()
+    // Interrupt an in-flight step immediately (the running turn observes the
+    // abort and ends `aborted`). The marker covers the windows where no step is
+    // running (pre-step, continuation).
+    this.currentAbort?.abort(reason ?? 'cancelled')
+  }
+
   /**
    * Resolve once the agent has reached quiescence after settling out of
    * `running`. If it is already disposed, awaits {@link done} (the loop-exit
@@ -218,6 +250,15 @@ export class ReactLoopAgent implements Agent {
       setAbort: controller => void (this.currentAbort = controller),
       disposed: this.disposed,
       isDisposed: () => this._status === 'disposed',
+      isCancelled: () => this.cancelRequested,
+      clearCancel: () => { this.cancelRequested = false },
+      // Settle whenIdle() waiters WITHOUT a status transition — the pre-step
+      // cancel-skip path drops the about-to-run turn and re-parks without ever
+      // flipping running→idle, so a waiter registered in the pre-step window
+      // (status idle, hasQueued was true) would otherwise hang. This emits no
+      // agent/status, so an ACP agent/status listener never sees a spurious idle
+      // that would resolve a freshly-queued prompt as cancelled.
+      settleIdle: () => { this.settleIdleWaiters() },
     })
     // The disposer must be infallible: it runs inside the fiber's LIFO
     // disposal chain, where a throw would skip later disposers (e.g. the

packages/agent-loop/src/inbox.ts

@@ -52,6 +52,16 @@ export class Inbox {
     return this.steeringMessages.splice(0)
   }
 
+  /**
+   * Discard all pending messages (queued + steering) without delivering them —
+   * used by `cancel()`, which drops un-started work rather than draining it into
+   * a turn. Unlike `drainQueued`/`drainSteering`, the messages are thrown away.
+   */
+  clear(): void {
+    this.queuedMessages.length = 0
+    this.steeringMessages.length = 0
+  }
+
   /** Wait until a queued message arrives or `cancel` resolves. */
   waitForQueued(cancel: Promise<void>): Promise<void> {
     if (this.hasQueued) return Promise.resolve()

packages/agent-loop/src/loop.ts

@@ -107,6 +107,26 @@ export interface LoopHandle {
   /** Resolves when the agent is disposed — unblocks the idle wait. */
   disposed: Promise<void>
   isDisposed(): boolean
+  /**
+   * Whether a `cancel()` is pending for the current turn. The driver checks this
+   * at every decision point where a turn could start or continue (right after
+   * the idle wait, after the `running` flip, before each step, and at the
+   * continuation gate) and drops the about-to-run / continuing turn. Reset once
+   * per loop iteration via {@link clearCancel} after the turn returns, so the
+   * marker governs exactly one cancellation and never leaks to a later prompt.
+   */
+  isCancelled(): boolean
+  /** Clear the cancel marker (called once per iteration after the turn returns). */
+  clearCancel(): void
+  /**
+   * Settle pending `whenIdle()` waiters WITHOUT a status transition. Used by the
+   * pre-step cancel-skip path: it drops the about-to-run turn and re-parks at the
+   * idle wait, so no `running→idle` transition fires to settle a `whenIdle()`
+   * waiter that was registered in the pre-step window — this settles it directly
+   * (it emits no `agent/status`, so an ACP `agent/status` listener never sees a
+   * spurious idle that would resolve a freshly-queued prompt as cancelled).
+   */
+  settleIdle(): void
 }
 
 /**
@@ -148,7 +168,33 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
     await agent.inbox.waitForQueued(handle.disposed)
     if (handle.isDisposed()) break
 
+    // Pre-step cancel (window 1): a `cancel()` landed after a `send()` woke the
+    // idle wait but before we flip to `running`. Drop the about-to-run turn: the
+    // queued/steering work is already cleared by `cancel()`, and we settle any
+    // `whenIdle()` waiter DIRECTLY (no status transition fires here, so the
+    // running→idle settle never runs) WITHOUT emitting `agent/status` (an ACP
+    // listener must not see a spurious idle that resolves a freshly-queued prompt
+    // as cancelled). Clear the marker and re-park.
+    if (handle.isCancelled()) {
+      handle.clearCancel()
+      handle.settleIdle()
+      continue
+    }
+
     handle.setStatus('running')
+
+    // Pre-step cancel (window 2): `setStatus('running')` emits `agent/status`
+    // SYNCHRONOUSLY, so a `running` listener can `cancel()` in the gap between the
+    // check above and `runTurn`. `cancel()` already cleared the queued FIFO, so
+    // drop the turn before it starts (runTurn would otherwise throw on an empty
+    // queue) and transition back to idle — `running` was already emitted, so a
+    // real `idle` transition (which also settles waiters) balances the status.
+    if (handle.isCancelled()) {
+      handle.clearCancel()
+      handle.setStatus('idle')
+      continue
+    }
+
     // Re-derive the turn number from the log each iteration (do NOT keep a local
     // counter): an idle `agent.inject()` can append its own one-shot turn while
     // the loop waits above, so the next real turn must continue from whatever
@@ -170,8 +216,18 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
       } catch { /* contained: a throwing agent/error listener must not kill the driver */ }
     }
 
+    // Reset the cancel marker UNCONDITIONALLY here, after the turn returns and
+    // before the next iteration's idle wait. NOT gated on the idle transition
+    // below: a `send()` that lands during the cancelled turn's flush window makes
+    // `hasQueued` true at the `setStatus('idle')` guard, so an idle-gated reset
+    // would never fire and the stale marker would wrongly drop that next prompt's
+    // turn. Resetting per iteration scopes the marker to exactly the turn that was
+    // cancelled.
+    handle.clearCancel()
+
     // Steering that arrived too late to join this turn (turn-end listeners,
-    // flush) becomes a queued message — it must never be stranded.
+    // flush) becomes a queued message — it must never be stranded. (A cancelled
+    // turn already cleared its steering, so there is nothing to re-enqueue.)
     for (const message of agent.inbox.drainSteering()) {
       agent.inbox.enqueue(message)
     }
@@ -323,6 +379,20 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
       const abort = new AbortController()
       handle.setAbort(abort)
 
+      // Cancel landing in the step-start window: a synchronous `agent/turn-start`
+      // or `agent/step-start` listener (both fire before this point) can have
+      // called `cancel()`, and `runStep` would otherwise run a full extra step
+      // with no AbortController having observed it. Check the marker AFTER
+      // setAbort (so the next-iteration drain sees a clean controller) and before
+      // `runStep`: drop the step, end the turn `aborted`. closeStep balances the
+      // already-appended step/start.
+      if (handle.isCancelled()) {
+        handle.setAbort(undefined)
+        reason = { kind: 'aborted', reason: 'cancelled' }
+        closeStep()
+        break
+      }
+
       let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error }
       try {
         stepOutcome = await runStep(ctx, agent, turn, step, abort.signal)
@@ -382,6 +452,16 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
       // next iteration's drain records it.
       if (!shouldContinue && agent.inbox.hasSteering) shouldContinue = true
 
+      // A cancel that landed during the continuation window — after the step's
+      // AbortController was cleared (setAbort(undefined)) but before the next
+      // step starts — has no controller to observe it, so the turn-scoped marker
+      // ends the turn here. cancel() also cleared the steering FIFO, so the
+      // override above did not re-arm continuation.
+      if (handle.isCancelled()) {
+        reason = { kind: 'aborted', reason: 'cancelled' }
+        break
+      }
+
       if (!shouldContinue || handle.isDisposed()) {
         /* v8 ignore next -- disposal during continuation-decision window is a narrow race; error-path disposal is covered elsewhere */
         if (handle.isDisposed()) reason = { kind: 'disposed' }

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

@@ -0,0 +1,279 @@
+/**
+ * Tests for the queue-aware `Agent.cancel()` primitive (PR C). `cancel()` is the
+ * broad verb — it clears queued + steering work, aborts an in-flight step, and
+ * drops a turn about to start — whereas `abort()` kills only the current step.
+ * These tests exercise every window where a cancel can land (idle, pre-step,
+ * mid-step, continuation) and the marker's arm/reset rules that keep a cancel
+ * from leaking to a later prompt or hanging `whenIdle()`.
+ *
+ * @module dsh-agent-loop/tests/cancel
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { TurnEndReason } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter) {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function send(agent: ReactLoopAgent, text: string) {
+  agent.send([{ type: 'text', text }])
+}
+
+/** Resolve on the agent's next idle transition (event-based, not status poll). */
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+/** All user-message texts recorded in the log (to assert what actually ran). */
+function userTexts(agent: ReactLoopAgent): string[] {
+  return agent.session.events
+    .filter(e => e.type === 'user/message')
+    .flatMap(e => e.type === 'user/message' ? e.data.content : [])
+    .flatMap(b => b.type === 'text' ? [b.text] : [])
+}
+
+describe('Agent.cancel()', () => {
+  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)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // The loop is parked at the idle wait with nothing queued. A cancel here must
+    // NOT arm the marker — otherwise the next legitimate prompt would be dropped.
+    agent.cancel('nothing to cancel')
+
+    send(agent, 'real prompt')
+    await waitForIdle(ctx, agent)
+
+    // The prompt ran: its user message is in the log and one turn completed.
+    expect(userTexts(agent)).toEqual(['real prompt'])
+    expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true)
+  })
+
+  it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => {
+    const adapter = new MockAdapter([textResponse('should not run')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // send() queues synchronously (status still idle, loop microtask not yet
+    // resumed). Cancel in that pre-step window: the queued turn must not run.
+    send(agent, 'drop me')
+    agent.cancel('pre-step')
+
+    // Give the loop a chance to wake and process the cancel.
+    await new Promise(r => setTimeout(r, 30))
+
+    // No turn was opened — the queued prompt was dropped, never recorded.
+    expect(userTexts(agent)).toEqual([])
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+    expect(agent.status).toBe('idle')
+  })
+
+  it('a whenIdle() waiter registered BEFORE a pre-step cancel resolves (F1 hang guard)', async () => {
+    const adapter = new MockAdapter([textResponse('x')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // Queue work, then register a whenIdle() waiter while in the pre-step window
+    // (status idle, hasQueued true) — it does NOT take the fast path. Then cancel.
+    // The skip path must settle this waiter directly (no running→idle transition
+    // ever fires), or it would hang forever.
+    send(agent, 'q')
+    const idle = agent.whenIdle()
+    agent.cancel('pre-step')
+
+    // Must resolve (not hang). A timeout makes the failure a clear test failure.
+    await Promise.race([
+      idle,
+      new Promise((_r, reject) => setTimeout(() => { reject(new Error('whenIdle hung after pre-step cancel')) }, 1000)),
+    ])
+    expect(agent.status).toBe('idle')
+  })
+
+  it('cancel() mid-step aborts the in-flight model call; the turn ends aborted', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_a, _t, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await new Promise(r => setTimeout(r, 30))
+    expect(agent.status).toBe('running')
+    agent.cancel('mid-step')
+    await waitForIdle(ctx, agent)
+
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'mid-step' }])
+  })
+
+  it('cancel() with no reason defaults to "cancelled" when aborting an in-flight step', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_a, _t, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await new Promise(r => setTimeout(r, 30))
+    agent.cancel() // no reason → default 'cancelled'
+    await waitForIdle(ctx, agent)
+
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }])
+  })
+
+  it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => {
+    const adapter = new MockAdapter(['hang', textResponse('second reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // First turn hangs; cancel it mid-step.
+    send(agent, 'first')
+    await new Promise(r => setTimeout(r, 30))
+    agent.cancel('cancel first')
+    await waitForIdle(ctx, agent)
+
+    // The marker must have been reset after the cancelled turn — a fresh prompt
+    // runs to completion rather than being dropped by a stale marker.
+    send(agent, 'second')
+    await waitForIdle(ctx, agent)
+
+    expect(userTexts(agent)).toContain('second')
+    // The second turn completed (its reply was streamed).
+    const reasons = agent.session.events.filter(e => e.type === 'turn/end')
+    expect(reasons.length).toBe(2)
+  })
+
+  it('cancel from a synchronous agent/turn-start listener drops the step (step-start window)', async () => {
+    const adapter = new MockAdapter([textResponse('should not stream')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // A turn-start listener fires BEFORE any AbortController is installed for the
+    // step. Cancelling there must still drop the step (the turn-scoped marker,
+    // not abort(), is what catches this) — no model step runs.
+    let streamed = false
+    ctx.on('agent/stream-chunk', () => { streamed = true })
+    const dispose = ctx.on('agent/turn-start', (subject) => {
+      if (subject === agent) agent.cancel('from turn-start')
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_a, _t, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+    dispose()
+
+    // No step streamed (the model never ran), and the turn ended aborted.
+    expect(streamed).toBe(false)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }])
+  })
+
+  it('cancel during the continuation window ends the turn aborted and runs no further step', async () => {
+    // A continuation-waterfall listener cancels DURING the continuation decision
+    // (the finished step's AbortController is already cleared), and votes to
+    // continue — but the turn-scoped marker checked right after must end the turn
+    // `aborted` and run NO second step.
+    const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    let steps = 0
+    ctx.on('agent/step-start', () => { steps += 1 })
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_a, _t, reason) => void reasons.push(reason))
+
+    let continued = false
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, next) => {
+      if (subject === agent && !continued) {
+        continued = true
+        agent.cancel('from continuation')
+        return true // vote to continue — the post-waterfall marker check must override
+      }
+      return next()
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    // Only ONE step ran (the second was cancelled in the continuation window),
+    // and the turn ended aborted.
+    expect(steps).toBe(1)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }])
+  })
+
+  it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => {
+    const adapter = new MockAdapter([textResponse('should not run')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    // setStatus('running') emits agent/status SYNCHRONOUSLY, so a running
+    // listener can cancel in the gap between the loop's pre-step check and
+    // runTurn. The second check (after the running flip) must drop the turn —
+    // runTurn would otherwise throw on the now-empty queue.
+    let streamed = false
+    ctx.on('agent/stream-chunk', () => { streamed = true })
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'running') agent.cancel('from running listener')
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+    dispose()
+
+    // No turn opened, no step streamed, and a later prompt still runs (the marker
+    // was reset).
+    expect(streamed).toBe(false)
+    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
+  })
+
+  it("cancel clears the turn's steering — it is not re-enqueued as a fresh turn", async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a1', { model: 'mock' })
+
+    send(agent, 'go')
+    await new Promise(r => setTimeout(r, 30))
+    expect(agent.status).toBe('running')
+    // Steer (joins the running turn's steering FIFO), then cancel: the steering
+    // must be dropped, NOT re-enqueued as a new queued turn.
+    agent.steer([{ type: 'text', text: 'steer text' }])
+    agent.cancel('cancel with steering')
+    await waitForIdle(ctx, agent)
+
+    // After the cancelled turn settles, the agent is idle with NO follow-up turn
+    // started from the dropped steering.
+    await new Promise(r => setTimeout(r, 30))
+    expect(agent.status).toBe('idle')
+    const turnStarts = agent.session.events.filter(e => e.type === 'turn/start')
+    expect(turnStarts.length).toBe(1) // only the original (cancelled) turn
+    // The steering text was dropped — it never reached the log.
+    const flat = agent.session.events
+      .filter(e => e.type === 'steering/message')
+      .flatMap(e => e.type === 'steering/message' ? e.data.content : [])
+      .flatMap(b => b.type === 'text' ? [b.text] : [])
+    expect(flat).not.toContain('steer text')
+  })
+})