dsh-ntr 0.3.2 → 0.3.4

package/src/bridge.ts

@@ -20,6 +20,7 @@ import {
   PROTOCOL_VERSION,
   RequestError,
   type ClientConnection,
+  type ContentBlock,
   type InitializeResponse,
   type McpServer,
   type McpServerHttp,
@@ -39,6 +40,7 @@ import {
   acpToolCallFromUpdate,
   buildAdapterModelId,
   childEnv,
+  hasUnambiguousModelSelector,
   isAcpToolContinuation,
   isUnderPath,
   mergeCatalogShape,
@@ -52,6 +54,7 @@ import {
   resolveFsPath,
   resolveSessionCwd,
   selectForwardPrompt,
+  isAbsolutePath,
   acpPresetStatusFromRoster,
   splitAdapterModelId,
   updateContentToText,
@@ -74,6 +77,7 @@ import type {
   AcpIdleRelease, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionOutcome, PermissionOptionView, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk,
 } from './protocol.ts'
 import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from './protocol.ts'
+import { OUTPUT_CHARS_PER_TOKEN, TurnTpsTracker } from './tps.ts'
 import { UpdateService } from './update.ts'
 
 /**
@@ -134,7 +138,30 @@ interface LiveSession {
   availableCommands?: SessionView['availableCommands']
   plan?: unknown[]
   usage?: SessionView['usage']
+  /**
+   * The plugin's own measurable burst aggregate over this ACP session's turns
+   * (see `src/tps.ts`). Persisted with the chat-session record so the dock's
+   * rate survives a host restart; absent until a turn contributes a measurable
+   * burst (>= 1 inter-chunk gap).
+   */
+  burst?: SessionView['burst']
   running: boolean
+  /**
+   * The HOST's prompt slot for this session: true from the moment a turn
+   * starts until the agent answers it (or the host aborts the turn, or the
+   * turn is discarded). Together with the {@link settled} gate — which STAYS
+   * claimed after an abort until the agent acknowledges the cancel — this is
+   * what `claimTurn` arbitrates, NOT `running`.
+   *
+   * The three are deliberately different:
+   * - an ambient wait keeps `running` true (the background drain is still the
+   *   session's work, so nothing may release the process) while this slot is
+   *   already FREE (the agent answered; only the drain keeps talking);
+   * - an aborted turn drops THIS flag at once (our face of the turn ends) but
+   *   leaves `settled` in place, so the next prompt still waits out
+   *   `turnSettleMs` for the agent instead of racing a concurrent prompt.
+   */
+  promptInFlight?: boolean
   closed: boolean
   /** The agent process died; the session awaits a `session/load` resume. */
   released: boolean
@@ -244,9 +271,73 @@ interface LiveSession {
    * the controller's own `retire` when it still points at it.
    */
   turnController?: TurnStreamController
+  /**
+   * A background turn the agent started on its OWN initiative (CodeBuddy's
+   * multitask drains: a sub-agent completion notice starts a run the client
+   * never asked for). Its first `session_info_update` announces the request id
+   * every later update of that run carries in `_meta`; a `session/prompt`
+   * answered instantly with no conversation request id was folded into this
+   * drain and its real answer arrives as the drain's updates.
+   *
+   * Only lifetime events clear it (close / release / resume / stop): a drain
+   * may outlive the turn that was steered into it, and clearing on a normal
+   * settle would misclassify the NEXT steered prompt.
+   */
+  ambient?: AmbientTurn
+  /**
+   * Request ids whose `agent/notice` already went out, so a repeated
+   * announcement of the same background run is not logged twice.
+   */
+  ambientNotices?: Set<string>
+  /**
+   * Background drains this session already STOPPED waiting on (an ambient wait
+   * that closed on silence, or a record that outlived `ambientStaleMs`). The
+   * record is gone from {@link ambient}, but the drain itself may still be
+   * running: a queued message or a long tool makes it speak again while the
+   * NEXT turn is on air. Without this list the late text would teach that turn
+   * the drain's id (`noteTurnRequestId` / `adoptTurnRequestId`) and fold the
+   * background run's answer into the user's answer (a double answer).
+   *
+   * An update or re-announcement carrying a listed id REVIVES it
+   * (`reviveAmbientId` + a rebuilt {@link ambient}): the run is alive, so its
+   * next steered prompt must receive the drain's text. Only while the record
+   * stays retired is its text transcript-only. Timestamps let the zero-output
+   * report recognise a prompt folded into a recently quieted drain
+   * (`hasRecentRetiredAmbient`). Bounded ({@link RETIRED_AMBIENT_MAX}), oldest
+   * evicted first; every lifecycle boundary clears the list
+   * (`clearAmbientState`).
+   */
+  retiredAmbients?: RetiredAmbient[]
   transcript: Transcript
 }
 
+/** One unsolicited (background) turn the agent is running, as announced in `_meta`. */
+interface AmbientTurn {
+  /** `codebuddy.ai/requestId` of the drain; every update of the run carries it. */
+  requestId: string
+  startedAt: number
+  /**
+   * When this drain last showed any sign of life (announcement or an update
+   * carrying its request id). {@link BridgeTuning.ambientStaleMs} expires the
+   * record from here, so a drain that died silently does not capture a later
+   * normal turn as steered.
+   */
+  lastActivityAt: number
+  /** Whether the drain already streamed prose (text or thought) into the transcript. */
+  sawOutput: boolean
+}
+
+/** A drain id the session stopped waiting on, and when it was retired. */
+interface RetiredAmbient {
+  requestId: string
+  /**
+   * When the wait was retired. `hasRecentRetiredAmbient` uses it to tell a
+   * prompt folded into a just-quieted drain from one that ended on its own;
+   * `adoptTurnRequestId` / `noteTurnRequestId` ignore the id at any age.
+   */
+  retiredAt: number
+}
+
 /** Reliability tuning, threaded from `AcpPluginConfig` through the manager. */
 export interface BridgeTuning {
   startupTimeoutMs?: number
@@ -341,6 +432,65 @@ export interface BridgeTuning {
    * probe-only process has no stake in. `0` disables it.
    */
   probeIdleTimeoutMs?: number
+  /**
+   * How long an ambient wait (see `TurnStreamController.awaitAmbient`) stays
+   * open after the LAST session update before the turn closes itself.
+   *
+   * A drain's end is its silence — the SDK's schema rejects the `session_end`
+   * CodeBuddy never sends anyway — but "silence" must be measured in the
+   * agent's own cadence, not in a chat-app-paced one. Measured against
+   * CodeBuddy 2.179.0: the gaps between drain ticks (the
+   * `model_requesting`→`model_streaming` hand-off of a real model call) run
+   * 1.0–1.4s, so any window below that closes the turn BEFORE the answer
+   * exists. 10s leaves room for two slow hand-offs without holding the turn
+   * open for a drain that actually finished.
+   *
+   * Deliberately NOT keyed on an `agentPhase` idle flag: a drain goes idle
+   * between queued messages too, so that signal closes the turn in the middle
+   * of its own work.
+   */
+  ambientQuietMs?: number
+  /**
+   * The hard ceiling on ONE ambient wait: a background run that keeps ticking
+   * for minutes without finishing must not hold the conversation's turn open
+   * forever. At the ceiling the turn says where the rest of the output will
+   * land and closes.
+   */
+  ambientMaxMs?: number
+  /**
+   * The hard ceiling on the WORKER phase of a detached-worker hold (see
+   * `TurnStreamController.holdForBackgroundDispatch`): the turn dispatched one
+   * or more background workers through `Agent` tool calls, the agent answered
+   * the prompt, and at least one worker has not reported back yet. The worker
+   * phase has NO quiet window on purpose — measured against CodeBuddy 2.179.0,
+   * a detached worker's own updates are 13–24s apart while it is perfectly
+   * alive — so only EVERY known dispatch reporting (completed / failed) or
+   * this ceiling can end it; a drain announcement is recorded but arms no
+   * clock before then. Once they have all reported, the drain's own
+   * `ambientQuietMs` / `ambientMaxMs` windows take over.
+   *
+   * Default 600000 ms (10 minutes).
+   */
+  backgroundTaskMaxMs?: number
+  /**
+   * How long a PARKED detached-worker hold may wait for the host to open the
+   * driver step that carries the worker's report. The prompt response landed
+   * between two steps (the host is about to execute the `Agent` card), and a
+   * host that never opens the continuation step must not hang the turn. The
+   * host normally opens it at once, so this is a safety bound, not a cadence —
+   * deliberately far larger than one model hand-off.
+   *
+   * Default 30000 ms (30 seconds).
+   */
+  backgroundParkedGraceMs?: number
+  /**
+   * How long an announced background drain may go without ANY update before a
+   * later instant prompt stops treating itself as folded into it. A drain that
+   * went silent for minutes is over even though nothing told us; keeping the
+   * record would misclassify the next normal turn as steered. Checked lazily
+   * when a prompt response arrives (see `streamPrompt`), never on a timer.
+   */
+  ambientStaleMs?: number
 }
 
 /**
@@ -426,6 +576,11 @@ const DEFAULT_TUNING: Required<BridgeTuning> = {
   turnStallTickMs: 30_000,
   idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
   probeIdleTimeoutMs: 300_000,
+  ambientQuietMs: 10_000,
+  ambientMaxMs: 120_000,
+  backgroundTaskMaxMs: 600_000,
+  backgroundParkedGraceMs: 30_000,
+  ambientStaleMs: 300_000,
 }
 
 type BridgeState = 'stopped' | 'starting' | 'ready' | 'error'
@@ -698,11 +853,16 @@ export class AgentBridge {
    * same session — forbidden by the protocol and rejected (or worse, mishandled)
    * by the agent. Waiting turns a protocol error into a short delay.
    *
+   * The gate is {@link LiveSession.promptInFlight} + the settle promise, NOT
+   * {@link LiveSession.running}: an ambient turn keeps `running` true for the
+   * whole drain while its prompt slot is already free, so `running` would
+   * refuse every message the user sends during a background task.
+   *
    * @param session - the session asking for the slot.
    * @returns whether the slot was claimed, and why not when it was not.
    */
   async claimTurn(session: LiveSession): Promise<{ ok: true } | { ok: false; reason: 'busy' | 'unsettled' }> {
-    if (session.running) return { ok: false, reason: 'busy' }
+    if (this.promptSlotHeld(session)) return { ok: false, reason: 'busy' }
     const pending = session.settled
     if (pending === undefined) return { ok: true }
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -720,13 +880,21 @@ export class AgentBridge {
     // The agent never acknowledged: sending now would start a concurrent turn,
     // so report it honestly instead of handing the agent two prompts at once.
     if (session.settled !== undefined) return { ok: false, reason: 'unsettled' }
-    if (session.running) return { ok: false, reason: 'busy' }
+    // Re-checked after the wait: another turn may have claimed the slot while
+    // this one was waiting on the gate.
+    if (this.promptSlotHeld(session)) return { ok: false, reason: 'busy' }
     return { ok: true }
   }
 
+  /** Whether a turn currently holds the agent prompt slot (see `promptInFlight`). */
+  private promptSlotHeld(session: LiveSession): boolean {
+    return session.promptInFlight === true
+  }
+
   /**
-   * Mark the agent-side turn as in flight and hand back the settler its stream
-   * owner must call once the agent is actually done with it.
+   * Mark the agent-side turn as in flight — claim the agent prompt slot and
+   * open the settle gate — and hand back the settler its stream owner must
+   * call once the agent is actually done with it.
    *
    * @param session - the session whose turn is starting.
    * @returns the settler (idempotent; also used by connection loss).
@@ -736,11 +904,16 @@ export class AgentBridge {
     const settled = new Promise<void>(resolve => { settle = resolve })
     session.settled = settled
     session.settledResolve = settle
+    session.promptInFlight = true
     this.touch()
     return () => {
+      // Identity-guarded: only THIS turn's settler may release the slot. A
+      // superseded turn's late settler must not clear the flag a NEWER turn
+      // has already claimed (its settle gate was replaced with a new promise).
       if (session.settled === settled) {
         session.settled = undefined
         session.settledResolve = undefined
+        session.promptInFlight = false
       }
       settle()
       // The turn is over: a fresh window starts here rather than at the prompt
@@ -752,12 +925,14 @@ export class AgentBridge {
   /**
    * Open a session's settle gate without owning its turn stream: the turn's
    * stream is gone (a resume, a release) but the next prompt still waits on
-   * this promise, and nothing is left that could ever resolve it.
+   * this promise, and nothing is left that could ever resolve it. The prompt
+   * slot itself goes with it: whatever held it is gone too.
    */
   private openSettleGate(session: LiveSession): void {
     const settle = session.settledResolve
     session.settled = undefined
     session.settledResolve = undefined
+    session.promptInFlight = false
     settle?.()
   }
 
@@ -1257,25 +1432,67 @@ export class AgentBridge {
    * {@link BridgeTuning.staleCancelRetryDelayMs}, out-waiting the cleanup
    * window, bounded by {@link BridgeTuning.staleCancelMaxRetries}; a genuinely
    * requested cancel (`cancelRequestedAtTurn` still names this generation)
-   * returns as-is.
+   * returns as-is — checked BOTH before the delay and after it, so a second
+   * stop click inside the retry window does not resend the prompt the user
+   * just stopped.
+   *
+   * `turnGen` is the {@link LiveSession.turnSeq} this prompt was sent for. A
+   * stale-cancel resend is only allowed while that generation still owns the
+   * session: once a successor turn began (the cancel fallback finalized this
+   * one and the user moved on), resending would race a second `session/prompt`
+   * into the successor's turn. The late answer is returned as-is instead.
+   *
+   * The RESPONSE's `_meta` travels with the stop reason: it is the only place
+   * an agent says whether the prompt actually queued a conversation turn (see
+   * `CodebuddyMeta.conversationRequestId`), which decides whether an instant
+   * answer was the turn ending or a fold into a background drain.
    */
-  async runPrompt(session: LiveSession, text: string, turnId: string): Promise<string> {
+  async runPrompt(session: LiveSession, prompt: string | ContentBlock[], turnId: string, turnGen: number): Promise<{ stopReason: string; meta?: Record<string, unknown> }> {
     const conn = this.conn
     if (conn === undefined || session.closed || session.released) throw new AcpError('session_closed', 'acp: session is closed')
     this.touch()
+
+    const blocks: ContentBlock[] = typeof prompt === 'string'
+      ? [{ type: 'text', text: prompt }]
+      : prompt
+
+    if (blocks.length === 0) {
+      throw new AcpError('empty_prompt', 'acp: prompt cannot be empty')
+    }
+
+    const hasImages = blocks.some(b => b.type === 'image')
+    if (hasImages && this.initResult?.agentCapabilities?.promptCapabilities?.image !== true) {
+      throw new AcpError('image_unsupported', `acp: agent "${this.def.id}" does not support image input`)
+    }
+
     for (let attempt = 0; ; attempt += 1) {
       // The response is activity too: the idle window must start at the turn's
       // END, not at the prompt that may have started a long time ago.
       const result = await conn.agent.request(methods.agent.session.prompt, {
         sessionId: session.acpSessionId,
-        prompt: [{ type: 'text', text }],
+        prompt: blocks,
       }).finally(() => { this.touch() })
+      const answered = () => ({
+        stopReason: result.stopReason,
+        ...(result._meta !== undefined && result._meta !== null ? { meta: result._meta } : {}),
+      })
       if (result.stopReason !== 'cancelled' || session.cancelRequestedAtTurn === session.turnSeq) {
-        return result.stopReason
+        return answered()
       }
-      if (attempt >= this.staleCancelMaxRetries) return result.stopReason
+      // The turn this answer belongs to no longer owns the session (a cancel
+      // fallback finalized it and a successor began): resending would fire a
+      // second `session/prompt` into the successor's turn.
+      if (session.turnSeq !== turnGen) return answered()
+      if (attempt >= this.staleCancelMaxRetries) return answered()
       await new Promise(resolve => setTimeout(resolve, this.staleCancelRetryDelayMs))
       if (session.closed || this.conn !== conn) throw new AcpError('session_closed', 'acp: session is closed')
+      // Re-check after the delay: the successor may have started while waiting.
+      if (session.turnSeq !== turnGen) return answered()
+      // ...and a SECOND stop during the delay names this same generation. The
+      // user already said stop, so the stale-cancel answer is not a swallow to
+      // out-wait anymore: resending would make the agent run the prompt the
+      // user just stopped (the double-click case). Return as-is.
+      if (session.cancelRequestedAtTurn === session.turnSeq) return answered()
       this.touch()
     }
   }
@@ -1326,16 +1543,30 @@ export class AgentBridge {
 
   /**
    * Force the local end of one turn whose agent never acknowledged it: clear
-   * `running`, open the settle gate, and broadcast the turn end with `turnId:
-   * ''` (there is no agent response to attribute it to). Shared by the cancel
+   * `running`, open the settle gate, and end the turn. Shared by the cancel
    * fallback and the stall watchdog.
    *
+   * A live controller owns the turn's streaming face — its segment queue, its
+   * ambient clocks and its `turn/end` id. Ending the turn behind its back
+   * would leave the driver step parked on an open queue, and the controller's
+   * own timers would later broadcast a SECOND `turn/end` for a turn already
+   * closed. So when the session still points at a current controller, the
+   * force goes THROUGH it (`forceFinalize`), which runs the same closing work
+   * as a normal settle exactly once. Only a turn with no live controller (an
+   * `/acp`-RPC turn, or one already retired) falls back to the local broadcast
+   * with `turnId: ''` — there is no stream whose id could be named.
+   *
    * Generation-guarded: a turn that already ended — or that a later turn
    * superseded — is not this call's to finalize. Returns whether it acted; a
    * `false` means the caller was late and must leave the session alone.
    */
   finalizeTurn(session: LiveSession, turnGen: number, message: string): boolean {
     if (session.closed || session.turnSeq !== turnGen) return false
+    const controller = session.turnController
+    if (controller !== undefined && !controller.stale) {
+      controller.forceFinalize({ kind: 'error', message })
+      return true
+    }
     // Nothing is in flight anymore (the turn settled on its own): nothing to
     // finalize. A still-pending settle gate counts as in flight even though
     // the stream is gone — that gate is what the next prompt waits on.
@@ -1403,10 +1634,12 @@ export class AgentBridge {
       session.closed = false
       session.released = false
       // A resume is a fresh agent-side state: nothing from the dead process's
-      // turn survives it, including the settle gate and the stall markers.
+      // turn survives it, including the settle gate and the stall markers. A
+      // background drain belonged to that process too.
       session.orphanPromptTurnSeq = undefined
       session.reclaimedTurnSeq = undefined
       session.activeToolCalls.clear()
+      clearAmbientState(session)
       session.lastAgentActivityAt = Date.now()
       this.openSettleGate(session)
       // Route replay updates into the fresh transcript while the load request
@@ -1469,8 +1702,10 @@ export class AgentBridge {
       // would make the next prompt wait for an answer that can no longer come.
       this.openSettleGate(session)
       // No call from the dead process can still be running: drop the tool set
-      // so a resumed turn starts on the plain window.
+      // so a resumed turn starts on the plain window. A background drain died
+      // with it, and a stale ambient would misclassify the NEXT prompt.
       session.activeToolCalls.clear()
+      clearAmbientState(session)
       session.released = true
       this.settlePermissions(session)
       this.released.set(session.sessionId, session)
@@ -1581,6 +1816,12 @@ export class AgentBridge {
   async closeSession(session: LiveSession, reason: 'closed' | 'agent-stopped' | 'agent-died'): Promise<void> {
     if (session.closed) return
     session.closed = true
+    // The session is going away: whatever background drain it announced ends
+    // with it (a re-created session must not inherit a stale ambient).
+    clearAmbientState(session)
+    // ...and so does its prompt slot: nothing may keep rejecting a new prompt
+    // for a record that is being deleted.
+    session.promptInFlight = false
     // Closing a session is activity of its own: restart the idle window here
     // rather than at the prompt that opened it.
     this.touch()
@@ -1655,6 +1896,7 @@ export class AgentBridge {
       this.settlePermissions(session)
       this.openSettleGate(session)
       session.activeToolCalls.clear()
+      clearAmbientState(session)
       this.sessions.delete(session.sessionId)
       this.acpIndex.delete(session.acpSessionId)
       this.hub.broadcast({ type: 'session/closed', sessionId: session.sessionId, reason })
@@ -1937,6 +2179,60 @@ export class AgentBridge {
     // tool, which earns the wider watchdog window.
     session.lastAgentActivityAt = Date.now()
     const kind = params.update.sessionUpdate
+    const meta = codebuddyMetaOf(params.update)
+    // A RETIRED drain that speaks again is alive, not retired. Un-retire it
+    // BEFORE this update is classified and rebuild the ambient record: the run
+    // may never re-announce itself, yet the next prompt folded into it must
+    // still be recognised as steered and receive the drain's text. A
+    // re-announcement below does the same for its id.
+    if (meta?.requestId !== undefined && isRetiredAmbientId(session, meta.requestId)) {
+      reviveAmbientId(session, meta.requestId)
+      session.ambient = {
+        requestId: meta.requestId,
+        startedAt: session.ambient?.startedAt ?? Date.now(),
+        lastActivityAt: Date.now(),
+        sawOutput: session.ambient?.sawOutput ?? false,
+      }
+    }
+    if (meta?.unsolicitedTurn !== undefined) {
+      // The agent started a background turn on its own: remember it so a
+      // prompt the agent folds into it (answered instantly, no conversation
+      // request id) can be kept open until the drain speaks. Announced once per
+      // request id — a repeated announcement is the same run, not news.
+      const run = meta.unsolicitedTurn
+      // A re-announcement also revives a drain whose wait already closed: the
+      // same run is alive, and the notice de-dupe set keeps it silent.
+      reviveAmbientId(session, run.requestId)
+      session.ambient = { requestId: run.requestId, startedAt: Date.now(), lastActivityAt: Date.now(), sawOutput: false }
+      const announced = session.ambientNotices ?? new Set<string>()
+      session.ambientNotices = announced
+      if (!announced.has(run.requestId)) {
+        announced.add(run.requestId)
+        // The de-dupe set outlives individual turns (a hard ceiling keeps the
+        // drain record), so it is bounded: evict the oldest ids first.
+        while (announced.size > AMBIENT_NOTICE_MAX) {
+          const oldest = announced.values().next().value
+          if (oldest === undefined) break
+          announced.delete(oldest)
+        }
+        this.hub.broadcast({
+          type: 'agent/notice',
+          agentId: session.agentId,
+          level: 'info',
+          text: `acp: agent "${this.def.id}" started a background task turn (${run.reason ?? 'unsolicited'}); its output will appear in the ACP transcript view, or in the turn that was waiting for it.`,
+        })
+      }
+    }
+    if (session.ambient !== undefined
+      && meta?.requestId === session.ambient.requestId) {
+      // The run is alive: refresh the staleness clock on ANY update it owns,
+      // not just prose (a tool-heavy stretch is still the drain working).
+      session.ambient.lastActivityAt = Date.now()
+      if ((kind === 'agent_message_chunk' || kind === 'agent_thought_chunk')
+        && chunkTextOf((params.update as { content?: unknown }).content) !== '') {
+        session.ambient.sawOutput = true
+      }
+    }
     if (kind === 'tool_call' || kind === 'tool_call_update') {
       const { toolCallId, status } = params.update as { toolCallId: string; status?: string | null }
       if (status === 'completed' || status === 'failed') session.activeToolCalls.delete(toolCallId)
@@ -1994,6 +2290,178 @@ export class AgentBridge {
   }
 }
 
+/**
+ * The CodeBuddy `_meta` facts this bridge reads, when the object carries them.
+ *
+ * CodeBuddy runs "background drains": a sub-agent completion notice starts a
+ * turn the client never prompted, announced by a `session_info_update` whose
+ * `_meta["codebuddy.ai/unsolicitedTurn"]` names the run. Every update of that
+ * run then carries `_meta["codebuddy.ai/requestId"]`, and a `session/prompt`
+ * answered instantly (with no `codebuddy.ai/conversationRequestId` on the
+ * RESPONSE) had its message folded into the drain — the real answer streams
+ * afterwards, under the drain's request id.
+ *
+ * The same run also explains a DETACHED WORKER: `_meta["codebuddy.ai/toolName"]`
+ * names the `Agent` call that dispatched it, the call is re-sent with
+ * `_meta["codebuddy.ai/isBackground"] = true` once the worker runs off-turn, and
+ * every update the worker emits carries
+ * `_meta["codebuddy.ai/parentToolCallId"]` naming that call. Those updates are
+ * the worker's own turn — they belong in the transcript, not in the session's
+ * assistant message. The completion of the dispatch call itself carries NO
+ * `_meta` at all, so a known call's status is read from its id.
+ *
+ * No other agent sends these keys: an object without them yields `undefined`,
+ * so every existing path is untouched. Values are only read when they have the
+ * declared shape (never guessed from a message body).
+ */
+interface CodebuddyMeta {
+  /** The run this update belongs to. */
+  requestId?: string
+  /** Set on the `session_info_update` that STARTS a background turn. */
+  unsolicitedTurn?: { requestId: string; reason?: string }
+  /** The agent's own phase heartbeat (`{ phase }`), a liveness tick. */
+  agentPhase?: { phase: string }
+  /** Set on a `session/prompt` RESPONSE that really queued a conversation turn. */
+  conversationRequestId?: string
+  /**
+   * The tool a `tool_call` names, when the agent omits `title`. `Agent` (or
+   * `Task`) means the call DISPATCHED a detached worker: the call stays in
+   * progress while the worker runs on its own.
+   */
+  toolName?: string
+  /**
+   * Set on every update a DETACHED WORKER emits (prose, tools, its report):
+   * it names the `Agent` tool call that dispatched the worker. Such an update
+   * belongs to the worker's own turn, never to this session's answer.
+   */
+  parentToolCallId?: string
+  /**
+   * Set on the dispatch call RE-SENT after the worker started
+   * (`codebuddy.ai/isBackground: true`): the call handed its work to a worker
+   * that keeps running off-turn, which is the structural "detached" signal.
+   * The first send of the same call does not carry it.
+   */
+  isBackground?: boolean
+  /** `codebuddy.ai/isSubagent` — the same re-send declares the worker a sub-agent. */
+  isSubagent?: boolean
+}
+
+/** Read the CodeBuddy `_meta` keys off an update or a `{ _meta }` wrapper. */
+function codebuddyMetaOf(source: unknown): CodebuddyMeta | undefined {
+  if (typeof source !== 'object' || source === null) return undefined
+  const row = source as Record<string, unknown>
+  const rawMeta = row._meta
+  if (typeof rawMeta !== 'object' || rawMeta === null) return undefined
+  const meta = rawMeta as Record<string, unknown>
+  const out: CodebuddyMeta = {}
+  const requestId = meta['codebuddy.ai/requestId']
+  if (typeof requestId === 'string' && requestId !== '') out.requestId = requestId
+  const conversationRequestId = meta['codebuddy.ai/conversationRequestId']
+  if (typeof conversationRequestId === 'string' && conversationRequestId !== '') {
+    out.conversationRequestId = conversationRequestId
+  }
+  const toolName = meta['codebuddy.ai/toolName']
+  if (typeof toolName === 'string' && toolName !== '') out.toolName = toolName
+  const parentToolCallId = meta['codebuddy.ai/parentToolCallId']
+  if (typeof parentToolCallId === 'string' && parentToolCallId !== '') out.parentToolCallId = parentToolCallId
+  // Booleans, read as booleans only: a string "true" is not the declared shape
+  // and guessing from it would make another agent's unrelated key look detached.
+  if (meta['codebuddy.ai/isBackground'] === true) out.isBackground = true
+  if (meta['codebuddy.ai/isSubagent'] === true) out.isSubagent = true
+  const unsolicited = meta['codebuddy.ai/unsolicitedTurn']
+  if (typeof unsolicited === 'object' && unsolicited !== null) {
+    const run = unsolicited as Record<string, unknown>
+    if (typeof run.requestId === 'string' && run.requestId !== '') {
+      out.unsolicitedTurn = {
+        requestId: run.requestId,
+        ...(typeof run.reason === 'string' && run.reason !== '' ? { reason: run.reason } : {}),
+      }
+    }
+  }
+  const phase = meta['codebuddy.ai/agentPhase']
+  if (typeof phase === 'object' && phase !== null) {
+    const tick = phase as Record<string, unknown>
+    if (typeof tick.phase === 'string' && tick.phase !== '') out.agentPhase = { phase: tick.phase }
+  }
+  return Object.keys(out).length === 0 ? undefined : out
+}
+
+/**
+ * Remember a background drain this session stopped waiting on. A quiet close
+ * drops the drain record (so an ordinary next turn is not held open for it),
+ * but the run may revive afterwards; keeping its id lets every later update be
+ * recognized as the drain's (`isRetiredAmbientId`) instead of being adopted as
+ * the next turn's own. Bounded, oldest first — an id this far back names a run
+ * no late update can plausibly still carry. Re-retiring an id refreshes its
+ * timestamp and moves it to the end.
+ */
+function retireAmbientId(session: LiveSession, requestId: string): void {
+  const retired = session.retiredAmbients ?? []
+  const existing = retired.findIndex(entry => entry.requestId === requestId)
+  if (existing >= 0) retired.splice(existing, 1)
+  retired.push({ requestId, retiredAt: Date.now() })
+  while (retired.length > RETIRED_AMBIENT_MAX) retired.shift()
+  session.retiredAmbients = retired
+}
+
+/** Whether this request id names a drain the session already stopped waiting on. */
+function isRetiredAmbientId(session: LiveSession, requestId: string | undefined): boolean {
+  return requestId !== undefined
+    && session.retiredAmbients?.some(entry => entry.requestId === requestId) === true
+}
+
+/**
+ * Whether the session retired a drain recently enough that a prompt answered
+ * with no ambient record and no conversation id may have been folded into it.
+ * A quiet close is only evidence WE stopped waiting, so the next instant
+ * answer is ambiguous; past this horizon the drain is treated as gone and the
+ * ordinary zero-output warning applies.
+ */
+function hasRecentRetiredAmbient(session: LiveSession, withinMs: number): boolean {
+  const retired = session.retiredAmbients
+  if (retired === undefined || retired.length === 0) return false
+  const cutoff = Date.now() - withinMs
+  return retired.some(entry => entry.retiredAt >= cutoff)
+}
+
+/**
+ * The retired drain spoke again (an update or a re-announcement carried its
+ * id): it is alive, not retired. The caller rebuilds {@link LiveSession.ambient}
+ * so the next prompt folded into it is recognised as steered and its text can
+ * reach the user's turn; only while the id stays retired does its text remain
+ * transcript-only.
+ */
+function reviveAmbientId(session: LiveSession, requestId: string): void {
+  const retired = session.retiredAmbients
+  if (retired === undefined) return
+  const index = retired.findIndex(entry => entry.requestId === requestId)
+  if (index < 0) return
+  retired.splice(index, 1)
+  if (retired.length === 0) session.retiredAmbients = undefined
+}
+
+/**
+ * Forget every background-drain trace a session carried. Called at each
+ * lifecycle boundary (close / release / resume / force reset): a fresh
+ * agent-side state neither inherits a stale drain nor the ids of drains that
+ * belonged to the old one.
+ */
+function clearAmbientState(session: LiveSession): void {
+  session.ambient = undefined
+  session.ambientNotices?.clear()
+  session.retiredAmbients = undefined
+}
+
+/**
+ * The closing line of a turn the agent deferred to its OWN background run: the
+ * answer exists, but in the ACP transcript view rather than in this bubble.
+ * Shared by the ambient wait and the detached-worker hold, so both say the
+ * same thing in the same words.
+ */
+function backgroundDeferralLine(agentId: string): string {
+  return `\n[dsh-ntr] agent "${agentId}" deferred this turn to a background task run; its output is in the ACP transcript view. Send again after the background run finishes.\n`
+}
+
 /** Human-facing identity of an ACP tool call (the approval headline). */
 /**
  * Human-facing name of the tool an ask is about, for the chat line and the
@@ -2085,6 +2553,7 @@ function snapshot(session: LiveSession): SessionView {
     ...(session.availableCommands !== undefined ? { availableCommands: session.availableCommands } : {}),
     ...(session.plan !== undefined ? { plan: session.plan } : {}),
     ...(session.usage !== undefined ? { usage: session.usage } : {}),
+    ...(session.burst !== undefined ? { burst: session.burst } : {}),
     running: session.running,
     closed: session.closed,
     ...(session.released ? { released: true } : {}),
@@ -2127,6 +2596,7 @@ interface PersistedChatSession {
   reasoningEffort?: string
   modes?: SessionView['modes']
   usage?: SessionView['usage']
+  burst?: SessionView['burst']
   hasHistory?: boolean
 }
 
@@ -2142,6 +2612,7 @@ function persistedChatSession(session: LiveSession): PersistedChatSession {
     ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }),
     ...(session.modes === undefined ? {} : { modes: session.modes }),
     ...(session.usage === undefined ? {} : { usage: session.usage }),
+    ...(session.burst === undefined ? {} : { burst: session.burst }),
     ...(session.hasHistory === true || session.transcript.since(0).length > 0 ? { hasHistory: true } : {}),
   }
 }
@@ -2160,6 +2631,14 @@ function isPersistedUsage(value: unknown): value is SessionView['usage'] {
   return typeof usage.used === 'number' && typeof usage.size === 'number'
 }
 
+/** Tolerant shape check for a `burst` aggregate read back from disk. */
+function isPersistedBurst(value: unknown): value is NonNullable<SessionView['burst']> {
+  if (value === null || typeof value !== 'object') return false
+  const burst = value as { outputTokens?: unknown; burstMs?: unknown }
+  return typeof burst.outputTokens === 'number' && burst.outputTokens >= 0
+    && typeof burst.burstMs === 'number' && burst.burstMs >= 0
+}
+
 /**
  * The DSH chat session's OWN workspace, when one is resolvable: the directory
  * the user selected in the DSH sidebar, which the host reports back as the
@@ -2925,12 +3404,17 @@ interface SegmentState {
   activeToolCall: AcpToolCallSnapshot | undefined
   /** Whether this segment opened at least one tool-call block. */
   hasCard: boolean
+  /**
+   * The segment belongs to an ambient wait: the agent folded our prompt into a
+   * background drain it started itself. Tool traffic is recorded (so the
+   * transcript and any parked tool-output waiter get it) but opens NO card —
+   * a card would make the host loop execute a tool for a turn whose answer has
+   * not even started streaming yet.
+   */
+  ambient: boolean
   finished: boolean
 }
 
-/** ACP `usage_update` is context occupancy, not request tokens; host usage is a 4-chars/token OUTPUT estimate (tool args excluded). */
-const OUTPUT_CHARS_PER_TOKEN = 4
-
 /** How one segment's stream ends, in `StreamChunk.finish` terms. */
 type SegmentFinishReason =
   | { kind: 'stop' }
@@ -2943,6 +3427,153 @@ type TurnSettle =
   | { kind: 'cancelled' }
   | { kind: 'error'; message: string; code?: string }
 
+/** How often a running turn's live burst aggregate is pushed to the browser. */
+const TPS_PUSH_INTERVAL_MS = 1000
+
+/**
+ * Bounds on the updates withheld while a turn's own request id is still
+ * unknown (see `TurnStreamController.bufferAmbientUpdate`). The buffer exists
+ * only for the response window of one prompt, but a chatty drain could stream
+ * for a while inside it; over the bound the OLDEST entries are dropped — the
+ * transcript still has every one of them.
+ */
+const PENDING_AMBIENT_MAX_ENTRIES = 200
+const PENDING_AMBIENT_MAX_CHARS = 64 * 1024
+
+/**
+ * Bound on {@link LiveSession.ambientNotices}. The set now outlives the turn
+ * that announced a drain (a hard ceiling keeps the record, and a repeated
+ * announcement of the same run must stay silent), so it needs a ceiling of its
+ * own for a chatty agent. Oldest ids are evicted first; an id that far back is
+ * a run nobody is waiting on anymore.
+ */
+const AMBIENT_NOTICE_MAX = 64
+
+/**
+ * Bound on {@link LiveSession.retiredAmbients}. The ids only exist to catch a
+ * drain that speaks again after its wait closed, and the timestamp lets the
+ * next silent close recognise a recent fold — a short-horizon concern, so a
+ * small ring is enough; the oldest is evicted first.
+ */
+const RETIRED_AMBIENT_MAX = 32
+
+/**
+ * Floor for the "recently retired" lookback the zero-output fallback uses
+ * (twice `ambientQuietMs`). Only test-sized quiet windows fall below it; a
+ * production window (10s) always wins. Without the floor a 250ms quiet window
+ * would leave a 500ms lookback, too tight to survive a loaded CI scheduler
+ * between one turn ending and the next prompt's response.
+ */
+const RETIRED_AMBIENT_RECENT_MIN_MS = 1_000
+
+/** One ambient wait's clocks and the stop reason it will close the turn with. */
+interface AmbientWait {
+  /** The drain's request id: the turn is waiting on this run, not on its own. */
+  requestId: string
+  quietTimer: ReturnType<typeof setTimeout>
+  hardTimer: ReturnType<typeof setTimeout>
+  /** The stop reason the agent's `session/prompt` response carried. */
+  stopReason: string
+  /**
+   * Whether the CEILING closed this wait (the drain was still ticking) rather
+   * than silence. A hard ending must keep the session's drain record: the next
+   * prompt may be folded into the same run, and it is still alive.
+   */
+  hard?: boolean
+}
+
+/** An update withheld from the segment until the turn's own request id is known. */
+interface PendingAmbientUpdate {
+  seq: number
+  update: Record<string, unknown>
+  /** `JSON.stringify(update).length`, kept so eviction need not re-serialize. */
+  chars: number
+}
+
+/**
+ * The `Agent` tool call that handed work to a DETACHED worker.
+ *
+ * CodeBuddy 2.179.0 with multitask on: the coordinator opens an `Agent` call
+ * (`_meta["codebuddy.ai/toolName"] = "Agent"`), says "已派…", and ENDS ITS OWN
+ * PROMPT normally while the worker keeps running off-turn. The call itself
+ * stays `in_progress` until the worker reports, and only then does the agent
+ * start the background drain that carries the worker's report into the
+ * session. A turn that closed at its prompt response therefore lost the only
+ * answer it was ever going to produce; this record is what the controller
+ * holds the turn open for.
+ */
+interface BackgroundDispatch {
+  /** The `Agent` call's id — the card that stays on the plane. */
+  toolCallId: string
+  /** The last status the agent declared for the dispatch call itself. */
+  status: string
+  /** Whether the call already reported completed / failed. */
+  completed: boolean
+  /**
+   * Whether the work runs DETACHED, read from the wire's own structure: the
+   * call re-sent with `_meta["codebuddy.ai/isBackground"] = true`, or any
+   * update naming this call as its `parentToolCallId`. A synchronous
+   * `Agent` / `Task` call carries neither, so it can never make the turn wait
+   * after its own answer.
+   */
+  detached: boolean
+  /** Whether any update came FROM the worker (`codebuddy.ai/parentToolCallId`). */
+  sawWorkerUpdate: boolean
+}
+
+/**
+ * A turn held open for the detached worker its `Agent` call dispatched.
+ *
+ * Two phases, because their liveness signals differ:
+ * - `worker`: at least one worker runs off-turn and may be silent for tens of
+ *   seconds between model calls — NO quiet timer, only
+ *   {@link BridgeTuning.backgroundTaskMaxMs}. It ends when EVERY known dispatch
+ *   reported (completed / failed); a drain announcement is recorded meanwhile
+ *   but arms no clock.
+ * - `drain`: every dispatch reported and the background turn that carries
+ *   their report is (or is about to start) — the existing ambient windows
+ *   apply (`ambientQuietMs` quiet, reset by every update; `ambientMaxMs`
+ *   ceiling from the switch).
+ */
+interface BackgroundHold {
+  /** The stop reason the prompt RESPONSE carried (what the turn closes with). */
+  stopReason: string
+  /** The run this hold currently waits on: the response's id or the last announcement. */
+  requestId?: string
+  /**
+   * Every drain id this hold may fold text from: the response's
+   * `conversationRequestId` / `requestId` plus every announced id. A run
+   * announced before the response may name a different id than the response —
+   * both are this turn's answer, and anything else stays background noise.
+   */
+  acceptedIds: Set<string>
+  phase: 'worker' | 'drain'
+  /**
+   * Agent MESSAGE text folded into this hold. The parent's interim
+   * acknowledgement ("已派…") landed before the hold and is not the drained
+   * run's answer: a hold that never received that answer must still say where
+   * it will appear.
+   */
+  answerChars: number
+  /**
+   * The transcript head when the hold began. Text at or below it arrived
+   * before the hold — a parked hold replays the parent's ack from there — so
+   * it is not counted in {@link answerChars}; the drain updates withheld for
+   * the response are the exception and are counted explicitly when flushed.
+   */
+  floorSeq: number
+  quietTimer?: ReturnType<typeof setTimeout>
+  hardTimer?: ReturnType<typeof setTimeout>
+  /**
+   * The bounded wait for a driver step to speak into. Only while the hold is
+   * PARKED (`pendingBackgroundHold`): the response landed between steps, and
+   * the host is expected to open the continuation step for the Agent card.
+   */
+  graceTimer?: ReturnType<typeof setTimeout>
+  /** Whether the run's ids were already released (a close, cancel or teardown). */
+  retired: boolean
+}
+
 /**
  * The state of ONE ACP prompt, shared across every driver step of the turn.
  *
@@ -2956,13 +3587,111 @@ type TurnSettle =
 class TurnStreamController {
   private segment: SegmentState | undefined
   private settled = false
+  /** Whether the turn's closing work already ran (see `closeTurn`). */
+  private closedTurn = false
   private disposed = false
   private readonly seenCalls = new Set<string>()
   private readonly announcedKinds = new Map<string, string>()
   /** Narrative lines (permission asks) that arrived while no segment was open. */
   private readonly pendingProse: string[] = []
   sawVisibleBlock = false
+  /**
+   * Whether THIS turn streamed its own prose (text or reasoning), i.e. an
+   * answer that is not the background drain's. Tool cards do not count — a
+   * drain that only ran tools delivered no words to the conversation.
+   */
+  private sawAgentProse = false
+  /**
+   * Whether any `agent_message_chunk` text reached the plane. Reasoning does
+   * not count: a steer whose drain only thought is still a turn with no answer
+   * text, and must say so when it closes.
+   */
+  private sawVisibleText = false
+  /**
+   * The CodeBuddy request id this turn has adopted as its own (from the
+   * prompt RESPONSE's `conversationRequestId`, or from the first update that
+   * named one). Used to keep a background drain's prose out of the user's
+   * answer; `undefined` means "unknown" and nothing is split (fail-open).
+   */
+  private turnRequestId?: string
+  /**
+   * Updates the session's background drain already streamed while this turn's
+   * OWN request id was still unknown. They are NOT folded on arrival: a drain
+   * tick that lands before the prompt response could otherwise teach the turn
+   * the drain's id (`noteTurnRequestId`) and mix the drain's text into the
+   * user's answer. Withheld here (cursor already advanced — the transcript
+   * keeps a copy) until the response decides what this turn is:
+   * - a normal turn (response carries a conversation id) discards them — they
+   *   were never this turn's answer;
+   * - a steered turn flushes them into the segment, in order, once
+   *   `awaitAmbient` marks the segment ambient (tool cards suppressed).
+   */
+  private readonly pendingAmbientUpdates: PendingAmbientUpdate[] = []
+  private pendingAmbientChars = 0
+  /**
+   * Whether the bounded buffer dropped at least one update. The flush then
+   * says so in the conversation instead of silently losing the front of the
+   * drain's output (constraint 29: ACP payloads are never dropped silently).
+   */
+  private pendingAmbientTruncated = false
+  /** The ambient wait in progress, if the agent folded this prompt into a drain. */
+  private awaitingAmbient?: AmbientWait
+  /**
+   * The prompt response named no conversation turn while a drain this session
+   * retired RECENTLY may still be running without re-announcing. The turn still
+   * settles at once (a drain record that no update revived is not waited on),
+   * but its zero-output report says the turn may have been folded into that run
+   * instead of blaming the agent and suggesting a resend.
+   */
+  private recentRetiredDrain = false
+  /** The outcome of a settle whose closing work is waiting one macrotask (see `settle`). */
+  private pendingOutcome?: TurnSettle
+  private closeScheduled = false
   private cursorSeq: number
+  /**
+   * Burst tracker for this turn, fed from the LIVE hub frames only. Segment
+   * replay must not touch it: every event is already counted once when it
+   * arrived, and replay would double the numerator and the gaps.
+   */
+  private readonly tps = new TurnTpsTracker()
+  private tpsSeq: number
+  private lastTpsPushAt = 0
+  /**
+   * The ambient quiet/ceiling windows, read once from the manager: they are
+   * deployment tuning, not per-tick facts, and small test values must be stable
+   * for the whole turn (see {@link BridgeTuning.ambientQuietMs} for the
+   * measured CodeBuddy tick cadence these defaults come from).
+   */
+  private readonly ambientTuning: { quietMs: number; maxMs: number }
+  /**
+   * The detached workers this turn dispatched (see {@link BackgroundDispatch}),
+   * by `toolCallId`, recorded from the wire while the turn is still streaming —
+   * typically in the first step, before the prompt response lands. A turn may
+   * dispatch several, and the hold waits for ALL of them.
+   */
+  private readonly dispatches = new Map<string, BackgroundDispatch>()
+  /** The detached-worker hold in progress, once a segment carries it. */
+  private backgroundHold?: BackgroundHold
+  /**
+   * A hold parked because the prompt response landed while NO driver segment
+   * was open (the host is between steps, about to execute the Agent card). It
+   * begins when the next `startSegment` opens — or closes after a bounded
+   * grace so a host that never opens one does not hang the turn.
+   */
+  private pendingBackgroundHold?: BackgroundHold
+  /**
+   * The hold's own windows, read once at construction like the ambient pair:
+   * `taskMaxMs` is the worker phase's ceiling, `graceMs` the parked hold's
+   * bounded wait for a driver step (see {@link BridgeTuning.backgroundTaskMaxMs}
+   * and {@link BridgeTuning.backgroundParkedGraceMs}).
+   */
+  private readonly backgroundTuning: { taskMaxMs: number; graceMs: number }
+  /**
+   * When this controller was built. Only a drain announced AFTER this moment
+   * may be adopted by the hold: an `ambient` record that predates the turn is
+   * some earlier run's, and folding its text would mix two answers.
+   */
+  private readonly constructedAt: number
 
   constructor(
     private readonly manager: BridgeManager,
@@ -2975,6 +3704,10 @@ class TurnStreamController {
   ) {
     this.turnSeqAtStart = session.turnSeq
     this.cursorSeq = session.transcript.head
+    this.tpsSeq = session.transcript.head
+    this.constructedAt = Date.now()
+    this.ambientTuning = manager.ambientTuning
+    this.backgroundTuning = manager.backgroundTuning
     this.unsubscribe = hub.subscribe(event => this.onEvent(event))
   }
 
@@ -3010,6 +3743,12 @@ class TurnStreamController {
    * consuming it, so the next segment replays it again.
    */
   startSegment(): SegmentState {
+    // A step opening on an already settled turn (the response landed a tick
+    // ago and the tail drain is still scheduled) closes that turn FIRST: the
+    // step must read a settled controller and the session must not stay
+    // `running` across the macrotask boundary — the host's next prompt would be
+    // refused as busy for no reason.
+    this.flushScheduledClose()
     // A step opening is the HOST handing the turn back to the agent — this
     // runs for the first step and for each continuation after the host
     // executed a card. The watchdog measures the stretch the AGENT holds the
@@ -3025,13 +3764,31 @@ class TurnStreamController {
       outputChars: 0,
       activeToolCall: undefined,
       hasCard: false,
+      // A segment opened DURING an ambient wait (never the steered first step,
+      // which marks its own) inherits the suppression: the drain's tools still
+      // stay transcript-only until the turn closes. A detached-worker hold
+      // suppresses its cards for the same reason, and a PARKED hold must
+      // suppress from the first replayed update on — the drain's TaskOutput
+      // arrives in exactly that step.
+      ambient: this.awaitingAmbient !== undefined
+        || this.backgroundHold !== undefined
+        || this.pendingBackgroundHold !== undefined,
       finished: false,
     }
     this.segment = seg
     const entries = this.session.transcript.since(this.cursorSeq)
     for (const entry of entries) {
       if (seg.finished) break
-      if (!this.foldInto(seg, entry.update as Record<string, unknown>)) break
+      const update = entry.update as Record<string, unknown>
+      // The same split the live path makes: a background drain's prose is not
+      // this turn's answer, even when it landed while no step was open. The
+      // record (tool outputs) still goes in; the cursor moves past it.
+      if (this.isForeignAmbientText(update)) {
+        this.recordWithoutSegment(update)
+        this.cursorSeq = entry.seq
+        continue
+      }
+      if (!this.foldInto(seg, update, entry.seq)) break
       this.cursorSeq = entry.seq
     }
     if (!seg.finished && this.pendingProse.length > 0) {
@@ -3040,6 +3797,12 @@ class TurnStreamController {
       const lines = this.pendingProse.splice(0, this.pendingProse.length).join('')
       this.emitProse(seg, 'reasoning', lines)
     }
+    const parkedHold = this.pendingBackgroundHold
+    if (parkedHold !== undefined && !seg.finished) {
+      // The host opened the continuation step for the Agent card: the hold
+      // finally has a driver step to speak the drain's answer into.
+      this.adoptBackgroundHold(seg, parkedHold)
+    }
     if (this.settled) this.finishAfterSettle(seg)
     return seg
   }
@@ -3049,10 +3812,745 @@ class TurnStreamController {
     if (this.segment !== undefined) this.finishSegment(this.segment, reason)
   }
 
+  /** Whether this turn already streamed prose of its own (not a drain's). */
+  get hasAgentProse(): boolean {
+    return this.sawAgentProse
+  }
+
+  /**
+   * Keep the turn open for a background drain the agent folded our prompt into.
+   *
+   * THE SHAPE: the agent answered `session/prompt` at once (CodeBuddy returns
+   * `end_turn` in ~14ms when it merges the message into a drain it is already
+   * running) and the real answer streams afterwards under the DRAIN's request
+   * id. Closing on the response would cut the turn before its text exists —
+   * which is exactly the bug this state exists for. So:
+   *
+   * - the agent-side prompt slot is released (`endTurn`: the response HAS
+   *   landed) but the turn is NOT settled: `settled` means "the turn is over",
+   *   and it is not — no `turn/end`, no `running = false`, no segment close;
+   * - the segment keeps folding the session's updates, with cards suppressed
+   *   (see `SegmentState.ambient`): the host must not execute a background
+   *   tool for a turn whose answer has not begun;
+   * - any update on the session resets the quiet clock, and the drain's end is
+   *   its silence (a `session_end` is rejected by the SDK's schema and never
+   *   reaches us — never wait for one); a hard ceiling closes what never ends.
+   */
+  awaitAmbient(requestId: string, stopReason: string): void {
+    if (this.settled || this.disposed || this.awaitingAmbient !== undefined) return
+    const seg = this.segment
+    if (seg === undefined || seg.finished) {
+      // No live driver step to speak into: nothing can be folded, so close the
+      // turn the ordinary way rather than holding state that renders nothing.
+      this.clearPendingAmbient()
+      this.settle({ kind: 'stop', stopReason })
+      return
+    }
+    seg.ambient = true
+    // The response landed: the agent no longer holds a prompt for this turn.
+    this.endTurn()
+    // The drain may have spoken BEFORE the response was judged. Those updates
+    // were withheld while this turn's own request id was unknowable (see
+    // `pendingAmbientUpdates`); the turn IS the drain, so they are its answer —
+    // folded in arrival order, now that `seg.ambient` suppresses their cards.
+    this.flushPendingAmbient(seg)
+    if (seg.finished) {
+      this.settle({ kind: 'stop', stopReason })
+      return
+    }
+    const wait: AmbientWait = {
+      requestId,
+      quietTimer: setTimeout(() => { this.onAmbientQuiet(wait) }, this.ambientTuning.quietMs),
+      hardTimer: setTimeout(() => { this.onAmbientHard(wait) }, this.ambientTuning.maxMs),
+      stopReason,
+    }
+    wait.quietTimer.unref?.()
+    wait.hardTimer.unref?.()
+    this.awaitingAmbient = wait
+  }
+
+  /**
+   * The prompt response named no conversation turn while a drain the session
+   * retired recently may still be running (and did not re-announce): the turn
+   * cannot be held open, but a zero-output report must not blame the agent.
+   * See `hasRecentRetiredAmbient` for the window.
+   */
+  noteRecentRetiredDrain(): void {
+    this.recentRetiredDrain = true
+  }
+
+  /**
+   * Whether this turn dispatched a detached worker whose answer is still
+   * outstanding. Read when the prompt response lands: such a turn is NOT over
+   * even though the agent answered it (see {@link holdForBackgroundDispatch}).
+   *
+   * Two ways a dispatch keeps the turn open:
+   * - it has not reported back yet (the worker is still running), or
+   * - it DID report — before the response, even — but it was structurally
+   *   detached and emitted worker updates: the drain that carries its report
+   *   is still coming.
+   * A synchronous `Agent` / `Task` call (completed, no `isBackground`, no
+   * worker updates) matches neither and closes normally.
+   */
+  get dispatchedDetachedWorker(): boolean {
+    for (const dispatch of this.dispatches.values()) {
+      if (!dispatch.completed) return true
+      if (dispatch.detached && dispatch.sawWorkerUpdate) return true
+    }
+    return false
+  }
+
+  /** The hold this turn is inside — adopted, or parked waiting for a step. */
+  private activeBackgroundHold(): BackgroundHold | undefined {
+    return this.backgroundHold ?? this.pendingBackgroundHold
+  }
+
+  /** Whether every KNOWN dispatch has reported (no dispatch at all counts as done). */
+  private allDispatchesCompleted(): boolean {
+    for (const dispatch of this.dispatches.values()) {
+      if (!dispatch.completed) return false
+    }
+    return true
+  }
+
+  /**
+   * Hold the turn open for the detached worker(s) its `Agent` tool calls
+   * dispatched — the second controlled ambient-family exception (constraint
+   * 23), not a new idle watchdog.
+   *
+   * THE SHAPE (measured against CodeBuddy 2.179.0, multitask on): the
+   * coordinator opens an `Agent` call that hands work to a background worker,
+   * says "已派…", and the `session/prompt` RESPONSE arrives normally while the
+   * worker keeps running. The worker's own updates (requestId B +
+   * `parentToolCallId`) never touch this session's message; when it finishes,
+   * the agent starts a background DRAIN (requestId A — the response's own
+   * `conversationRequestId`) whose steps carry the report and the final answer.
+   * Nothing tells the client the worker is running: no `session_end` (the SDK's
+   * schema rejects it) and an `agentPhase` idle tick even fires BETWEEN the
+   * worker and the drain. So the response cannot close the turn.
+   *
+   * The hold:
+   * - releases the agent-side prompt slot (`endTurn`: the response landed)
+   *   while keeping `running` and the driver step open;
+   * - marks the segment background, so EVERY tool call for the rest of the
+   *   hold — the workers', the drain's TaskOutput — stays transcript-only and
+   *   the final message carries text with no card in front of it;
+   * - waits in two phases: the worker phase only has the
+   *   {@link BridgeTuning.backgroundTaskMaxMs} ceiling (a detached worker goes
+   *   silent for tens of seconds while it works) and ends only when ALL known
+   *   dispatches reported, after which the drain phase uses the ambient
+   *   windows.
+   */
+  holdForBackgroundDispatch(stopReason: string, requestId?: string): void {
+    if (this.settled || this.disposed || this.closedTurn || this.stale) return
+    if (this.activeBackgroundHold() !== undefined) return
+    const hold: BackgroundHold = {
+      stopReason,
+      requestId,
+      acceptedIds: new Set<string>(),
+      phase: 'worker',
+      answerChars: 0,
+      floorSeq: this.session.transcript.head,
+      retired: false,
+    }
+    if (requestId !== undefined) hold.acceptedIds.add(requestId)
+    // A drain announced while this turn was ALREADY on air belongs to it (the
+    // announcement may have named a different id than the response). One that
+    // predates the turn is some earlier run's, and folding its text would mix
+    // two answers.
+    const announced = this.session.ambient
+    if (announced !== undefined && announced.startedAt >= this.constructedAt) {
+      hold.acceptedIds.add(announced.requestId)
+      if (hold.requestId === undefined) hold.requestId = announced.requestId
+    }
+    // The response landed: the agent no longer holds a prompt for this turn.
+    this.endTurn()
+    hold.hardTimer = setTimeout(() => { this.onBackgroundHard(hold) }, this.backgroundTuning.taskMaxMs)
+    hold.hardTimer.unref?.()
+    const seg = this.segment
+    if (seg !== undefined && !seg.finished) {
+      this.adoptBackgroundHold(seg, hold)
+    } else {
+      // The response landed BETWEEN driver steps: the host is about to execute
+      // the Agent card and open its continuation step. Park the hold for that
+      // step, with a bounded wait — a host that never opens one must not hang
+      // the turn forever.
+      hold.graceTimer = setTimeout(() => { this.onBackgroundGraceExpired(hold) }, this.backgroundTuning.graceMs)
+      hold.graceTimer.unref?.()
+      this.pendingBackgroundHold = hold
+    }
+    // A FAST detached worker may already have reported (even before the
+    // response): with every known dispatch complete there is no worker phase
+    // left to wait out, so the drain phase starts now.
+    if (this.allDispatchesCompleted()) this.startBackgroundDrain(hold)
+  }
+
+  /** Give a (possibly parked) hold a driver segment: cards off for the rest of it. */
+  private adoptBackgroundHold(seg: SegmentState, hold: BackgroundHold): void {
+    if (hold.graceTimer !== undefined) {
+      clearTimeout(hold.graceTimer)
+      hold.graceTimer = undefined
+    }
+    if (this.pendingBackgroundHold === hold) this.pendingBackgroundHold = undefined
+    seg.ambient = true
+    this.backgroundHold = hold
+    // The drain may have spoken BEFORE the response was judged. Those updates
+    // were withheld while this turn's own id was unknown
+    // (`pendingAmbientUpdates`); only the runs THIS hold owns are its answer —
+    // another run's withheld text is dropped (the transcript keeps it).
+    this.flushBackgroundHoldUpdates(seg, hold)
+    // The parked grace owns the wait while no step is on air; now that one is,
+    // a hold whose drain phase already began arms its quiet clock.
+    if (hold.phase === 'drain') this.armBackgroundQuiet(hold)
+  }
+
+  /**
+   * The worker phase is over once EVERY known dispatch reported: the drain
+   * that carries their reports is (about to be) running, so the existing
+   * ambient windows take over, measured from HERE.
+   *
+   * An announced run is accepted immediately, but while any dispatch is still
+   * incomplete it only records the id and switches the hold's primary run —
+   * arming the quiet clock there would let a drain that spoke early cut the
+   * turn off before its other worker ever reports.
+   */
+  private startBackgroundDrain(hold: BackgroundHold, requestId?: string): void {
+    if (hold !== this.backgroundHold && hold !== this.pendingBackgroundHold) return
+    if (requestId !== undefined) {
+      hold.acceptedIds.add(requestId)
+      hold.requestId = requestId
+    }
+    if (!this.allDispatchesCompleted()) return
+    if (hold.phase === 'drain') {
+      if (this.backgroundHold === hold) this.armBackgroundQuiet(hold)
+      return
+    }
+    hold.phase = 'drain'
+    if (hold.hardTimer !== undefined) clearTimeout(hold.hardTimer)
+    hold.hardTimer = setTimeout(() => { this.onBackgroundHard(hold) }, this.ambientTuning.maxMs)
+    hold.hardTimer.unref?.()
+    // A parked hold belongs to the grace until a driver step opens; a hold
+    // with a step arms its quiet clock now.
+    if (this.backgroundHold === hold) this.armBackgroundQuiet(hold)
+  }
+
+  /**
+   * A dispatch that lands while the drain phase already began means the
+   * coordinator handed out NEW work: the worker phase is back, and with it the
+   * absence of a quiet window.
+   */
+  private enterBackgroundWorkerPhase(hold: BackgroundHold): void {
+    if (hold.phase === 'worker') return
+    hold.phase = 'worker'
+    if (hold.quietTimer !== undefined) {
+      clearTimeout(hold.quietTimer)
+      hold.quietTimer = undefined
+    }
+    if (hold.hardTimer !== undefined) clearTimeout(hold.hardTimer)
+    hold.hardTimer = setTimeout(() => { this.onBackgroundHard(hold) }, this.backgroundTuning.taskMaxMs)
+    hold.hardTimer.unref?.()
+  }
+
+  /** Push the drain phase's quiet clock out: every update is evidence of work. */
+  private armBackgroundQuiet(hold: BackgroundHold): void {
+    if (hold.quietTimer !== undefined) clearTimeout(hold.quietTimer)
+    hold.quietTimer = setTimeout(() => { this.onBackgroundQuiet(hold) }, this.ambientTuning.quietMs)
+    hold.quietTimer.unref?.()
+  }
+
+  /**
+   * Any session update restarts the drain phase's quiet clock. Only an
+   * ADOPTED hold has one: a parked hold's wait belongs to its grace timer, and
+   * the worker phase never has a clock at all.
+   */
+  private noteBackgroundHoldActivity(): void {
+    const hold = this.backgroundHold
+    if (hold === undefined || hold.phase !== 'drain') return
+    this.armBackgroundQuiet(hold)
+  }
+
+  /** The drained run went quiet: the turn ends with the stop reason the response gave. */
+  private onBackgroundQuiet(hold: BackgroundHold): void {
+    if (this.backgroundHold !== hold || hold.phase !== 'drain') return
+    this.closeBackgroundHold(hold, { hard: false })
+  }
+
+  /** The hold outlived its ceiling (worker or drain): the run is still going. */
+  private onBackgroundHard(hold: BackgroundHold): void {
+    if (hold !== this.backgroundHold && hold !== this.pendingBackgroundHold) return
+    this.closeBackgroundHold(hold, { hard: true })
+  }
+
+  /**
+   * No driver step opened inside the grace: the host is not coming back for
+   * this turn's Agent card. Close it the way a quiet ambient ending does — the
+   * deferral line, never the zero-output blame — and keep ONE drain record:
+   * the worker may still report into a run no turn is waiting on.
+   *
+   * A parked hold has NO segment by definition, so the chat plane has nowhere
+   * to put the deferral line: it goes to the settings log (`agent/notice`)
+   * instead of being parked on prose nobody will read.
+   */
+  private onBackgroundGraceExpired(hold: BackgroundHold): void {
+    if (this.pendingBackgroundHold !== hold) return
+    this.pendingBackgroundHold = undefined
+    this.clearBackgroundHoldTimers(hold)
+    const line = hold.answerChars > 0 ? undefined : backgroundDeferralLine(this.session.agentId)
+    this.releaseBackgroundHoldIds(hold, { hard: true })
+    if (line !== undefined) this.broadcastBackgroundDeferral(line)
+    this.closeTurn({ kind: 'stop', stopReason: hold.stopReason }, { line, keepAmbient: true, requestId: hold.requestId })
+  }
+
+  /**
+   * Close a detached-worker hold exactly once. A turn that folded NO answer
+   * text from its held runs says where the rest of the output will land (the
+   * deferral wording, never the silent-failure blame); the parent's interim
+   * acknowledgement does not count as that answer.
+   *
+   * Ownership of the drain ids at close (`releaseBackgroundHoldIds`): a quiet
+   * close retires every accepted id and drops the session record; a hard or
+   * grace close keeps exactly ONE record, because the run is provably still
+   * going and a later update or re-announcement must revive it normally.
+   */
+  private closeBackgroundHold(hold: BackgroundHold, options: { hard: boolean }): void {
+    if (this.pendingBackgroundHold === hold) this.pendingBackgroundHold = undefined
+    else if (this.backgroundHold === hold) this.backgroundHold = undefined
+    else return
+    this.clearBackgroundHoldTimers(hold)
+    const line = hold.answerChars > 0 ? undefined : backgroundDeferralLine(this.session.agentId)
+    this.releaseBackgroundHoldIds(hold, { hard: options.hard })
+    const onAir = this.segment !== undefined && !this.segment.finished
+    // With no segment on air the closing line has no chat bubble to land in:
+    // log it, so the fact is recorded rather than silently dropped.
+    if (line !== undefined && !onAir) this.broadcastBackgroundDeferral(line)
+    this.closeTurn(
+      { kind: 'stop', stopReason: hold.stopReason },
+      { line, keepAmbient: options.hard, requestId: hold.requestId },
+    )
+  }
+
+  /** Write a hold's deferral line into the settings log (`agent/notice`). */
+  private broadcastBackgroundDeferral(line: string): void {
+    this.hub.broadcast({
+      type: 'agent/notice',
+      agentId: this.session.agentId,
+      level: 'info',
+      text: line.trim(),
+    })
+  }
+
+  /** Drop a hold's clocks. The hold object itself stays for its `retired` mark. */
+  private clearBackgroundHoldTimers(hold: BackgroundHold): void {
+    if (hold.quietTimer !== undefined) clearTimeout(hold.quietTimer)
+    if (hold.hardTimer !== undefined) clearTimeout(hold.hardTimer)
+    if (hold.graceTimer !== undefined) clearTimeout(hold.graceTimer)
+    hold.quietTimer = undefined
+    hold.hardTimer = undefined
+    hold.graceTimer = undefined
+  }
+
+  /**
+   * Drop every hold clock (teardown / a forced ending). `retire` also gives up
+   * every accepted run id — a SUCCESSOR turn must never fold the abandoned
+   * hold's drain or worker text into its own answer.
+   */
+  private clearBackgroundHold(options?: { retire?: boolean }): void {
+    const pending = this.pendingBackgroundHold
+    if (pending !== undefined) {
+      this.pendingBackgroundHold = undefined
+      this.clearBackgroundHoldTimers(pending)
+      if (options?.retire === true) this.releaseBackgroundHoldIds(pending, { hard: false })
+    }
+    const hold = this.backgroundHold
+    if (hold === undefined) return
+    this.backgroundHold = undefined
+    this.clearBackgroundHoldTimers(hold)
+    if (options?.retire === true) this.releaseBackgroundHoldIds(hold, { hard: false })
+  }
+
+  /**
+   * Settle what happens to the session's drain records when a hold closes.
+   *
+   * `hard: false` (quiet close, cancel, teardown): the run is no longer waited
+   * on, so EVERY accepted id is retired — its late text stays transcript-only
+   * for whatever turn runs next — and the session record is dropped if it
+   * names one of them.
+   *
+   * `hard: true` (ceiling / parked grace): the run is provably still going.
+   * Exactly ONE record survives — the session's current drain if it has one,
+   * else the hold's primary run — with its activity clock refreshed; the other
+   * accepted ids are retired. A hold whose primary id had no session record
+   * CREATES one, so a successor's `noteTurnRequestId` cannot adopt that id.
+   * Every accepted id therefore ends up either retired or owned by
+   * `session.ambient`; never both unowned and unretired.
+   */
+  private releaseBackgroundHoldIds(hold: BackgroundHold, options: { hard: boolean }): void {
+    if (hold.retired) return
+    hold.retired = true
+    if (!options.hard) {
+      for (const id of hold.acceptedIds) retireAmbientId(this.session, id)
+      if (this.session.ambient !== undefined && hold.acceptedIds.has(this.session.ambient.requestId)) {
+        this.session.ambient = undefined
+      }
+      return
+    }
+    const survivor = this.session.ambient?.requestId ?? hold.requestId
+    for (const id of hold.acceptedIds) {
+      if (id === survivor) continue
+      retireAmbientId(this.session, id)
+    }
+    if (survivor === undefined) return
+    const now = Date.now()
+    if (this.session.ambient?.requestId === survivor) {
+      this.session.ambient.lastActivityAt = now
+    } else {
+      this.session.ambient = {
+        requestId: survivor,
+        startedAt: now,
+        lastActivityAt: now,
+        sawOutput: hold.answerChars > 0,
+      }
+    }
+    // The surviving run is alive, not retired (an earlier wait of this turn
+    // may have retired it before it spoke again).
+    reviveAmbientId(this.session, survivor)
+  }
+
+  /**
+   * Fold the withheld drain updates that belong to this hold into its segment.
+   * The rest of the buffer was some OTHER run's text: it is dropped here (the
+   * transcript keeps it), never leaked into this turn's answer.
+   */
+  private flushBackgroundHoldUpdates(seg: SegmentState, hold: BackgroundHold): void {
+    if (this.pendingAmbientUpdates.length === 0) {
+      this.pendingAmbientTruncated = false
+      return
+    }
+    const pending = this.pendingAmbientUpdates.splice(0, this.pendingAmbientUpdates.length)
+    this.pendingAmbientChars = 0
+    const truncated = this.pendingAmbientTruncated
+    this.pendingAmbientTruncated = false
+    const accepted = pending.filter(entry => {
+      const requestId = codebuddyMetaOf(entry.update)?.requestId
+      return requestId !== undefined && hold.acceptedIds.has(requestId)
+    })
+    if (accepted.length === 0) return
+    if (truncated && !seg.finished) {
+      // The front of the drain's output was evicted from the bounded buffer:
+      // say so rather than letting the turn quietly start mid-story.
+      this.emitProse(seg, 'text', '\n[dsh-ntr] background output was truncated; the ACP transcript view still has every update.\n')
+    }
+    for (const entry of accepted) {
+      if (seg.finished) break
+      this.foldInto(seg, entry.update, entry.seq)
+      // The buffered drain text arrived BEFORE the hold, but it IS the held
+      // run's answer: below the hold's floor it was not counted by `foldInto`,
+      // so count it here (the floor exists to skip the parent's earlier ack,
+      // not the drain's own words).
+      if (entry.seq <= hold.floorSeq
+        && String(entry.update.sessionUpdate ?? '') === 'agent_message_chunk') {
+        hold.answerChars += chunkTextOf(entry.update.content).length
+      }
+    }
+  }
+
+  /**
+   * Follow the detached-worker signals of one live update.
+   *
+   * Only CodeBuddy sends them (`codebuddyMetaOf` answers `undefined` for every
+   * other agent, so nothing here can fire for them):
+   * - an `Agent` / `Task` `tool_call` records the dispatch — the FIRST send
+   *   needs that CodeBuddy shape;
+   * - the SAME call re-sent with `isBackground: true`, or any update naming it
+   *   as its `parentToolCallId`, marks the work DETACHED;
+   * - that call reporting completed / failed is read BY ID: the real
+   *   completion frame carries NO `_meta` at all, so requiring the CodeBuddy
+   *   shape here would miss every real completion;
+   * - any update carrying `parentToolCallId` is the worker's OWN turn — it
+   *   proves the worker alive but never belongs to this session's answer;
+   * - an `unsolicitedTurn` announcement is the drain that carries the report.
+   */
+  private trackBackgroundDispatch(update: Record<string, unknown>): void {
+    if (this.closedTurn) return
+    const meta = codebuddyMetaOf(update)
+    const kind = String(update.sessionUpdate ?? '')
+    const row = update as { toolCallId?: unknown; status?: unknown }
+    const toolCallId = typeof row.toolCallId === 'string' ? row.toolCallId.trim() : ''
+    const status = typeof row.status === 'string' ? row.status : ''
+    const completedStatus = status === 'completed' || status === 'failed'
+    if ((kind === 'tool_call' || kind === 'tool_call_update') && toolCallId !== '') {
+      const known = this.dispatches.get(toolCallId)
+      if (known !== undefined) {
+        // A known dispatch: the id is the whole evidence (see the doc above).
+        if (status !== '') known.status = status
+        if (meta?.isBackground === true) known.detached = true
+        if (completedStatus && !known.completed) {
+          known.completed = true
+          this.noteDispatchProgress()
+        }
+      } else if (meta !== undefined
+        && (meta.toolName === 'Agent' || meta.toolName === 'Task')
+        && (kind === 'tool_call' || meta.isBackground === true)) {
+        // A NEW dispatch needs the CodeBuddy shape. A turn may dispatch more
+        // than one worker; the hold waits for all of them.
+        const dispatch: BackgroundDispatch = {
+          toolCallId,
+          status,
+          completed: completedStatus,
+          detached: meta.isBackground === true,
+          sawWorkerUpdate: false,
+        }
+        this.dispatches.set(toolCallId, dispatch)
+        if (!dispatch.completed) {
+          const held = this.activeBackgroundHold()
+          // A dispatch registered after the drain phase began means new work:
+          // the worker phase (and its absence of a quiet clock) is back.
+          if (held !== undefined) this.enterBackgroundWorkerPhase(held)
+        }
+      }
+    }
+    if (meta?.parentToolCallId !== undefined) {
+      const parent = this.dispatches.get(meta.parentToolCallId)
+      if (parent !== undefined) {
+        parent.detached = true
+        parent.sawWorkerUpdate = true
+      }
+    }
+    if (meta?.unsolicitedTurn !== undefined) {
+      const held = this.activeBackgroundHold()
+      if (held !== undefined) this.startBackgroundDrain(held, meta.unsolicitedTurn.requestId)
+    }
+  }
+
+  /**
+   * A dispatch just reported: once the LAST one has, the drain phase starts.
+   * Until then the turn stays in its worker phase, with no quiet clock.
+   */
+  private noteDispatchProgress(): void {
+    if (!this.allDispatchesCompleted()) return
+    const held = this.activeBackgroundHold()
+    if (held !== undefined) this.startBackgroundDrain(held)
+  }
+
+  /** Any session update is evidence the drain still works: push the quiet clock out. */
+  private noteAmbientActivity(): void {
+    const wait = this.awaitingAmbient
+    if (wait === undefined) return
+    clearTimeout(wait.quietTimer)
+    wait.quietTimer = setTimeout(() => { this.onAmbientQuiet(wait) }, this.ambientTuning.quietMs)
+    wait.quietTimer.unref?.()
+  }
+
+  /** The drain went quiet: the turn ends with the stop reason the response gave. */
+  private onAmbientQuiet(wait: AmbientWait): void {
+    if (this.awaitingAmbient !== wait) return
+    this.finishAmbient(wait)
+  }
+
+  /** The drain outlived the ceiling: say where the rest will land, then close. */
+  private onAmbientHard(wait: AmbientWait): void {
+    if (this.awaitingAmbient !== wait) return
+    const seg = this.segment
+    if (seg !== undefined && !seg.finished) {
+      this.emitProse(seg, 'text', `\n[dsh-ntr] agent "${this.session.agentId}" is still running a background task; the rest of its output will appear in the ACP transcript view.\n`)
+    }
+    // The ceiling is evidence the drain is STILL RUNNING (unlike a quiet close),
+    // so the ending keeps the session's drain record; see `closeTurn`.
+    wait.hard = true
+    // The hard explanation already says the turn was cut short; the deferred
+    // line would only repeat it in different words.
+    this.finishAmbient(wait, { announceDeferral: false })
+  }
+
+  /**
+   * Close an ambient wait exactly once. A turn that produced no answer TEXT
+   * says so: the drain's output is in the ACP transcript view, and this
+   * bubble must not be empty (the zero-output report, reworded for a turn that
+   * was deferred rather than failed).
+   */
+  private finishAmbient(wait: AmbientWait, options?: { announceDeferral?: boolean }): void {
+    if (this.awaitingAmbient !== wait) return
+    const line = options?.announceDeferral === false || this.sawVisibleText
+      ? undefined
+      : backgroundDeferralLine(this.session.agentId)
+    this.closeTurn(
+      { kind: 'stop', stopReason: wait.stopReason },
+      { line, keepAmbient: wait.hard === true, requestId: wait.requestId },
+    )
+  }
+
+  /** Drop the ambient wait's clocks (the turn is being closed by someone else). */
+  private clearAmbientWait(): void {
+    const wait = this.awaitingAmbient
+    if (wait === undefined) return
+    this.awaitingAmbient = undefined
+    clearTimeout(wait.quietTimer)
+    clearTimeout(wait.hardTimer)
+  }
+
+  /**
+   * Withhold one background-drain update until the prompt response says what
+   * this turn is. The cursor advances past it anyway: it is already in the
+   * transcript, and replaying it into a later segment would emit it twice.
+   * Bounded (see `PENDING_AMBIENT_MAX_*`) — the transcript still keeps every
+   * entry the buffer drops.
+   */
+  private bufferAmbientUpdate(seq: number, update: Record<string, unknown>): void {
+    const chars = JSON.stringify(update).length
+    this.pendingAmbientUpdates.push({ seq, update, chars })
+    this.pendingAmbientChars += chars
+    while (this.pendingAmbientUpdates.length > PENDING_AMBIENT_MAX_ENTRIES
+      || (this.pendingAmbientChars > PENDING_AMBIENT_MAX_CHARS && this.pendingAmbientUpdates.length > 1)) {
+      const dropped = this.pendingAmbientUpdates.shift()
+      if (dropped === undefined) break
+      this.pendingAmbientChars -= dropped.chars
+      this.pendingAmbientTruncated = true
+    }
+  }
+
+  /** Fold the withheld drain updates into the now-ambient segment, once, in order. */
+  private flushPendingAmbient(seg: SegmentState): void {
+    if (this.pendingAmbientUpdates.length === 0) {
+      this.pendingAmbientTruncated = false
+      return
+    }
+    const truncated = this.pendingAmbientTruncated
+    this.pendingAmbientTruncated = false
+    const pending = this.pendingAmbientUpdates.splice(0, this.pendingAmbientUpdates.length)
+    this.pendingAmbientChars = 0
+    if (truncated && !seg.finished) {
+      // The front of the drain's output was evicted from the bounded buffer:
+      // say so rather than letting the turn quietly start mid-story.
+      this.emitProse(seg, 'text', '\n[dsh-ntr] background output was truncated; the ACP transcript view still has every update.\n')
+    }
+    for (const entry of pending) {
+      if (seg.finished) break
+      this.foldInto(seg, entry.update, entry.seq)
+    }
+  }
+
+  /** Drop withheld drain updates: this turn is not the drain, or it is closing. */
+  private clearPendingAmbient(): void {
+    this.pendingAmbientUpdates.length = 0
+    this.pendingAmbientChars = 0
+    this.pendingAmbientTruncated = false
+  }
+
   /** The agent settled its `session/prompt`. Ends the turn's streaming face. */
   settle(outcome: TurnSettle): void {
     if (this.settled) return
+    // `settled` is claimed NOW (a second settle, a cancel or a watchdog that
+    // races the tail drain must find the turn already spoken for), but the
+    // CLOSING work waits one macrotask: the SDK dispatches `session/update`
+    // notifications independently of the `session/prompt` RESPONSE, so the
+    // agent's last chunks can still be queued when this lands (see
+    // `settleTranscript`). Only what already reached the transcript is read —
+    // one macrotask, never an open-ended wait.
+    this.settled = true
+    this.clearAmbientWait()
+    this.clearPendingAmbient()
+    // An outside ending (watchdog, cancel) abandons a detached-worker hold: its
+    // run is no longer this turn's, so its id is retired before the close.
+    this.clearBackgroundHold({ retire: true })
+    this.pendingOutcome = outcome
+    this.closeScheduled = true
+    setImmediate(() => { this.flushScheduledClose() })
+  }
+
+  /**
+   * Force the local end of this turn — the cancel fallback and any watchdog
+   * that reached the controller. Runs the SAME closing work as a normal settle
+   * (`closeTurn`): the ambient clocks stop, the on-air segment closes (so the
+   * driver step parked on its queue ends), exactly one `turn/end` goes out
+   * with THIS turn's id, the session stops running and the prompt slot is
+   * released. Idempotent: a turn that already closed ignores the call.
+   */
+  forceFinalize(outcome: TurnSettle): void {
+    if (this.stale || this.closedTurn) return
+    this.clearAmbientWait()
+    // A forced ending abandons a detached-worker hold: retire its run's id so
+    // its late words stay transcript-only for the next turn.
+    this.clearBackgroundHold({ retire: true })
+    // A settle's deferred tail read is moot once this close runs: the turn is
+    // over now, and the pending macrotask must not drain anything into it.
+    this.pendingOutcome = undefined
+    this.closeScheduled = false
+    this.closeTurn(outcome)
+  }
+
+  /**
+   * Run the deferred closing work now, when a driver step is about to open on
+   * an already settled turn: the continuation step must see the closed turn
+   * (and the session NOT left `running` across the macrotask boundary).
+   * Idempotent — the scheduled tick then finds nothing left to do.
+   */
+  private flushScheduledClose(): void {
+    if (!this.closeScheduled) return
+    this.closeScheduled = false
+    const outcome = this.pendingOutcome
+    this.pendingOutcome = undefined
+    if (outcome === undefined) return
+    // A DISPOSE that raced this queued close cleared it (see `dispose`), so a
+    // close still scheduled here belongs to a settle that landed AFTER the
+    // stream was retired (a crash rejects its prompt only after the teardown).
+    // That turn still ends through its own queue and real id — the teardown's
+    // releaseAll frame carried an empty id.
+    this.drainTail()
+    this.closeTurn(outcome)
+  }
+
+  /**
+   * Fold the notifications that reached the transcript but not the segment:
+   * the tail a response raced past. Stops AT a cutting event without consuming
+   * it (same rule as `startSegment`) — its next segment is not this turn's.
+   */
+  private drainTail(): void {
+    // The deferred read belongs to the turn that scheduled it. If the turn was
+    // retired or a NEWER turn already began (turnSeq moved on) in this one
+    // macrotask window, everything past the cursor is the successor's: folding
+    // it here would leak its text into this turn's driver step.
+    if (this.stale) return
+    const seg = this.segment
+    if (seg === undefined || seg.finished) return
+    for (const entry of this.session.transcript.since(this.cursorSeq)) {
+      if (seg.finished) break
+      const update = entry.update as Record<string, unknown>
+      // The same split the live path makes: a background drain's text in the
+      // tail is not this turn's answer. Record what the registry needs (tool
+      // outputs), move the cursor past it, and do NOT fold it — otherwise the
+      // deferred read smuggles the drain's prose into a normal turn.
+      if (this.isForeignAmbientText(update)) {
+        this.recordWithoutSegment(update)
+        this.cursorSeq = entry.seq
+        continue
+      }
+      if (!this.foldInto(seg, update, entry.seq)) break
+      this.cursorSeq = entry.seq
+    }
+  }
+
+  /**
+   * End the turn exactly once: burst metrics, ONE `turn/end`, the provisional
+   * lock, the closing text, the segment, the session flags, the prompt slot.
+   *
+   * `ambient.line` marks a controlled ambient ending: the given line closes
+   * the segment when the turn carried no answer text, instead of the generic
+   * zero-output warning (which would blame the agent for a turn the drain
+   * simply had not finished yet). `ambient.keepAmbient` says the ending was the
+   * CEILING, not silence: see the drain-record comment below.
+   */
+  private closeTurn(outcome: TurnSettle, ambient?: { line?: string; keepAmbient?: boolean; requestId?: string }): void {
+    if (this.closedTurn) return
+    this.closedTurn = true
+    // A closed turn is a settled turn, whichever path got here first (an
+    // ambient ending does not go through `settle`).
     this.settled = true
+    this.clearAmbientWait()
+    this.clearPendingAmbient()
+    // Whoever closed this turn already decided what happens to the held
+    // run's record (`closeBackgroundHold` retired or kept it); only the clocks
+    // are still ours to drop.
+    this.clearBackgroundHold()
     // A late answer to a SUPERSEDED turn still has to close this controller's
     // queue (a continuation step may be parked on it) and its settle gate —
     // but it must not touch the session the NEWER turn now owns, nor release
@@ -3064,6 +4562,38 @@ class TurnStreamController {
         ? { kind: 'error', failure: { message: outcome.message, code: outcome.code ?? 'INTERNAL' } }
         : { kind: 'stop' }
     if (current) {
+      // An ambient ending that came from SILENCE retires the drain record with
+      // its turn: a record that outlives the wait would make the NEXT instant
+      // answer with no conversation request id look steered (see
+      // `awaitAmbient`), holding a normal turn open for a drain this one
+      // already finished waiting on. A HARD ceiling ending is the opposite
+      // evidence — the drain was still ticking when the turn was cut — so the
+      // record SURVIVES (activity clock refreshed; `ambientStaleMs` expires it
+      // lazily) precisely so the next prompt folded into the same drain is
+      // still recognised as steered. `ambientNotices` is never cleared here:
+      // a repeated announcement of the same run must stay silent, and the set
+      // is bounded where entries are added.
+      if (ambient !== undefined) {
+        if (ambient.keepAmbient === true) {
+          if (this.session.ambient !== undefined) this.session.ambient.lastActivityAt = Date.now()
+        } else {
+          // Silence closed this wait, but silence is not proof the run ended: a
+          // queued message or a long tool can make the drain speak again. So
+          // RETIRE its id before dropping the record — a revived run's late
+          // text must stay in the ACP transcript view instead of teaching the
+          // NEXT turn the drain's id and mixing the drain's answer into the
+          // user's (a double answer). The trade-off is deliberate: a next
+          // prompt the agent folds into that same revived drain may not receive
+          // the drain's text on the chat plane (transcript-only); a double
+          // answer is worse.
+          if (ambient.requestId !== undefined) retireAmbientId(this.session, ambient.requestId)
+          this.session.ambient = undefined
+        }
+      }
+      // The turn's burst aggregate must be visible before the turn is marked
+      // over: the final `turn/metrics` lands first, then `turn/end` flips the
+      // session/pill state. Persisting and broadcasting share one value.
+      this.finalizeTps()
       if (outcome.kind === 'cancelled') {
         this.hub.broadcast({ type: 'turn/end', sessionId: this.session.sessionId, turnId: this.turnId, stopReason: 'cancelled' })
       } else if (outcome.kind === 'error') {
@@ -3073,19 +4603,28 @@ class TurnStreamController {
       }
       // The provisional lock settles BEFORE any synthesized warning below: the
       // warning is our text, not evidence that the first turn delivered anything.
+      //
+      // An AMBIENT ending ends the provisional phase WITHOUT a rollback: a
+      // deferral to a background drain is not a failed first turn, the drain's
+      // text still lands in the ACP transcript view, and rolling the lock back
+      // would close the session under it — dropping exactly the output the
+      // deferred turn promised. The lock therefore becomes permanent.
       if (this.session.provisionalLock === true) {
         this.session.provisionalLock = false
-        if (!this.sawVisibleBlock) this.rollbackFirstTurn(this.session)
+        if (!this.sawVisibleBlock && ambient === undefined) this.rollbackFirstTurn(this.session)
       }
     }
     const seg = this.segment
     if (seg !== undefined) {
-      if (current && outcome.kind === 'stop' && !this.sawVisibleBlock) {
+      if (ambient !== undefined) {
+        // The ambient line is OUR report, so it only appears when the drain
+        // delivered no answer text of its own; reasoning alone does not count.
+        if (ambient.line !== undefined && current) this.emitProse(seg, 'text', ambient.line)
+      } else if (current && outcome.kind === 'stop' && !this.sawVisibleBlock) {
         // The silent-failure report: a normal stop with nothing the chat
         // plane renders. Aborted or failing turns need no extra hint; this
         // is specifically "protocol says success, the bubble is empty".
-        const line = `\n[dsh-ntr] agent "${this.session.agentId}" ended the turn with no visible output (stop reason: ${outcome.stopReason}). Some agents fold upstream failures — auth, billing, rate limits — into a normal stop; try resending, and check the agent process logs if it repeats.\n`
-        this.emitProse(seg, 'text', line)
+        this.emitProse(seg, 'text', this.zeroOutputLine(outcome.stopReason))
       }
       this.finishSegment(seg, reason)
     }
@@ -3100,23 +4639,58 @@ class TurnStreamController {
     }
     this.endTurn()
     // The controller stays indexed only while a continuation step can still
-    // come for its cards. A cancelled, failed, or card-less turn has none:
-    // retire it now; the next turn's `rememberTurnStream` would anyway.
+    // come for its cards. A cancelled, failed, or card-less turn has none: retire
+    // it now; the next turn's `rememberTurnStream` would anyway. An ambient turn
+    // ALWAYS retires: its suppressed calls never open cards, so keeping the index
+    // would pin the controller (and its session id) to a turn nobody can continue.
     if (!current) this.retire()
-    else if (outcome.kind !== 'stop' || this.seenCalls.size === 0) this.dispose()
+    else if (ambient !== undefined || outcome.kind !== 'stop' || this.seenCalls.size === 0) this.dispose()
   }
 
-  /** Cancelled by the user: finish the on-air segment and release the turn's slots. */
+  /**
+   * Cancelled by the user: finish the on-air segment and release the turn's
+   * slots. An AMBIENT turn has already released the prompt slot (its response
+   * landed) and holds no segment the cancel fallback could close, so the
+   * cancel closes the turn itself with the cancelled stop.
+   */
   abortActiveSegment(): void {
     if (this.stale) return
+    this.clearPendingAmbient()
+    if (this.closeScheduled) {
+      // `settle` claimed the turn but queued its closing work for the next
+      // macrotask. An abort landing inside that window must not let the
+      // scheduled close broadcast the RESPONSE's stop reason while the segment
+      // already finished `aborted`: drop the queued outcome and close NOW with
+      // the cancelled one, so `turn/end` and the segment's finish agree.
+      this.closeScheduled = false
+      this.pendingOutcome = undefined
+      this.closeTurn({ kind: 'cancelled' })
+      return
+    }
+    if (this.awaitingAmbient !== undefined) {
+      this.settle({ kind: 'cancelled' })
+      return
+    }
+    if (this.backgroundHold !== undefined || this.pendingBackgroundHold !== undefined) {
+      // A detached-worker hold is a turn whose prompt response already landed
+      // (the slot is free) and whose segment is still open on purpose: the
+      // cancel ends OUR face of it now, once, and the held run's id is retired
+      // so its late text cannot join the next turn.
+      this.clearBackgroundHold({ retire: true })
+      this.settle({ kind: 'cancelled' })
+      return
+    }
     this.finishActive({ kind: 'aborted', failure: { message: 'aborted', code: 'ABORTED' } })
     // The agent may take its time acknowledging the cancel, but OUR face of
-    // the turn ends now: the session stops running and a provisional first
-    // lock settles against what was actually shown. The turn SLOT stays
-    // claimed, though: the agent-side prompt is still in flight, and a second
+    // the turn ends now: the session stops running, the HOST's prompt slot is
+    // released (so a new prompt may claim it), and a provisional first lock
+    // settles against what was actually shown. The AGENT-side gate (`settled`)
+    // stays claimed: the prompt is still in flight over there, and a second
     // prompt sent into that window would be a concurrent `session/prompt` the
-    // protocol forbids — `settle` (or the cancel fallback) releases the slot.
+    // protocol forbids — `claimTurn` waits it out, `settle` (or the cancel
+    // fallback) opens it.
     this.session.running = false
+    this.session.promptInFlight = false
     if (this.session.provisionalLock === true) {
       this.session.provisionalLock = false
       if (!this.sawVisibleBlock) this.rollbackFirstTurn(this.session)
@@ -3124,9 +4698,29 @@ class TurnStreamController {
     releaseAllToolOutputWaiters()
   }
 
-  /** Stop observing and release the manager's index. Idempotent. */
+  /**
+   * Stop observing and release the manager's index. Idempotent.
+   *
+   * The segment is CLOSED here (aborted) before unsubscribing: a driver step
+   * parked on its queue (`yield* segment.queue`) only ends when the queue
+   * closes, and a controller replaced by the conversation's next turn would
+   * otherwise leave that step hanging forever. An already finished segment is a
+   * no-op, and the session's flags are left alone — a superseded turn must not
+   * mark the newer turn's session idle.
+   */
   dispose(): void {
     if (this.disposed) return
+    // A settle may have queued its closing work for the next macrotask: this
+    // close owns the turn now, so that tick must not broadcast a second
+    // `turn/end` (with this turn's real id) over the teardown.
+    this.closeScheduled = false
+    this.pendingOutcome = undefined
+    this.finishActive({ kind: 'aborted', failure: { message: 'turn stream retired', code: 'RETIRED' } })
+    this.clearAmbientWait()
+    this.clearPendingAmbient()
+    // A successor turn must never fold this hold's drain or worker text: the
+    // abandoned run's id is retired before the subscription goes away.
+    this.clearBackgroundHold({ retire: true })
     this.retire()
     releaseAllToolOutputWaiters()
   }
@@ -3187,20 +4781,73 @@ class TurnStreamController {
     } else {
       // A settled turn that never showed anything: the zero-output warning the
       // plane would have gotten from a single-stream turn (constraint 23).
-      const line = `\n[dsh-ntr] agent "${this.session.agentId}" ended the turn with no visible output. Some agents fold upstream failures — auth, billing, rate limits — into a normal stop; try resending, and check the agent process logs if it repeats.\n`
+      const line = this.zeroOutputLine()
       if (seg.index < 0) this.emitProse(seg, 'text', line)
       this.finishSegment(seg, { kind: 'stop' })
     }
   }
 
+  /**
+   * The "protocol says success, the bubble is empty" line. When a recently
+   * retired drain may have taken the prompt without re-announcing itself, say
+   * that instead of blaming the agent: the output exists in the transcript.
+   */
+  private zeroOutputLine(stopReason?: string): string {
+    if (this.recentRetiredDrain) {
+      return `\n[dsh-ntr] agent "${this.session.agentId}" produced no visible output this turn; it may have been folded into a background run; its output is in the ACP transcript view.\n`
+    }
+    const reason = stopReason === undefined ? '' : ` (stop reason: ${stopReason})`
+    return `\n[dsh-ntr] agent "${this.session.agentId}" ended the turn with no visible output${reason}. Some agents fold upstream failures — auth, billing, rate limits — into a normal stop; try resending, and check the agent process logs if it repeats.\n`
+  }
+
   private onEvent(event: unknown): void {
     if (this.disposed) return
     const row = event as { type?: string; sessionId?: string }
     if (row.sessionId !== undefined && row.sessionId !== this.session.sessionId) return
     if (row.type === 'session/update') {
       const typed = event as { sessionId: string; seq: number; update: unknown }
-      if (typed.seq <= this.cursorSeq) return
+      // Any update — a `usage_update` / phase tick included — says the
+      // background drain is still working, so the ambient quiet clock restarts.
+      this.noteAmbientActivity()
+      // A detached-worker hold's drain phase has the same rule; its worker
+      // phase never does (see `BridgeTuning.backgroundTaskMaxMs`).
+      this.noteBackgroundHoldActivity()
       const update = typed.update as Record<string, unknown>
+      // The dispatch / worker / announcement bookkeeping runs BEFORE the cursor
+      // guard: those are turn-level facts, not segment content, and an update
+      // withheld by the ambient buffer must still keep them.
+      this.trackBackgroundDispatch(update)
+      if (typed.seq <= this.cursorSeq) return
+      // A background drain's prose is not this turn's answer: keep it out of
+      // the plane (the transcript still has it). Fail-open — nothing is split
+      // until this turn has a request id of its own to compare against.
+      this.noteTurnRequestId(update)
+      if (this.isForeignAmbientText(update)) {
+        this.recordWithoutSegment(update)
+        // Advance past it only when nothing is left unconsumed behind it: the
+        // event that CUT the previous segment is parked for the next one, and
+        // jumping the cursor over it would lose its text for good. The replay
+        // applies the same foreign split, so leaving this one behind is safe.
+        if (typed.seq === this.cursorSeq + 1) this.cursorSeq = typed.seq
+        return
+      }
+      // The turn's OWN request id is still unknown and this update belongs to
+      // the background drain: folding it now could make the drain's tick teach
+      // `noteTurnRequestId` the drain's id, mixing the drain's text into the
+      // user's answer. Withhold it until the prompt response decides what this
+      // turn is (see `pendingAmbientUpdates`); the cursor moves on because the
+      // transcript already holds the entry.
+      if (this.turnRequestId === undefined
+        && this.awaitingAmbient === undefined
+        && this.isAmbientOwned(update)) {
+        this.bufferAmbientUpdate(typed.seq, update)
+        this.cursorSeq = typed.seq
+        return
+      }
+      // Live-only burst accounting runs BEFORE the segment cursor: prose that
+      // arrives between segments still belongs to this turn's output, and its
+      // gaps are real. Replay never reaches this path.
+      this.trackTps(typed)
       const seg = this.segment
       if (seg === undefined || seg.finished) {
         // Between segments: tool outputs still reach the shared registry (the
@@ -3213,16 +4860,75 @@ class TurnStreamController {
       }
       // The cursor advances only past events fully consumed into this
       // segment; the event that CUTS the segment belongs to the next one.
-      if (this.foldInto(seg, update)) this.cursorSeq = typed.seq
+      if (this.foldInto(seg, update, typed.seq)) this.cursorSeq = typed.seq
     } else if (row.type === 'permission/request') {
+      this.tps.onBreak()
       const typed = event as Extract<AcpEvent, { type: 'permission/request' }>
       this.pushProse(this.permissionLine(typed))
     } else if (row.type === 'permission/expired') {
+      this.tps.onBreak()
       const typed = event as { toolCall: unknown; timeoutMs: number; outcome: PermissionOutcome; optionName?: string }
       this.pushProse(this.expiredLine(typed))
     }
   }
 
+  /** Feed one live update into the turn's burst tracker. Never called by replay. */
+  private trackTps(typed: { seq: number; update: unknown }): void {
+    if (typed.seq <= this.tpsSeq) return
+    this.tpsSeq = typed.seq
+    const update = typed.update as Record<string, unknown>
+    const kind = String(update.sessionUpdate ?? '')
+    if (kind === 'agent_thought_chunk' || kind === 'agent_message_chunk') {
+      const text = chunkTextOf(update.content)
+      if (text === '') return
+      this.tps.onProse(text, Date.now())
+      this.pushLiveTps()
+    } else if (kind === 'tool_call' || kind === 'tool_call_update') {
+      this.tps.onBreak()
+    }
+  }
+
+  /** Throttled live aggregate so the dock's speed moves during a long turn. */
+  private pushLiveTps(): void {
+    const dshSessionId = this.session.dshSessionId
+    if (dshSessionId === undefined) return
+    const now = Date.now()
+    if (now - this.lastTpsPushAt < TPS_PUSH_INTERVAL_MS) return
+    const snap = this.tps.snapshot()
+    if (snap.outputTokens <= 0 || snap.burstMs <= 0) return
+    this.lastTpsPushAt = now
+    const base = this.session.burst ?? { outputTokens: 0, burstMs: 0 }
+    this.hub.broadcast({
+      type: 'turn/metrics',
+      sessionId: this.session.sessionId,
+      dshSessionId,
+      turnId: this.turnId,
+      outputTokens: base.outputTokens + snap.outputTokens,
+      burstMs: base.burstMs + snap.burstMs,
+      final: false,
+    })
+  }
+
+  /** Close the turn's metrics: persist the measurable part, then broadcast it. */
+  private finalizeTps(): void {
+    const dshSessionId = this.session.dshSessionId
+    if (dshSessionId === undefined) return
+    const snap = this.tps.snapshot()
+    if (snap.outputTokens > 0 && snap.burstMs > 0) {
+      this.manager.noteSessionBurst(this.session, snap.outputTokens, snap.burstMs)
+    }
+    const aggregate = this.session.burst ?? { outputTokens: 0, burstMs: 0 }
+    this.hub.broadcast({
+      type: 'turn/metrics',
+      sessionId: this.session.sessionId,
+      dshSessionId,
+      turnId: this.turnId,
+      outputTokens: aggregate.outputTokens,
+      burstMs: aggregate.burstMs,
+      final: true,
+    })
+  }
+
   /**
    * Put one narrative line into the turn's prose stream.
    *
@@ -3259,15 +4965,115 @@ class TurnStreamController {
     recordAcpToolOutput(callId, updateContentToText(update.content))
   }
 
+  /**
+   * Whether this update belongs to a background drain — the one the session is
+   * waiting on, or one whose wait already closed (retired) but whose run can
+   * still speak.
+   */
+  private isAmbientOwned(update: Record<string, unknown>): boolean {
+    const requestId = codebuddyMetaOf(update)?.requestId
+    if (requestId === undefined) return false
+    return requestId === this.session.ambient?.requestId
+      || isRetiredAmbientId(this.session, requestId)
+  }
+
+  /** Learn this turn's own CodeBuddy request id from the first update naming one. */
+  private noteTurnRequestId(update: Record<string, unknown>): void {
+    if (this.turnRequestId !== undefined) return
+    const meta = codebuddyMetaOf(update)
+    // A detached worker's update names A WORKER, never this turn: adopting it
+    // would let the worker's own turn pass as the session's answer.
+    if (meta?.parentToolCallId !== undefined) return
+    // While a hold runs, the only ids this turn owns are the drain ids it
+    // accepted (see `BackgroundHold.acceptedIds`) — and those belong to the
+    // background run, never to a second "own turn id" that would outlive the
+    // hold. Nothing else may be adopted.
+    if (this.activeBackgroundHold() !== undefined) return
+    const requestId = meta?.requestId
+    // A background drain's update names THE DRAIN, never this turn: adopting it
+    // would make `isForeignAmbientText` pass the drain's own text through. A
+    // RETIRED drain (its wait closed on silence, the run revived) is the same
+    // trap — that id belongs to the background run whichever turn is on air.
+    if (requestId === undefined || requestId === this.session.ambient?.requestId) return
+    if (isRetiredAmbientId(this.session, requestId)) return
+    this.turnRequestId = requestId
+  }
+
+  /** Adopt the request id the prompt RESPONSE declared for this turn. */
+  adoptTurnRequestId(requestId: string): void {
+    // A retired drain id is never this turn's own: adopting it would make the
+    // background run's prose pass `isForeignAmbientText` as the answer. The
+    // response still ends a normal turn, so the withheld drain buffer is
+    // dropped either way (the transcript keeps it).
+    if (!isRetiredAmbientId(this.session, requestId)) this.turnRequestId = requestId
+    // A normal turn: whatever the drain streamed while the id was unknown was
+    // never this turn's answer. Drop it (the transcript keeps it) — it must not
+    // surface when a later segment replays or when the turn flushes anything.
+    this.clearPendingAmbient()
+  }
+
+  /**
+   * Prose of the session's background drain while this turn runs on its OWN
+   * request id: it belongs to the background run, not to the user's answer.
+   * Fail-open by design — an unknown turn id splits nothing, and a turn that
+   * was itself folded into the drain keeps its prose.
+   */
+  private isForeignAmbientText(update: Record<string, unknown>): boolean {
+    const meta = codebuddyMetaOf(update)
+    const requestId = meta?.requestId
+    // A detached worker's own turn is never this session's answer, whichever
+    // turn is on air (the fold-level guard lives in `foldInto` as well, for
+    // the replay paths that never ask this question). This includes a worker
+    // update that also names a drain id: its prose is the WORKER's.
+    if (meta?.parentToolCallId !== undefined) return true
+    // A detached-worker hold owns the drain phase: any run it accepted (the
+    // response's id, an announcement that named a different one) is this
+    // turn's answer, and every OTHER id is background noise — whatever the
+    // turn's own id says. Parked holds count: the response already owns them.
+    const hold = this.activeBackgroundHold()
+    if (hold !== undefined) {
+      if (requestId === undefined) return false
+      return !hold.acceptedIds.has(requestId)
+    }
+    // The drain THIS turn is waiting on owns its text unconditionally: the
+    // wait was opened for this id (a revived drain may still carry a retired
+    // mark if the update raced the revival), so the whole steered answer must
+    // reach the user instead of being filtered as background noise.
+    if (requestId !== undefined && this.awaitingAmbient?.requestId === requestId) return false
+    // A RETIRED drain is foreign even though its record is gone: the quiet
+    // close only means WE stopped waiting, not that the run ended. Its late
+    // text must never join the turn now on air — even before that turn has
+    // learned a request id of its own (the fail-open below does not apply to
+    // an id known to be a background run).
+    if (isRetiredAmbientId(this.session, requestId)) return true
+    if (this.turnRequestId === undefined) return false
+    if (requestId === undefined || requestId === this.turnRequestId) return false
+    const ambient = this.session.ambient
+    return ambient !== undefined && requestId === ambient.requestId
+  }
+
   /**
    * The turn's whole fold, shared by live events and segment replay. Visible
    * non-tool events END a card-bearing segment instead of joining it — that is
    * the segmentation rule that puts each card between two assistant messages.
    * Returns whether the event was consumed into this segment: the cutting
    * event is left unconsumed (and thus behind the cursor) for the next one.
+   *
+   * `seq` is the update's transcript position when the caller has one: the
+   * detached-worker hold uses it to count only the answer text that arrived
+   * AFTER the hold began (a parked hold replays the parent's earlier ack).
    */
-  private foldInto(seg: SegmentState, update: Record<string, unknown>): boolean {
+  private foldInto(seg: SegmentState, update: Record<string, unknown>, seq?: number): boolean {
     const kind = String(update.sessionUpdate ?? '')
+    // A DETACHED WORKER's own turn: its words and tools are the worker's, not
+    // this session's answer. The transcript keeps them (the ACP view is where
+    // the user can read them) and the shared tool-output registry still sees
+    // the call, but nothing reaches this turn's message and no card opens for
+    // the host to execute. This applies to EVERY turn, not just a hold.
+    if (codebuddyMetaOf(update)?.parentToolCallId !== undefined) {
+      this.noteToolRecord(update)
+      return true
+    }
     if (kind === 'agent_thought_chunk' || kind === 'agent_message_chunk') {
       const text = chunkTextOf(update.content)
       if (text === '') return true
@@ -3276,10 +5082,34 @@ class TurnStreamController {
         return false
       }
       seg.outputChars += text.length
+      // "The turn's own answer", as opposed to a background drain's prose that
+      // happens to stream through the same session (see `isForeignAmbientText`).
+      if (!this.isAmbientOwned(update)) this.sawAgentProse = true
+      if (kind === 'agent_message_chunk') {
+        this.sawVisibleText = true
+        // A hold's closing line asks whether ITS runs delivered answer text.
+        // The parent's interim acknowledgement arrived before the hold and
+        // already set `sawVisibleText`, so the hold keeps its own counter —
+        // and only text that arrived after the hold began counts (a parked
+        // hold replays that earlier ack from the transcript).
+        const hold = this.activeBackgroundHold()
+        if (hold !== undefined && (seq === undefined || seq > hold.floorSeq)) {
+          hold.answerChars += text.length
+        }
+      }
       this.emitProse(seg, kind === 'agent_thought_chunk' ? 'reasoning' : 'text', text)
       return true
     } else if (kind === 'tool_call' || kind === 'tool_call_update') {
       this.noteToolRecord(update)
+      if (seg.ambient || this.isAmbientOwned(update)) {
+        // A background drain's tools stay in the transcript: opening a card
+        // would make the host execute a tool and propose a continuation step
+        // for a turn whose answer has not started yet. The ownership check
+        // covers a NORMAL turn too — its own segment is not ambient, but a
+        // drain can stream a tool call on the same session while it runs, and
+        // that call is not this turn's work.
+        return true
+      }
       const snapshot = acpToolCallFromUpdate(update)
       if (snapshot === undefined) return true
       if (seg.activeType === 'tool-call' && seg.activeToolCall?.callId === snapshot.callId) {
@@ -3291,6 +5121,12 @@ class TurnStreamController {
         return true
       }
       if (this.seenCalls.has(snapshot.callId)) return true // a restatement of a card already settled
+      // A BARE status-only update for a call this turn never announced is not
+      // a card. The real wire sends the detached dispatch's completion exactly
+      // that way (no `_meta`, no title, no input); a turn that begins after the
+      // dispatch belongs to another turn's card, and opening one here would
+      // make the host execute a phantom tool.
+      if (kind === 'tool_call_update' && snapshot.name === '' && snapshot.argsRaw === '') return true
       this.seenCalls.add(snapshot.callId)
       this.openToolCallBlock(seg, snapshot)
       return true
@@ -3524,6 +5360,34 @@ export class BridgeManager {
     return this.turnStreams.get(dshSessionId)
   }
 
+  /**
+   * The ambient windows a turn's controller reads once at construction (see
+   * {@link BridgeTuning.ambientQuietMs}). Exposed as a plain snapshot so the
+   * controller never pokes at the manager's tuning object, and tests can tune
+   * the cadence through the constructor like every other window.
+   */
+  get ambientTuning(): { quietMs: number; maxMs: number } {
+    return {
+      quietMs: this.tuning.ambientQuietMs,
+      maxMs: this.tuning.ambientMaxMs,
+    }
+  }
+
+  /**
+   * The detached-worker hold's windows, read once at controller construction
+   * for the same reason as {@link ambientTuning}: `taskMaxMs` is the worker
+   * phase's only clock (see {@link BridgeTuning.backgroundTaskMaxMs}) and
+   * `graceMs` the bounded wait a PARKED hold gives the host to open its
+   * continuation step (see {@link BridgeTuning.backgroundParkedGraceMs}). The
+   * drain phase reuses {@link ambientTuning}.
+   */
+  get backgroundTuning(): { taskMaxMs: number; graceMs: number } {
+    return {
+      taskMaxMs: this.tuning.backgroundTaskMaxMs,
+      graceMs: this.tuning.backgroundParkedGraceMs,
+    }
+  }
+
   /** Index a turn's controller, retiring whatever turn it supersedes. */
   rememberTurnStream(dshSessionId: string, controller: TurnStreamController): void {
     const previous = this.turnStreams.get(dshSessionId)
@@ -3722,6 +5586,13 @@ export class BridgeManager {
     this.sessionWorkspaceResolver = resolver
   }
 
+  /**
+   * Set the attachment service or context used to resolve image attachments in user prompts.
+   */
+  setAttachmentResolver(resolver?: unknown): void {
+    this.attachmentResolver = resolver
+  }
+
   /**
    * Wire the ACP-mode probe: given a DSH session id, report whether that
    * session runs the ACP agent preset. The host half reads it back from the
@@ -3836,6 +5707,7 @@ export class BridgeManager {
         ...(session.modes === undefined ? {} : { modes: session.modes }),
         ...(session.availableCommands === undefined ? {} : { availableCommands: session.availableCommands }),
         ...(session.usage === undefined ? {} : { usage: session.usage }),
+        ...(session.burst === undefined ? {} : { burst: session.burst }),
         ...(session.released ? { released: true } : {}),
         ...(session.running ? { running: true } : {}),
         ...forkRowInfo(session, this.canForkNow(session.agentId)),
@@ -4733,6 +6605,21 @@ export class BridgeManager {
     for (const dshSessionId of this.chatAgentIntent.keys()) this.syncConversationRoute(dshSessionId)
   }
 
+  /**
+   * Fold one settled ACP turn's measurable burst into the session aggregate and
+   * persist it. A turn with no measured inter-chunk gap contributes neither
+   * side: adding its tokens with zero time would inflate the session rate.
+   */
+  noteSessionBurst(session: LiveSession, outputTokens: number, burstMs: number): void {
+    if (outputTokens <= 0 || burstMs <= 0) return
+    const base = session.burst ?? { outputTokens: 0, burstMs: 0 }
+    session.burst = {
+      outputTokens: base.outputTokens + outputTokens,
+      burstMs: base.burstMs + burstMs,
+    }
+    this.persistAgents()
+  }
+
   private persistAgents(): void {
     const filePath = this.getStoragePath()
     if (!filePath) return
@@ -4798,8 +6685,8 @@ export class BridgeManager {
       if (typeof dshSessionId !== 'string' || dshSessionId === '') continue
       if (typeof cwd !== 'string') continue
       if (!this.defsMap.has(agentId)) continue
-      const { title, modelId, reasoningEffort, modes, usage, hasHistory } = record as {
-        title?: unknown; modelId?: unknown; reasoningEffort?: unknown; modes?: unknown; usage?: unknown; hasHistory?: unknown
+      const { title, modelId, reasoningEffort, modes, usage, burst, hasHistory } = record as {
+        title?: unknown; modelId?: unknown; reasoningEffort?: unknown; modes?: unknown; usage?: unknown; burst?: unknown; hasHistory?: unknown
       }
       const session: LiveSession = {
         sessionId,
@@ -4814,6 +6701,7 @@ export class BridgeManager {
         ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
         ...(isPersistedModes(modes) ? { modes } : {}),
         ...(isPersistedUsage(usage) ? { usage } : {}),
+        ...(isPersistedBurst(burst) ? { burst } : {}),
         ...(hasHistory === true ? { hasHistory: true } : {}),
         running: false,
         turnSeq: 0,
@@ -5083,6 +6971,10 @@ export class BridgeManager {
   private autoExposeNewModels(agentId: string, next: AcpAgentCatalog, before: AcpAgentCatalog | undefined): boolean {
     const def = this.defsMap.get(agentId)
     if (def === undefined || def.autoDiscoverModels === false || before === undefined) return false
+    // A different model-slot identity is a corrected reading, not newly added
+    // models. Diffing across it would expose an entire real catalog the first
+    // time a parser fix replaces a mislabelled slot (Qoder CN).
+    if (before.model !== undefined && next.model !== undefined && before.model.configId !== next.model.configId) return false
     const known = new Set((before.model?.choices ?? []).map(choice => choice.value))
     const exposed = new Set(def.exposedModels ?? [])
     const added = (next.model?.choices ?? [])
@@ -5473,6 +7365,11 @@ export class BridgeManager {
   private staleModelChoice(session: LiveSession, modelChoice: string | undefined): string | undefined {
     const wanted = modelChoice !== undefined && modelChoice !== '' ? modelChoice : undefined
     if (wanted === undefined) return undefined
+    // `category` is a UX hint, not identity: an agent may publish several
+    // `category: 'model'` options (Qoder CN ships `reasoning_effort` that way)
+    // and no explicit `model` id. In that case the selector is a guess, so a
+    // "not offered" verdict would refuse a perfectly valid pick — fail open.
+    if (!hasUnambiguousModelSelector(session.configOptions)) return undefined
     const model = parseCatalogOptions(session.configOptions).model
     if (model === undefined) return undefined
     if (model.currentValue === wanted) return undefined
@@ -5712,7 +7609,7 @@ export class BridgeManager {
     return { sessionId: session.sessionId }
   }
 
-  async prompt(sessionId: string, text: string): Promise<{ turnId: string }> {
+  async prompt(sessionId: string, prompt: string | ContentBlock[]): Promise<{ turnId: string }> {
     let located = await this.locateOrResume(sessionId)
     // The watchdog abandoned a previous turn here and the agent may still be
     // holding its prompt slot on the old process: reclaim BEFORE sending, or
@@ -5730,7 +7627,40 @@ export class BridgeManager {
       located = await this.locateOrResume(sessionId)
     }
     const { bridge, session } = located
-    if (session.running) throw new AcpError('turn_in_flight', 'acp: this session already has a prompt in flight')
+    // The agent prompt slot is SHARED with chat turns: `running` alone misses
+    // a chat turn whose cancellation already released it (`running` false,
+    // `promptInFlight` still naming the agent-side turn), and a live chat
+    // controller means a continuation step may resume the SAME agent turn.
+    // A controller that already SETTLED (kept only so its card's continuation
+    // can still stream) has given the agent slot back: `/acp` may use it, and
+    // advancing `turnSeq` retires it — the behaviour the stale-controller
+    // watchdog case pins.
+    const chatController = session.turnController
+    if (session.running
+      || session.promptInFlight === true
+      || (chatController !== undefined && !chatController.stale && !chatController.hasSettled)) {
+      throw new AcpError('turn_in_flight', 'acp: this session already has a prompt in flight')
+    }
+
+    const blocks: ContentBlock[] = typeof prompt === 'string'
+      ? [{ type: 'text', text: prompt }]
+      : prompt
+
+    if (blocks.length === 0) {
+      throw new AcpError('empty_prompt', 'acp: prompt cannot be empty')
+    }
+
+    const hasImages = blocks.some(b => b.type === 'image')
+    if (hasImages && bridge.initResult?.agentCapabilities?.promptCapabilities?.image !== true) {
+      throw new AcpError('image_unsupported', `acp: agent "${bridge.def.id}" does not support image input`)
+    }
+
+    // Claim the SAME slot the chat path claims (`claimTurn` + `beginTurn`): an
+    // `/acp` turn in flight must make the next chat prompt wait, and vice
+    // versa. The settler is idempotent and identity-guarded; the turn still
+    // ends through `turn/end` below, so chat and RPC turns share one gate
+    // without sharing a stream controller.
+    const endTurn = bridge.beginTurn(session)
     session.running = true
     session.turnSeq += 1
     const turnGen = session.turnSeq
@@ -5741,9 +7671,12 @@ export class BridgeManager {
     session.reclaimedTurnSeq = undefined
     this.armStallTimer()
     const turnId = randomUUID()
-    this.hub.broadcast({ type: 'turn/start', sessionId, turnId, text })
-    void bridge.runPrompt(session, text, turnId)
-      .then(stopReason => {
+    const promptText = typeof prompt === 'string'
+      ? prompt
+      : blocks.filter(b => b.type === 'text').map(b => (b as { text: string }).text).join('\n')
+    this.hub.broadcast({ type: 'turn/start', sessionId, turnId, text: promptText })
+    void bridge.runPrompt(session, blocks, turnId, turnGen)
+      .then(result => {
         // The reclaim already ended this turn locally; the answer it caused is
         // that same turn reporting back, not a second turn end for the caller.
         if (session.reclaimedTurnSeq === turnGen) {
@@ -5753,8 +7686,11 @@ export class BridgeManager {
         // A superseded turn's late answer must not end the turn now on air.
         if (session.turnSeq !== turnGen) return
         this.clearOrphanPrompt(session, turnGen)
+        // Release the shared slot BEFORE the terminal frame: a listener that
+        // sends the next prompt on `turn/end` must not read a stale claim.
+        endTurn()
         session.running = false
-        this.hub.broadcast({ type: 'turn/end', sessionId, turnId, stopReason })
+        this.hub.broadcast({ type: 'turn/end', sessionId, turnId, stopReason: result.stopReason })
       })
       .catch((error: unknown) => {
         if (session.reclaimedTurnSeq === turnGen) {
@@ -5771,6 +7707,7 @@ export class BridgeManager {
           return
         }
         this.clearOrphanPrompt(session, turnGen)
+        endTurn()
         session.running = false
         this.hub.broadcast({
           type: 'turn/end',
@@ -5779,6 +7716,9 @@ export class BridgeManager {
           error: describeError(error),
         })
       })
+      // Every outcome — normal answer, failure, reclaim early-return, or a
+      // close's rejection — releases the shared prompt slot exactly once.
+      .finally(() => { endTurn() })
     return { turnId }
   }
 
@@ -6104,6 +8044,7 @@ export class BridgeManager {
   }
   private sessionWorkspaceResolver?: SessionWorkspaceResolver
   private acpModeResolver?: AcpModeResolver
+  private attachmentResolver?: unknown
   /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
   private readonly acpModeCache = new Map<string, boolean>()
   /** In-flight cold reads behind `chatSessionAcpModeAnswer`, keyed by session id. */
@@ -6378,6 +8319,47 @@ export class BridgeManager {
     return { ok: true, reset: true }
   }
 
+  /**
+   * 聊天插话的槽位回收：宿主把插话作为同一会话在飞回合的下一步送达，
+   * 拒绝会让整条 host turn 失败。ACP 不能向运行中的 prompt 注入消息，
+   * 所以按插话语义中止当前回合，等 agent 真正结算后再让调用方重发。
+   *
+   * 只处理 `claimTurn` 的 `busy`（agent 仍持有本会话 prompt）；`unsettled`
+   * 说明我们这一侧已经释放过槽位（用户按过停止），保持原样拒绝。
+   *
+   * - 控制器已 settle（响应已到，延后收口还没释放闸门）：什么都不取消，只等闸门；
+   * - agent 真在跑：走用户取消同一条管线（session/cancel + 结算权限 + cancel fallback），
+   *   并立即关闭宿主这一侧的 segment，让闸门在 agent 应答/兜底后打开。
+   */
+  private async reclaimChatPrompt(
+    session: LiveSession,
+    controller: TurnStreamController,
+    signal?: AbortSignal,
+  ): Promise<'ok' | 'aborted'> {
+    if (session.closed || session.released) return 'ok'
+    if (!controller.hasSettled && session.promptInFlight === true) {
+      await this.bridge(session.agentId).cancel(session)
+      controller.abortActiveSegment()
+    }
+    return this.waitForSettleGate(session, signal)
+  }
+
+  /** 等 agent 侧 prompt slot 真正释放；步骤被取消时立即返回 aborted。 */
+  private waitForSettleGate(session: LiveSession, signal?: AbortSignal): Promise<'ok' | 'aborted'> {
+    const pending = session.settled
+    if (pending === undefined) return Promise.resolve('ok')
+    if (signal?.aborted) return Promise.resolve('aborted')
+    return new Promise(resolve => {
+      const done = (value: 'ok' | 'aborted'): void => {
+        signal?.removeEventListener('abort', onAbort)
+        resolve(value)
+      }
+      const onAbort = (): void => { done('aborted') }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      void pending.then(() => { done('ok') })
+    })
+  }
+
   async *streamPrompt(options: GenerateOptions): AsyncIterable<StreamChunk> {
     // The plugin's own conversation↔agent mapping decides who serves the turn
     // (see `bindChatAgent`): the driver may arrive here with the previous
@@ -6469,8 +8451,36 @@ export class BridgeManager {
     // Forward the person's own words: the host folds its context sections
     // (AGENTS.md digest, skill catalog, runtime snapshot) after the claimed user
     // batch precisely so a consumer can tell them apart by `source` — see
-    // `selectForwardPrompt` and AGENTS.md rule 16.
-    const selection = selectForwardPrompt(options.messages ?? [])
+    const workspaceRoot = chatWorkspaceRoot(this.sessionWorkspaceResolver, options.sessionId)
+    const defaultReadFile = (p: string) => {
+      try {
+        if (existsSync(p)) return readFileSync(p)
+        if (workspaceRoot !== undefined && !isAbsolutePath(p)) {
+          const joined = join(workspaceRoot, p)
+          if (existsSync(joined)) return readFileSync(joined)
+        }
+      } catch {}
+      return undefined
+    }
+
+    const resolver = this.attachmentResolver
+    const attachmentContext = resolver !== undefined && typeof resolver === 'object' && resolver !== null
+      ? Object.assign(Object.create(resolver), {
+          readFile: (p: string) => {
+            if (typeof (resolver as { readFile?: unknown }).readFile === 'function') {
+              try {
+                const res = (resolver as { readFile: (p: string) => unknown }).readFile(p)
+                if (res !== undefined) return res
+              } catch {}
+            }
+            return defaultReadFile(p)
+          },
+        })
+      : {
+          readFile: defaultReadFile,
+        }
+
+    const selection = selectForwardPrompt(options.messages ?? [], attachmentContext)
     if (selection.kind === 'no-user-input') {
       // An injected-context wake: nothing the user said, nothing to send.
       yield { type: 'finish', reason: { kind: 'stop' } }
@@ -6537,29 +8547,101 @@ export class BridgeManager {
       return
     }
 
-    // One prompt slot per session, and a turn the user aborted still occupies
-    // the AGENT's slot until it acknowledges the cancel (see `claimTurn`).
-    const claim = await bridge.claimTurn(session)
-    if (!claim.ok) {
-      // A first turn that never got the prompt slot delivered nothing either:
-      // give the conversation back instead of leaving it locked to an agent
-      // that refused the only message it was asked to serve.
+    const hasImages = (selection.images?.length ?? 0) > 0 || (selection.content?.some(b => b.type === 'image') ?? false)
+    if (hasImages && bridge.initResult?.agentCapabilities?.promptCapabilities?.image !== true) {
       if (session.provisionalLock === true) this.rollbackFirstTurn(session)
       yield {
         type: 'finish',
         reason: {
           kind: 'error',
           failure: {
-            message: claim.reason === 'busy'
-              ? 'acp: this session already has a prompt in flight'
-              : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
-            code: 'turn_in_flight',
+            message: `acp: agent "${agentId}" does not support image input`,
+            code: 'image_unsupported',
           },
         },
       }
       return
     }
 
+    // One prompt slot per session, and a turn the user aborted still occupies
+    // the AGENT's slot until it acknowledges the cancel (see `claimTurn`).
+    let claim = await bridge.claimTurn(session)
+    if (!claim.ok) {
+      // A STEER ("插话"): the host delivers the user's mid-turn message as the
+      // NEXT step of the SAME host turn, so the conversation's own ACP prompt
+      // is still on air. Refusing would fail the whole host turn. ACP forbids
+      // injecting into a running prompt, so the steer's real semantic — abort
+      // the current turn, then send this one — is spelled cancel + wait +
+      // re-claim here.
+      //
+      // Only `busy` can be a steer: it means the AGENT still holds OUR prompt
+      // (`promptInFlight`). `unsettled` means our side already released the
+      // slot (the person pressed stop, or an earlier steer cancelled): the
+      // agent has not acknowledged yet, and quietly queueing the next message
+      // behind a turn the user stopped is not this path's business — that
+      // stays the honest `turn_in_flight` refusal below.
+      //
+      // Only the conversation's OWN in-flight turn qualifies (its live stream
+      // controller, on this very session). A `/acp` RPC turn has no chat
+      // controller, and another conversation never reaches this session, so
+      // both keep the plain refusal: nothing may be cancelled behind a
+      // caller's back.
+      const chatController = claim.reason === 'busy' && options.sessionId !== undefined
+        ? this.turnStreamFor(options.sessionId)
+        : undefined
+      if (options.sessionId !== undefined
+        && chatController !== undefined
+        && !chatController.stale
+        && chatController.session === session) {
+        const reclaimed = await this.reclaimChatPrompt(session, chatController, options.signal)
+        if (reclaimed === 'aborted') {
+          // The person pressed stop while the previous turn was winding down:
+          // the steer is theirs to re-send, nothing goes to the agent.
+          yield {
+            type: 'finish',
+            reason: { kind: 'aborted', failure: { message: 'aborted', code: 'ABORTED' } },
+          }
+          return
+        }
+        // A first turn that produced nothing rolled its provisional lock back
+        // and CLOSED (and forgot) this session: the steer needs a fresh one.
+        if (session.closed || session.released) {
+          try {
+            session = await this.getOrCreateDshSession(options.sessionId, agentId)
+          } catch (err) {
+            yield {
+              type: 'finish',
+              reason: { kind: 'error', failure: { message: describeError(err), code: 'session_init_failed' } },
+            }
+            return
+          }
+        }
+        // Same bridge: the session may have been re-created, but the
+        // conversation is still served by this agent's process.
+        claim = await bridge.claimTurn(session)
+      }
+      if (!claim.ok) {
+        // Never roll the provisional lock back here: a failed claim means
+        // ANOTHER prompt holds the slot (or the agent has not settled it), and
+        // that turn owns the conversation's lock. Closing the session would
+        // kill a turn that is actively streaming — the refusal already tells
+        // the user to retry.
+        yield {
+          type: 'finish',
+          reason: {
+            kind: 'error',
+            failure: {
+              message: claim.reason === 'busy'
+                ? 'acp: this session already has a prompt in flight'
+                : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
+              code: 'turn_in_flight',
+            },
+          },
+        }
+        return
+      }
+    }
+
     // Same-agent model/effort switches ride the SAME ACP session (context
     // stays continuous); switching to another agent lands in a separate one
     // via the `${dshSessionId}:${agentId}` key in getOrCreateDshSession.
@@ -6682,8 +8764,12 @@ export class BridgeManager {
       // next turn has to respect. Settlement reaches the controller, which
       // releases the slot (`endTurn`) whether the segment on air is the first
       // or a continuation one.
-      bridge.runPrompt(session, promptText, turnId)
-        .then(stopReason => {
+      const promptBlocks: ContentBlock[] = selection.content && selection.content.length > 0
+        ? selection.content as ContentBlock[]
+        : [{ type: 'text', text: promptText }]
+
+      bridge.runPrompt(session, promptBlocks, turnId, turnGen)
+        .then(result => {
           // The reclaim already ended this turn locally, and the close it
           // performed rejected this very request: the late answer is that same
           // turn, not a second one to broadcast.
@@ -6691,9 +8777,79 @@ export class BridgeManager {
             session.reclaimedTurnSeq = undefined
             return
           }
-          controller.settle(stopReason === 'cancelled'
+          const responseMeta = codebuddyMetaOf({ _meta: result.meta })
+          // A DETACHED-WORKER HOLD: this turn's `Agent` call handed real work
+          // to a background worker that has not produced its answer yet, yet
+          // the agent answered the prompt normally (CodeBuddy says "已派…" and
+          // ends its own turn). Closing here loses the only answer the turn
+          // will ever produce — the worker's report streams into this same
+          // session later, as a background drain. Hold the turn open until
+          // every dispatch reports and the drain goes quiet (see
+          // `holdForBackgroundDispatch`); the prompt slot is released there.
+          //
+          // The decision comes BEFORE `adoptTurnRequestId`: adopting the id
+          // would clear the updates the drain streamed while this turn's own id
+          // was unknown, and those are exactly the ones the hold must fold.
+          const holdDispatch = controller.dispatchedDetachedWorker
+            && !session.released
+            && !session.closed
+            && result.stopReason !== 'cancelled'
+          if (!holdDispatch && responseMeta?.conversationRequestId !== undefined) {
+            // The response names the conversation turn it queued: an instant
+            // answer that still carries one is a real (if silent) turn, and its
+            // prose can be told apart from a background drain's.
+            controller.adoptTurnRequestId(responseMeta.conversationRequestId)
+          }
+          // An announced drain that has shown NO sign of life for the staleness
+          // window is over, even though nothing said so (CodeBuddy never sends
+          // `session_end`). Keeping the record would make a later instant answer
+          // with no conversation request id look steered, and hold a normal turn
+          // open against a drain that is never coming back. RETIRE the id
+          // first, so a late update or a response naming it is never adopted as
+          // this session's own turn; then forget the record (the notice de-dupe
+          // set with it) so this response settles normally.
+          if (session.ambient !== undefined
+            && Date.now() - session.ambient.lastActivityAt > this.tuning.ambientStaleMs) {
+            retireAmbientId(session, session.ambient.requestId)
+            session.ambient = undefined
+            session.ambientNotices?.clear()
+          }
+          if (holdDispatch) {
+            // The response may name one run while an announcement named
+            // another; the hold accepts both (see `BackgroundHold.acceptedIds`).
+            controller.holdForBackgroundDispatch(
+              result.stopReason,
+              responseMeta?.conversationRequestId ?? responseMeta?.requestId,
+            )
+            return
+          }
+          // An instant answer with NO conversation request id, while the agent
+          // announced a background drain this turn has not spoken into: the
+          // prompt was folded into that drain (CodeBuddy's multitask). The
+          // response is a formality — keep the turn open until the drain speaks.
+          if (session.ambient !== undefined
+            && !session.released
+            && !session.closed
+            && result.stopReason !== 'cancelled'
+            && responseMeta?.conversationRequestId === undefined
+            && !controller.hasAgentProse) {
+            controller.awaitAmbient(session.ambient.requestId, result.stopReason)
+            return
+          }
+          // No ambient record to wait on, but a drain this session stopped
+          // waiting on was retired moments ago: the run may have taken this
+          // prompt WITHOUT re-announcing itself. The turn cannot be held open
+          // (nothing names the drain), but a silent close must say the output
+          // may be in the transcript instead of blaming the agent.
+          if (session.ambient === undefined
+            && result.stopReason !== 'cancelled'
+            && responseMeta?.conversationRequestId === undefined
+            && hasRecentRetiredAmbient(session, Math.max(this.tuning.ambientQuietMs * 2, RETIRED_AMBIENT_RECENT_MIN_MS))) {
+            controller.noteRecentRetiredDrain()
+          }
+          controller.settle(result.stopReason === 'cancelled'
             ? { kind: 'cancelled' }
-            : { kind: 'stop', stopReason })
+            : { kind: 'stop', stopReason: result.stopReason })
         })
         .catch((err: unknown) => {
           if (session.reclaimedTurnSeq === turnGen) {