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/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' }