dsh-ntr 0.3.1 → 0.3.3

package/src/bridge.ts

@@ -20,6 +20,7 @@ import {
   PROTOCOL_VERSION,
   RequestError,
   type ClientConnection,
+  type ContentBlock,
   type InitializeResponse,
   type McpServer,
   type McpServerHttp,
@@ -52,6 +53,7 @@ import {
   resolveFsPath,
   resolveSessionCwd,
   selectForwardPrompt,
+  isAbsolutePath,
   acpPresetStatusFromRoster,
   splitAdapterModelId,
   updateContentToText,
@@ -69,11 +71,12 @@ import type {
   RosterPresetRow,
 } from './impl.ts'
 import type {
-  AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPresetStatus, AcpReleaseCause, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike,
+  AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPresetStatus, AcpReleaseCause, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionForkInfo, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike,
   LlmModelInfo, LlmModelReasoningInfo, LlmProviderInfo, LlmReasoningEffortInfo, LlmResolvedModelInfo,
-  ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionOutcome, PermissionOptionView, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk,
+  AcpIdleRelease, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionOutcome, PermissionOptionView, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk,
 } from './protocol.ts'
-import { DEFAULT_TAG_HALO } 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,10 +137,42 @@ 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
+  /**
+   * The agent-side session has history while the LOCAL buffer is empty: this
+   * record was restored from disk after a host restart (the replay has not
+   * landed yet), or a resume cleared the buffer ahead of the replay. The ACP
+   * view then says history replays on restore instead of "nothing yet". Set
+   * by `doResumeSession` (captured before the reset) and the restore path; the
+   * serializer ORs it with the live buffer length.
+   */
+  hasHistory?: boolean
   /**
    * When the agent last showed ANY sign of life on this session: an update, a
    * permission ask (arrival or answer), or a turn start. The stall watchdog
@@ -235,9 +270,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
@@ -332,6 +431,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
 }
 
 /**
@@ -415,8 +573,13 @@ const DEFAULT_TUNING: Required<BridgeTuning> = {
   turnStallMs: 600_000,
   turnStallToolMs: 1_800_000,
   turnStallTickMs: 30_000,
-  idleTimeoutMs: 1_800_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'
@@ -453,7 +616,7 @@ export class AgentBridge {
   private readonly staleCancelRetryDelayMs: number
   private readonly staleCancelMaxRetries: number
   private readonly turnSettleMs: number
-  private readonly defaultIdleTimeoutMs: number
+  private defaultIdleTimeoutMs: number
   private readonly probeIdleTimeoutMs: number
   /** Armed while READY; fires the idle-release check. */
   private idleTimer?: ReturnType<typeof setTimeout>
@@ -474,6 +637,13 @@ export class AgentBridge {
    * that a caller is waiting on the child it is about to kill.
    */
   private pendingCreates = 0
+  /**
+   * `session/fork` requests in flight (the adopt path of a branched
+   * conversation). Same teardown hazard as {@link pendingCreates}: until the
+   * forked session is registered, nothing else would stop an idle release
+   * from killing the child out from under the caller.
+   */
+  private pendingForks = 0
   /**
    * Whether a REAL session has ever been registered on this bridge. Probes
    * bypass session bookkeeping, so a bridge that has never hosted anything was
@@ -516,6 +686,20 @@ export class AgentBridge {
      * this bridge was built.
      */
     private readonly sessionWorkspace?: () => SessionWorkspaceResolver | undefined,
+    /**
+     * Told whenever the SESSION RECORDS change shape (a release parks them, a
+     * resume revives them): the manager persists `chatSessions` through it, so
+     * a parked conversation stays resumable across a host restart (see
+     * `BridgeManager.loadPersistedChatSessions`).
+     */
+    private readonly onSessionsDirty?: () => void,
+    /**
+     * Told whenever a fresh `initialize` reports the agent's
+     * `sessionCapabilities.fork` bit — the LAST KNOWN fork capability the
+     * manager persists and serves to the browser (the bridge's own
+     * `initResult` dies with the process; the manager's copy survives it).
+     */
+    private readonly onForkCapability?: (agentId: string, supported: boolean) => void,
   ) {
     const merged = { ...DEFAULT_TUNING, ...tuning }
     this.startupTimeoutMs = merged.startupTimeoutMs
@@ -550,6 +734,24 @@ export class AgentBridge {
     this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, this.permissionTimeoutMs)
   }
 
+  /**
+   * Adopt a rewritten host-default idle window (the settings page's write).
+   *
+   * Only the DEFAULT moves: an agent that names its own `idleTimeoutMs` keeps
+   * it (that promise is about the agent, not about the deployment), and a
+   * probe-only child keeps the short probe window.
+   *
+   * The timer is re-armed so the new window governs from NOW: an already
+   * armed timer still holds the old window, so a shortened window would not
+   * take effect until the old one elapsed.
+   */
+  applyIdleRelease(defaultIdleTimeoutMs: number): void {
+    if (this.defaultIdleTimeoutMs === defaultIdleTimeoutMs) return
+    this.defaultIdleTimeoutMs = defaultIdleTimeoutMs
+    this.clearIdleTimer()
+    this.touch()
+  }
+
   /**
    * The idle-release window this agent honors for its CHAT process: its own
    * field, else the host default. This is the number the panel prefills and
@@ -650,11 +852,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
@@ -672,13 +879,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).
@@ -688,11 +903,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
@@ -704,12 +924,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?.()
   }
 
@@ -744,6 +966,7 @@ export class AgentBridge {
   private hasActiveWork(): boolean {
     if (this.pendingProbes > 0
       || this.pendingCreates > 0
+      || this.pendingForks > 0
       || this.pendingCommands.size > 0
       || this.resuming.size > 0
       || this.permissions.sessionIds().length > 0
@@ -768,6 +991,7 @@ export class AgentBridge {
   hasOtherActiveWork(session: LiveSession): boolean {
     if (this.pendingProbes > 0
       || this.pendingCreates > 0
+      || this.pendingForks > 0
       || this.resuming.size > 0
       || this.starting !== undefined) return true
     for (const sessionId of this.pendingCommands.keys()) {
@@ -944,6 +1168,10 @@ export class AgentBridge {
       'initialize',
     )
     this.initResult = init
+    // The fork capability is agent knowledge that must outlive the process:
+    // report it so the manager can persist a LAST KNOWN copy and serve the
+    // browser's branch button after a release (`initResult` itself dies here).
+    this.onForkCapability?.(this.def.id, this.initResult?.agentCapabilities?.sessionCapabilities?.fork != null)
   }
 
   /**
@@ -1094,6 +1322,103 @@ export class AgentBridge {
     }
   }
 
+  /**
+   * Fork one live session through the agent's own `session/fork` (the
+   * UNSTABLE fourth session-creation point): the agent copies its internal
+   * state into a NEW ACP session that remembers the parent's context — the
+   * second half of a branched conversation, after the host's `sessions.fork`
+   * has already built the DSH session tree. The child is addressed by the
+   * CHILD DSH conversation id, so its first message reaches an agent that
+   * actually remembers the parent.
+   *
+   * The parent must be live on this connection — a released parent has no
+   * process to fork from (the browser blocks that click; this is the hard
+   * stop behind it). The ACP request carries the SAME `mcpServers` list as
+   * `session/new` / `session/load` (one list per process; an empty list would
+   * evict the live sessions' MCP scope) and is bounded by the startup timeout
+   * like every session-creation step. Counted in {@link pendingForks} while
+   * in flight so an idle release cannot kill the child out from under the
+   * caller.
+   */
+  async forkSession(parent: LiveSession, dshSessionId: string): Promise<LiveSession> {
+    if (this.initResult?.agentCapabilities?.sessionCapabilities?.fork == null) {
+      throw new AcpError('fork_unsupported', `acp: agent "${this.def.id}" does not advertise the session/fork capability`)
+    }
+    const conn = this.conn
+    if (conn === undefined) throw new AcpError('agent_unreachable', 'acp: connection is not open')
+    // The child runs where the parent runs: its cwd is the parent's already
+    // validated workspace, re-trusted as its own extra root (the same minimal
+    // trust `resolveSessionCwd` applied when the parent was created — never
+    // the agent's configured sandbox cwd, which is not where the conversation
+    // lives).
+    const resolved = resolveSessionCwd(this.def, parent.cwd, p => realpathSync(p), [parent.cwd])
+    this.pendingForks += 1
+    try {
+      const result = await this.withStartupTimeout(
+        conn.agent.request(methods.agent.session.fork, {
+          sessionId: parent.acpSessionId,
+          cwd: resolved,
+          mcpServers: toAcpMcpServers(this.def.mcpServers),
+        }),
+        'session/fork',
+      )
+      // A fork answer that names the parent (or any session already routed on
+      // this connection) would interleave the parent's updates, asks and
+      // permission cards into the child — refuse it rather than register it.
+      if (typeof result.sessionId !== 'string' || result.sessionId === '') {
+        throw new AcpError('fork_failed', 'acp: session/fork returned no session id')
+      }
+      if (result.sessionId === parent.acpSessionId || this.acpIndex.has(result.sessionId)) {
+        throw new AcpError('fork_id_conflict', 'acp: session/fork returned an id that already exists on this connection')
+      }
+      const session: LiveSession = {
+        sessionId: randomUUID(),
+        agentId: this.def.id,
+        acpSessionId: result.sessionId,
+        cwd: resolved,
+        running: false,
+        turnSeq: 0,
+        closed: false,
+        released: false,
+        lastAgentActivityAt: Date.now(),
+        activeToolCalls: new Set(),
+        transcript: new Transcript(this.transcriptMax),
+        dshSessionId,
+        ...(result.modes !== undefined && result.modes !== null
+          ? {
+            modes: {
+              currentModeId: result.modes.currentModeId,
+              availableModes: result.modes.availableModes.map(m => ({
+                id: m.id,
+                name: m.name,
+                ...(m.description !== null ? { description: m.description } : {}),
+              })),
+            },
+          }
+          : {}),
+        ...(usableConfigOptions(result.configOptions) ? { configOptions: result.configOptions } : {}),
+      }
+      // The fork answer's config options are the AGENT-LEVEL surface too (the
+      // same feed `session/new` provides): absorb them so the composer chips
+      // of the fresh conversation render without a probe.
+      if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
+        this.onCatalog(this.def.id, result.configOptions)
+      }
+      this.sessions.set(session.sessionId, session)
+      this.acpIndex.set(session.acpSessionId, session)
+      // Same flip as `createSession`: a registered session makes this a chat
+      // process; re-arm the idle clock on the agent's own window.
+      this.clearIdleTimer()
+      this.everHostedSession = true
+      this.hub.broadcast({ type: 'session/created', sessionId: session.sessionId, session: snapshot(session) })
+      this.touch()
+      return session
+    } finally {
+      this.pendingForks -= 1
+      this.touch()
+    }
+  }
+
   /**
    * Fire one prompt turn. Returns after the agent settles the turn; the caller
    * (manager) keeps the UI informed through broadcast events, so the RPC that
@@ -1106,25 +1431,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()
     }
   }
@@ -1175,16 +1542,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.
@@ -1241,17 +1622,23 @@ export class AgentBridge {
       if (conn === undefined) throw new AcpError('agent_unreachable', 'acp: connection is not open')
       const resolved = resolveSessionCwd(this.def, session.cwd, p => realpathSync(p), workspaceRoot === undefined ? [] : [workspaceRoot])
       // Replay arrives as brand-new updates, so the transcript restarts too;
-      // seq keeps meaning "position in the current epoch".
+      // seq keeps meaning "position in the current epoch". What the buffer held
+      // is now the agent's to replay — remember that there IS history before
+      // dropping it, or a failed resume parks an empty buffer back and the
+      // view claims the conversation never happened.
+      session.hasHistory = session.hasHistory === true || session.transcript.since(0).length > 0
       session.transcript = new Transcript(this.transcriptMax)
       session.cwd = resolved
       session.running = false
       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
@@ -1285,6 +1672,7 @@ export class AgentBridge {
       this.touch()
       // Republish so configOptions/modes observed on load reach the browser.
       this.hub.broadcast({ type: 'session/meta', sessionId: session.sessionId, session: snapshot(session) })
+      this.onSessionsDirty?.()
       return session
     } catch (error) {
       this.acpIndex.delete(session.acpSessionId)
@@ -1292,6 +1680,7 @@ export class AgentBridge {
       session.released = true
       this.released.set(session.sessionId, session)
       this.hub.broadcast({ type: 'session/released', sessionId: session.sessionId, session: snapshot(session), reason: 'resume failed', cause: 'resume-failed' })
+      this.onSessionsDirty?.()
       throw error
     }
   }
@@ -1312,8 +1701,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)
@@ -1327,6 +1718,10 @@ export class AgentBridge {
     this.state = 'stopped'
     this.initResult = undefined
     this.publishStatus()
+    // The parked records are what keeps them resumable after a host restart —
+    // persist now, while their transcripts (the `hasHistory` evidence) are
+    // still the ones they were parked with.
+    this.onSessionsDirty?.()
   }
 
   /** Detach one released session record for a resume attempt. */
@@ -1342,6 +1737,15 @@ export class AgentBridge {
     return this.released.delete(sessionId)
   }
 
+  /**
+   * Register a session record restored from disk as already parked: a host
+   * restart killed every process, so it comes back exactly as `releaseAll`
+   * would have left it — resumable via `session/load`, never live.
+   */
+  parkReleased(session: LiveSession): void {
+    this.released.set(session.sessionId, session)
+  }
+
   get releasedList(): LiveSession[] {
     return [...this.released.values()]
   }
@@ -1411,6 +1815,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()
@@ -1485,6 +1895,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 })
@@ -1767,6 +2178,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)
@@ -1824,6 +2289,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
@@ -1915,13 +2552,92 @@ 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 } : {}),
+    ...(session.hasHistory === true ? { hasHistory: true } : {}),
     seq: session.transcript.head,
   }
 }
 
+/**
+ * The `fork` half of one `session/chat-list` row: the host's verdict on
+ * forking this session's ACP agent. The capability half is the agent's LAST
+ * KNOWN bit (see `canForkNow`); the state half is the session's own, released
+ * checked before running (a parked record is never running). The browser
+ * renders its branch button from this verdict and never reads a capability
+ * bit itself.
+ */
+function forkRowInfo(session: LiveSession, capability: boolean): { fork: ChatSessionForkInfo } {
+  if (!capability) return { fork: { supported: false, reason: 'unsupported' } }
+  if (session.released) return { fork: { supported: false, reason: 'released' } }
+  if (session.running || session.settled !== undefined) return { fork: { supported: false, reason: 'busy' } }
+  return { fork: { supported: true } }
+}
+
+/**
+ * One chat-bound session record, as persisted across host restarts (the
+ * `chatSessions` key of the agent registry). Deliberately identity + display
+ * mirrors ONLY — the transcript is the agent's to replay on `session/load`,
+ * and `configOptions` come back from the same load. `hasHistory` is what lets
+ * an empty restored view say "history replays on restore" instead of
+ * "nothing yet".
+ */
+interface PersistedChatSession {
+  sessionId: string
+  acpSessionId: string
+  agentId: string
+  dshSessionId: string
+  cwd: string
+  title?: string
+  modelId?: string
+  reasoningEffort?: string
+  modes?: SessionView['modes']
+  usage?: SessionView['usage']
+  burst?: SessionView['burst']
+  hasHistory?: boolean
+}
+
+function persistedChatSession(session: LiveSession): PersistedChatSession {
+  return {
+    sessionId: session.sessionId,
+    acpSessionId: session.acpSessionId,
+    agentId: session.agentId,
+    dshSessionId: session.dshSessionId as string,
+    cwd: session.cwd,
+    ...(session.title === undefined ? {} : { title: session.title }),
+    ...(session.modelId === undefined ? {} : { modelId: session.modelId }),
+    ...(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 } : {}),
+  }
+}
+
+/** Tolerant shape check for a `modes` value read back from disk. */
+function isPersistedModes(value: unknown): value is SessionView['modes'] {
+  if (value === null || typeof value !== 'object') return false
+  const modes = value as { currentModeId?: unknown; availableModes?: unknown }
+  return typeof modes.currentModeId === 'string' && Array.isArray(modes.availableModes)
+}
+
+/** Tolerant shape check for a `usage` value read back from disk. */
+function isPersistedUsage(value: unknown): value is SessionView['usage'] {
+  if (value === null || typeof value !== 'object') return false
+  const usage = value as { used?: unknown; size?: unknown }
+  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
@@ -2687,12 +3403,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' }
@@ -2705,6 +3426,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.
  *
@@ -2718,13 +3586,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,
@@ -2737,6 +3703,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))
   }
 
@@ -2772,6 +3742,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
@@ -2787,34 +3763,793 @@ 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
-      this.cursorSeq = entry.seq
+    this.segment = seg
+    const entries = this.session.transcript.since(this.cursorSeq)
+    for (const entry of entries) {
+      if (seg.finished) 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) {
+      // Narrative that arrived between segments (a permission ask during card
+      // execution): it belongs to the turn's story, so it opens this segment.
+      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
+  }
+
+  /** Finish the segment on air (if any). Used by cancel paths and teardown. */
+  finishActive(reason: SegmentFinishReason): void {
+    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')
     }
-    if (!seg.finished && this.pendingProse.length > 0) {
-      // Narrative that arrived between segments (a permission ask during card
-      // execution): it belongs to the turn's story, so it opens this segment.
-      const lines = this.pendingProse.splice(0, this.pendingProse.length).join('')
-      this.emitProse(seg, 'reasoning', lines)
+    for (const entry of pending) {
+      if (seg.finished) break
+      this.foldInto(seg, entry.update, entry.seq)
     }
-    if (this.settled) this.finishAfterSettle(seg)
-    return seg
   }
 
-  /** Finish the segment on air (if any). Used by cancel paths and teardown. */
-  finishActive(reason: SegmentFinishReason): void {
-    if (this.segment !== undefined) this.finishSegment(this.segment, reason)
+  /** 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
@@ -2826,6 +4561,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') {
@@ -2835,19 +4602,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)
     }
@@ -2862,23 +4638,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)
@@ -2886,9 +4697,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()
   }
@@ -2949,20 +4780,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
@@ -2975,16 +4859,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.
    *
@@ -3021,15 +4964,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
@@ -3038,10 +5081,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) {
@@ -3053,6 +5120,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
@@ -3240,6 +5313,29 @@ export class BridgeManager {
    * write would fight with no way to tell which one is live.
    */
   private deadlineOverride: ApprovalDeadlinePatch = {}
+  /**
+   * The idle-release window the settings page picked, in ms, persisted
+   * with the agent registry. `undefined` means the deployment baseline runs.
+   *
+   * Merged OVER {@link baselineIdleTimeoutMs} exactly like
+   * {@link deadlineOverride} over {@link baselineDeadline}: a UI pick is what
+   * runs, and `cordis.patch.yml` becomes the value the reset button returns
+   * to. Without this split the two sources would fight with no way to tell
+   * which one is live.
+   */
+  private idleReleaseOverride?: number
+  /**
+   * The window `cordis.patch.yml` names, when it names one. Kept apart
+   * from the override for the same reason the deadline keeps its baseline
+   * apart: the settings card has to be able to say "the file asks for
+   * 10 minutes, the value set here wins".
+   */
+  private configuredIdleTimeoutMs?: number
+  /**
+   * The idle-release window before any override — the tuning this manager was
+   * constructed with (the deployment baseline, or the built-in 30 minutes).
+   */
+  private baselineIdleTimeoutMs: number
   /**
    * Tuning in force, defaults applied. The approval deadline is rewritten
    * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
@@ -3263,6 +5359,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)
@@ -3401,6 +5525,7 @@ export class BridgeManager {
     // it. Everything else in `tuning` is fixed for the manager's lifetime, so
     // only this needs a snapshot.
     this.baselineDeadline = this.tuning.permissionTimeoutMs
+    this.baselineIdleTimeoutMs = this.tuning.idleTimeoutMs
     this.baselineMode = this.tuning.permissionTimeoutMode
     for (const def of defs) {
       this.defsMap.set(def.id, def)
@@ -3417,6 +5542,10 @@ export class BridgeManager {
     // A persisted deadline override must reach the tuning the bridges are built
     // from, not just the settings card's readout.
     this.applyDeadlineTuning()
+    // The same for the idle-release window: a persisted override must
+    // reach the tuning the bridges are built from, not just the
+    // settings card's readout.
+    this.applyIdleReleaseTuning()
     // The request-path rewrite falls back to this default for a conversation
     // the user never bound explicitly — the same agent the composer chip shows.
     routeBindingRegistry().defaultModel = this.defaultAgent()
@@ -3427,8 +5556,10 @@ export class BridgeManager {
     onConnectionLost: (bridge: AgentBridge, reason: string) => void,
     onCatalog?: (agentId: string, configOptions: unknown, shapeOnly?: boolean) => void,
     onCommands?: (agentId: string, commands: NonNullable<SessionView['availableCommands']>) => void,
+    onSessionsDirty?: () => void,
+    onForkCapability?: (agentId: string, supported: boolean) => void,
   ): AgentBridge {
-    return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver)
+    return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver, onSessionsDirty, onForkCapability)
   }
 
   /**
@@ -3454,6 +5585,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
@@ -3567,12 +5705,88 @@ export class BridgeManager {
         ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }),
         ...(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)),
       })
     }
     return out
   }
 
+  /**
+   * Adopt the ACP side of a branched conversation: the browser has already
+   * asked the HOST to fork the DSH session tree (`sessions.fork`), and this
+   * runs the agent's own `session/fork` of the parent conversation's live ACP
+   * session so the child actually remembers the parent context — then binds
+   * the child to it (the fourth session-creation point, with every discipline
+   * the other three carry).
+   *
+   * Failure is deliberately all-or-nothing: nothing is written for the child
+   * until the agent has answered, so a failed adopt leaves the child an
+   * ordinary copied-history conversation whose first message starts a fresh
+   * `session/new` (today's behavior) — never a half-bound record.
+   *
+   * @param childDshSessionId - the DSH session the host fork created.
+   * @param parentDshSessionId - the conversation being branched; its ACP
+   *   session must be LIVE on this connection (a released parent has no
+   *   process to fork from — the browser blocks the click, this is the hard
+   *   stop behind it).
+   */
+  async adoptForkedSession(childDshSessionId: string, parentDshSessionId: string): Promise<{ sessionId: string; acpSessionId: string }> {
+    // One conversation, one agent (the lock). The parent's LIVE session is
+    // the fork source; released or in-flight-settling parents are refused —
+    // forking a parked record would silently resume it, and forking mid-turn
+    // would fork an agent state the parent turn is still changing.
+    const parent = [...this.dshSessionMap.values()].find(session =>
+      session.dshSessionId === parentDshSessionId && !session.closed && !session.released)
+    if (parent === undefined) {
+      throw new AcpError('parent_not_live', 'acp: the conversation to branch has no live ACP session; send a message to resume it first')
+    }
+    if (parent.running || parent.settled !== undefined) {
+      throw new AcpError('turn_in_flight', 'acp: the conversation to branch is running a turn; wait for it to finish')
+    }
+    const agentId = parent.agentId
+    const childKey = `${childDshSessionId}:${agentId}`
+    if (this.dshSessionMap.has(childKey)) {
+      throw new AcpError('id_conflict', 'acp: the forked conversation is already bound to an ACP session')
+    }
+    // Capability gate BEFORE any request: an agent that never advertised
+    // `session/fork` must not be asked (it would answer an unknown-method
+    // error at best). Live init wins, last-known falls back — the same
+    // verdict the browser's row already showed.
+    if (!this.canForkNow(agentId)) {
+      throw new AcpError('fork_unsupported', `acp: agent "${agentId}" does not advertise the session/fork capability`)
+    }
+    const session = await this.bridge(agentId).forkSession(parent, childDshSessionId)
+    // The fork answered — the child is real on the agent side. From here the
+    // binding is written through the SAME paths as any chat session: one
+    // choice record (a copy of the parent's, locked — a branched conversation
+    // belongs to its agent from birth), the route pin, and persistence.
+    this.dshSessionMap.set(childKey, session)
+    const parentChoice = this.chatAgentIntent.get(parentDshSessionId)
+    this.patchChatChoice(childDshSessionId, {
+      agentId,
+      locked: true,
+      ...(parentChoice?.modelId === undefined ? {} : { modelId: parentChoice.modelId }),
+      ...(parentChoice?.effort === undefined ? {} : { effort: parentChoice.effort }),
+      ...(parentChoice?.mode === undefined ? {} : { mode: parentChoice.mode }),
+      ...(parentChoice?.extraConfigs === undefined ? {} : { extraConfigs: { ...parentChoice.extraConfigs } }),
+    })
+    // The fourth creation point follows the same discipline as `createSession`
+    // and `doResumeSession`: apply the recorded pick to the fresh session, so
+    // mode and extra configs (which only this path applies) cannot drift from
+    // what the composer shows — a forked session starts on the agent-side
+    // state the fork copied, and the record must match what runs.
+    await this.applyChatChoice(session)
+    // Re-publish so the browser's list and the composer's occupancy ring see
+    // the child immediately (with its just-bound choice mirrors).
+    this.hub.broadcast({ type: 'session/meta', sessionId: session.sessionId, session: snapshot(session) })
+    this.persistAgents()
+    return { sessionId: session.sessionId, acpSessionId: session.acpSessionId }
+  }
+
   /**
    * Bind one DSH chat session to an ACP agent.
    *
@@ -3827,11 +6041,12 @@ export class BridgeManager {
     this.patchChatChoice(dshSessionId, { agentId, modelId: choice === undefined ? undefined : modelId })
     for (const session of this.dshSessionMap.values()) {
       if (session.dshSessionId !== dshSessionId || session.agentId !== agentId) continue
-      if (session.released) continue
-      await this.alignSessionConfig(session, choice, session.reasoningEffort)
       session.choice = choice
       session.modelId = modelId
+      if (session.released) continue
+      await this.alignSessionConfig(session, choice, session.reasoningEffort)
     }
+    this.persistAgents()
   }
 
   /**
@@ -3857,12 +6072,15 @@ export class BridgeManager {
     // session is skipped here and re-aligned by `applyChatChoice` on resume.
     this.patchChatChoice(dshSessionId, { ...(agentId === undefined ? {} : { agentId }), effort })
     for (const session of this.dshSessionMap.values()) {
-      if (session.dshSessionId !== dshSessionId || session.released) continue
+      if (session.dshSessionId !== dshSessionId) continue
       if (agentId !== undefined && session.agentId !== agentId) continue
+      session.reasoningEffort = effort
+      if (session.released) continue
       const aligned = await this.alignSessionConfig(session, session.choice, effort)
       // Same rule as the model axis: a dropped level is no longer "in force".
       session.reasoningEffort = aligned.effortStale ? undefined : effort
     }
+    this.persistAgents()
   }
 
   /**
@@ -4051,9 +6269,15 @@ export class BridgeManager {
   }
 
   /**
-   * Switch one chat-bound session's ACP mode. A released session is resumed
-   * first (`session/load`), matching the "send to recover" promise — the mode
-   * switch is itself a reason to bring the agent back.
+   * Switch one chat-bound session's ACP mode.
+   *
+   * A released session is deliberately NOT resumed for it (user decision,
+   * 2026-10-30 — the composer's axes are "what the next turn should use", and
+   * the process comes back only when the user sends a message or hits the
+   * released banner's resume button). The pick is recorded and
+   * `applyChatChoice` applies it on resume, exactly like `setChatSessionModel`
+   * / `setChatSessionEffort` / `setChatSessionConfig`; only a LIVE session is
+   * told immediately (`session/set_mode`).
    */
   async setChatSessionMode(dshSessionId: string, modeId: string, agentId?: string): Promise<void> {
     if (agentId !== undefined) {
@@ -4083,9 +6307,20 @@ export class BridgeManager {
     if (target.closed) {
       throw new AcpError('unknown_session', `acp: the ACP session bound to chat session ${dshSessionId} is closed`)
     }
+    // A PARKED session gets the same record-only treatment (its agent is its
+    // own `agentId`, whatever the caller passed — the selection above already
+    // matched it). Resuming here was the one composer axis that broke ranks
+    // with the others, and it woke a process the user had explicitly parked.
+    if (target.released) {
+      this.patchChatChoice(dshSessionId, { agentId: target.agentId, mode: modeId })
+      if (target.modes !== undefined) {
+        target.modes = { ...target.modes, currentModeId: modeId }
+      }
+      this.persistAgents()
+      return
+    }
     const bridge = this.bridge(target.agentId)
-    const session = target.released ? await bridge.resumeSession(target) : target
-    await bridge.setMode(session, modeId)
+    await bridge.setMode(target, modeId)
     // Persisted only AFTER the agent accepted it: a mode the agent rejected must
     // not come back on the next restore. This is the same contract the model and
     // thought level follow (user decision, 2026-10-18 — every control in the
@@ -4093,6 +6328,42 @@ export class BridgeManager {
     this.patchChatChoice(dshSessionId, { agentId: target.agentId, mode: modeId })
   }
 
+  /**
+   * Bring one chat conversation's released session back on a fresh process on
+   * the USER's explicit gesture (the "恢复进程" banner) — the same work the
+   * next prompt performs lazily (`getOrCreateDshSession`'s released branch),
+   * minus the create path: a banner button must never materialize a session
+   * the conversation has not had yet. A live target passes through untouched,
+   * so a double click (or a click racing the next message) spawns nothing.
+   */
+  async resumeChatSession(dshSessionId: string): Promise<void> {
+    const candidates = [...this.dshSessionMap.values()].filter(
+      session => session.dshSessionId === dshSessionId && !session.closed,
+    )
+    // The session the NEXT message would use — the bound agent's — is the one
+    // to bring back; the first candidate is the fallback for a conversation
+    // whose binding has drifted (same selection `setChatSessionMode` makes
+    // without an explicit agentId).
+    const target = candidates.find(session => session.agentId === this.chatAgentFor(dshSessionId)) ?? candidates[0]
+    if (target === undefined) {
+      throw new AcpError('unknown_session', `acp: no ACP session is bound to chat session ${dshSessionId}`)
+    }
+    if (!target.released) return
+    const bridge = this.bridge(target.agentId)
+    const resumed = await bridge.resumeSession(target)
+    // Chat-side rebind + pick re-application, verbatim the lazy path's: the
+    // freshly loaded session comes back at the agent's defaults, so the
+    // conversation's model / thought level must be re-applied or the composer
+    // would show one thing and the process run another (see
+    // `getOrCreateDshSession`).
+    resumed.dshSessionId = dshSessionId
+    this.lockChatAgent(dshSessionId, target.agentId)
+    if (this.chatAgentIntent.has(dshSessionId)) this.syncConversationRoute(dshSessionId)
+    else routeBindingRegistry().conversations.set(dshSessionId, resumed.modelId ?? target.agentId)
+    await this.applyChatChoice(resumed)
+    resumed.provisionalLock = false
+  }
+
   /**
    * Wire the harness's preset roster (`ctx.agentPresets`) into `presetStatus`.
    *
@@ -4276,7 +6547,21 @@ export class BridgeManager {
         } catch {
           this.deadlineOverride = {}
         }
+        // The settings page's idle-release pick. Re-validated on every boot
+        // because the state file is user- and version-editable: an
+        // unreadable value must not poison the window, and a value the
+        // validator accepts must be the value that runs.
+        try {
+          const raw = (parsed as { idleRelease?: unknown }).idleRelease
+          const value = (raw as { idleTimeoutMs?: unknown } | undefined)?.idleTimeoutMs
+          this.idleReleaseOverride = typeof value === 'number' && IDLE_RELEASE_MS.includes(value)
+            ? value
+            : undefined
+        } catch {
+          this.idleReleaseOverride = undefined
+        }
         this.loadPersistedChoices((parsed as { conversations?: unknown }).conversations)
+        this.loadPersistedChatSessions((parsed as { chatSessions?: unknown }).chatSessions)
       }
     } catch {
       // Storage load failure is non-fatal
@@ -4319,10 +6604,32 @@ 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
     try {
+      // The chat-bound session records themselves: a host restart kills the
+      // processes but not the agent-side sessions, so restoring these as
+      // PARKED keeps a conversation resumable (`session/load`) instead of
+      // its next message silently starting a context-less new one.
+      const chatSessions = [...this.dshSessionMap.values()]
+        .filter(session => session.dshSessionId !== undefined && !session.closed)
+        .map(persistedChatSession)
       const payload = {
         version: 2,
         ...(this.defaultAgentId === undefined ? {} : { defaultAgentId: this.defaultAgentId }),
@@ -4333,12 +6640,18 @@ export class BridgeManager {
         ...(Object.keys(this.deadlineOverride).length === 0
           ? {}
           : { approvalDeadlines: { ...this.deadlineOverride } }),
+        // The settings page's idle-release pick. Absent while none was
+        // ever written, so a fresh deployment's state file stays as it was.
+        ...(this.idleReleaseOverride === undefined
+          ? {}
+          : { idleRelease: { idleTimeoutMs: this.idleReleaseOverride } }),
         // The per-conversation picks: agent + model + thought level + mode +
         // extra config values chosen in the composer, including for
         // conversations with no live session yet.
         ...(this.chatAgentIntent.size === 0
           ? {}
           : { conversations: Object.fromEntries(this.chatAgentIntent) }),
+        ...(chatSessions.length === 0 ? {} : { chatSessions }),
       }
       writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf-8')
     } catch {
@@ -4346,9 +6659,74 @@ export class BridgeManager {
     }
   }
 
+  /**
+   * Restore chat session records from disk as PARKED sessions.
+   *
+   * Every process died with the host, so nothing comes back live — but the
+   * agent-side sessions did not. Restoring each record as `released` is what
+   * makes the released banner, its resume button and the "next message
+   * resumes it" promise survive a restart (the alternative is the next
+   * message quietly starting a NEW, context-less session — constraint 10's
+   * "released ≠ destroyed" lost at the process boundary). Tolerant, one row
+   * at a time: a single corrupt entry must not cost every other conversation
+   * its context. Records whose agent is no longer configured are dropped —
+   * there is nothing to resume ON, and the next write omits them.
+   */
+  private loadPersistedChatSessions(raw: unknown): void {
+    if (!Array.isArray(raw)) return
+    for (const row of raw) {
+      if (row === null || typeof row !== 'object') continue
+      const record = row as Record<string, unknown>
+      const { sessionId, acpSessionId, agentId, dshSessionId, cwd } = record
+      if (typeof sessionId !== 'string' || sessionId === '') continue
+      if (typeof acpSessionId !== 'string' || acpSessionId === '') continue
+      if (typeof agentId !== 'string' || agentId === '') continue
+      if (typeof dshSessionId !== 'string' || dshSessionId === '') continue
+      if (typeof cwd !== 'string') continue
+      if (!this.defsMap.has(agentId)) continue
+      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,
+        acpSessionId,
+        agentId,
+        dshSessionId,
+        cwd,
+        ...(typeof title === 'string' && title !== '' ? { title } : {}),
+        ...(typeof modelId === 'string' && modelId !== ''
+          ? { modelId, ...(splitAdapterModelId(modelId).choice === undefined ? {} : { choice: splitAdapterModelId(modelId).choice }) }
+          : {}),
+        ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
+        ...(isPersistedModes(modes) ? { modes } : {}),
+        ...(isPersistedUsage(usage) ? { usage } : {}),
+        ...(isPersistedBurst(burst) ? { burst } : {}),
+        ...(hasHistory === true ? { hasHistory: true } : {}),
+        running: false,
+        turnSeq: 0,
+        closed: false,
+        released: true,
+        lastAgentActivityAt: Date.now(),
+        activeToolCalls: new Set<string>(),
+        transcript: new Transcript(this.transcriptMax),
+      }
+      this.dshSessionMap.set(`${dshSessionId}:${agentId}`, session)
+      this.bridge(agentId).parkReleased(session)
+    }
+  }
+
   // ---- Model catalog ----
 
   private readonly catalogs = new Map<string, { catalog: AcpAgentCatalog; updatedAt: number }>()
+  /**
+   * Each agent's LAST KNOWN `sessionCapabilities.fork` bit, persisted with the
+   * model catalog. A live `initialize` result outranks it whenever one exists
+   * (see {@link canForkNow}) — this copy answers when the process is gone
+   * (a released session's branch button must not flash into "supported" just
+   * because `initResult` died with it, nor read `view().agentCapabilities`,
+   * which a release clears).
+   */
+  private readonly forkCaps = new Map<string, boolean>()
   /**
    * The slash commands each agent declared in its most recent session, cached
    * per agent and persisted alongside the model catalog.
@@ -4415,7 +6793,10 @@ export class BridgeManager {
       const stale = parsed.version !== BridgeManager.CATALOG_SCHEMA
       for (const [agentId, raw] of Object.entries(agents)) {
         if (typeof raw !== 'object' || raw === null) continue
-        const row = raw as { catalog?: unknown; updatedAt?: unknown; commands?: unknown; commandsUpdatedAt?: unknown }
+        const row = raw as { catalog?: unknown; updatedAt?: unknown; commands?: unknown; commandsUpdatedAt?: unknown; fork?: unknown }
+        // The persisted fork capability: a LAST KNOWN bit, loaded before any
+        // bridge can report a fresh one (a fresh `initialize` overwrites it).
+        if (typeof row.fork === 'boolean') this.forkCaps.set(agentId, row.fork)
         // Commands and the model catalog are learned independently (a session
         // may declare one before the other), so either half alone is a valid row.
         if (Array.isArray(row.commands)) {
@@ -4445,11 +6826,18 @@ export class BridgeManager {
         updatedAt?: number
         commands?: NonNullable<SessionView['availableCommands']>
         commandsUpdatedAt?: number
+        fork?: boolean
       }> = {}
       for (const [agentId, entry] of this.catalogs) agents[agentId] = { catalog: entry.catalog, updatedAt: entry.updatedAt }
       for (const [agentId, entry] of this.commandCache) {
         agents[agentId] = { ...(agents[agentId] ?? {}), commands: entry.commands, commandsUpdatedAt: entry.updatedAt }
       }
+      // The LAST KNOWN fork capability rides the same file: it outlives the
+      // agent process, which is exactly when the browser needs it (see
+      // `canForkNow`).
+      for (const [agentId, supported] of this.forkCaps) {
+        agents[agentId] = { ...(agents[agentId] ?? {}), fork: supported }
+      }
       writeFileSync(filePath, JSON.stringify({ version: BridgeManager.CATALOG_SCHEMA, agents }, null, 2), 'utf-8')
     } catch {
       // Storage persist failure is non-fatal
@@ -4541,6 +6929,33 @@ export class BridgeManager {
     this.hub.broadcast({ type: 'catalog/updated', agentId, updatedAt: entry.updatedAt })
   }
 
+  /**
+   * Record a fresh `initialize`'s `sessionCapabilities.fork` verdict (the
+   * bridge reports it right after the handshake). Persisted with the model
+   * catalog; no broadcast — the browser learns it through `session/chat-list`
+   * rows, and its branch button deliberately runs on a last-known basis (the
+   * agent's own next `initialize` is the refresh).
+   */
+  private noteForkCapability(agentId: string, supported: boolean): void {
+    if (this.forkCaps.get(agentId) === supported) return
+    this.forkCaps.set(agentId, supported)
+    this.persistCatalogs()
+  }
+
+  /**
+   * Whether an agent's fork can be attempted RIGHT NOW: a live `initialize`
+   * answer wins (the process is up, its handshake is current); only when the
+   * process is gone does the LAST KNOWN persisted bit answer. `false` covers
+   * "never seen" — an unknown agent simply never gets a fork attempt.
+   */
+  private canForkNow(agentId: string): boolean {
+    const bridge = this.bridges.get(agentId)
+    if (bridge?.initResult !== undefined) {
+      return bridge.initResult.agentCapabilities?.sessionCapabilities?.fork != null
+    }
+    return this.forkCaps.get(agentId) === true
+  }
+
   /**
    * Append models this observation newly introduced to the agent's selection.
    *
@@ -4966,6 +7381,10 @@ export class BridgeManager {
         else this.absorbCatalog(observedAgentId, configOptions)
       }, (observedAgentId, commands) => {
         this.absorbCommands(observedAgentId, commands)
+      }, () => {
+        this.persistAgents()
+      }, (observedAgentId, supported) => {
+        this.noteForkCapability(observedAgentId, supported)
       })
       this.bridges.set(agentId, bridge)
     }
@@ -5125,11 +7544,15 @@ export class BridgeManager {
       if (splitAdapterModelId(model).agentId === agentId) routeBindingRegistry().conversations.delete(dshSessionId)
     }
     if (routeBindingRegistry().defaultModel === agentId) routeBindingRegistry().defaultModel = undefined
-    // Both maps are independent (either may be missing), so delete both before
-    // deciding whether the file needs rewriting.
+    // All three maps are independent (any may be missing), so delete all
+    // before deciding whether the file needs rewriting. The fork capability
+    // goes with the agent: a same-id rebuild must not inherit the OLD agent's
+    // "supported" and click into a `fork_unsupported` wall before its own
+    // first `initialize` answers.
     const droppedCatalog = this.catalogs.delete(agentId)
     const droppedCommands = this.commandCache.delete(agentId)
-    if (droppedCatalog || droppedCommands) this.persistCatalogs()
+    const droppedFork = this.forkCaps.delete(agentId)
+    if (droppedCatalog || droppedCommands || droppedFork) this.persistCatalogs()
     this.persistAgents()
     this.hub.broadcast({
       type: 'agent/status',
@@ -5176,7 +7599,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
@@ -5194,7 +7617,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
@@ -5205,9 +7661,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) {
@@ -5217,8 +7676,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) {
@@ -5235,6 +7697,7 @@ export class BridgeManager {
           return
         }
         this.clearOrphanPrompt(session, turnGen)
+        endTurn()
         session.running = false
         this.hub.broadcast({
           type: 'turn/end',
@@ -5243,6 +7706,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 }
   }
 
@@ -5378,6 +7844,23 @@ export class BridgeManager {
     this.persistAgents()
   }
 
+  /**
+   * Declare the deployment baseline for the idle-release window — the value
+   * `cordis.patch.yml` names, passed RAW (only when it names one).
+   *
+   * Kept separate from the validated tuning for the same reason the
+   * deadline keeps its baseline apart: "the file says 10 minutes" and
+   * "the file says nothing, so 30 minutes applies" are different facts.
+   * The first is the reset target and shows as the fact being overridden;
+   * the second is a built-in default. Called once by the host entry,
+   * before any bridge exists.
+   */
+  setConfiguredIdleRelease(idleTimeoutMs: number | undefined): void {
+    this.configuredIdleTimeoutMs = idleTimeoutMs
+    if (idleTimeoutMs !== undefined) this.baselineIdleTimeoutMs = idleTimeoutMs
+    this.applyIdleReleaseTuning()
+  }
+
   /**
    * Declare the deployment baseline for the approval deadline — the values
    * `cordis.patch.yml` names, passed RAW (only the keys it actually contains).
@@ -5424,6 +7907,58 @@ export class BridgeManager {
     return deadlines
   }
 
+  /**
+   * The idle-release window in force, plus the facts that explain a value the
+   * user did not pick: the deployment baseline an override is outranking.
+   *
+   * `defaultIdleTimeoutMs` is the window a RESET returns to — the deployment
+   * baseline when the config file names one, else the built-in default. It is
+   * NOT a hardcoded constant: a deployment that names 10 minutes must reset
+   * to 10 minutes, not to the built-in 30.
+   *
+   * The config file's own number is reported only when the file names one, so
+   * the settings card can stay silent about a plain default.
+   */
+  idleRelease(): AcpIdleRelease {
+    const release: AcpIdleRelease = {
+      idleTimeoutMs: this.idleTimeoutMs(),
+      defaultIdleTimeoutMs: this.baselineIdleTimeoutMs,
+    }
+    if (this.configuredIdleTimeoutMs !== undefined) release.configuredIdleTimeoutMs = this.configuredIdleTimeoutMs
+    return release
+  }
+
+  /**
+   * Write the idle-release window, or drop the persisted override with
+   * `reset` so the deployment baseline applies again.
+   *
+   * HOT: the rewrite reaches every live bridge, so a user changing the window
+   * never has to kill a running session to see it take effect.
+   */
+  async setIdleRelease(idleTimeoutMs: number | undefined, reset = false): Promise<void> {
+    this.idleReleaseOverride = reset ? undefined : idleTimeoutMs
+    this.applyIdleReleaseTuning()
+    this.persistAgents()
+  }
+
+  /**
+   * Recompute the idle-release window from override → deployment baseline, and
+   * push the result to every live bridge.
+   */
+  private applyIdleReleaseTuning(): void {
+    const window = this.idleTimeoutMs()
+    this.tuning.idleTimeoutMs = window
+    for (const bridge of this.bridges.values()) bridge.applyIdleRelease(window)
+  }
+
+  /**
+   * The idle-release window that runs, in ms: the settings page's pick, else
+   * the deployment baseline.
+   */
+  private idleTimeoutMs(): number {
+    return this.idleReleaseOverride ?? this.baselineIdleTimeoutMs
+  }
+
   /**
    * Write the approval deadline, or the mode (omitted keys keep their value),
    * or drop the persisted override with `reset` so the config-file baseline —
@@ -5486,12 +8021,20 @@ export class BridgeManager {
 
   /** Drop every chat-keyed record pointing at one host session (close/stop paths). */
   private forgetDshSession(sessionId: string): void {
+    let dropped = false
     for (const [key, session] of this.dshSessionMap) {
-      if (session.sessionId === sessionId) this.dshSessionMap.delete(key)
+      if (session.sessionId === sessionId) {
+        this.dshSessionMap.delete(key)
+        dropped = true
+      }
     }
+    // The disk record goes with it: a closed session is destroyed, not parked,
+    // and must not come back on the next boot (constraint 10).
+    if (dropped) this.persistAgents()
   }
   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. */
@@ -5638,6 +8181,9 @@ export class BridgeManager {
       // A RESUMED session had context before this call; a lock written here is
       // not provisional even if the conversation record was missing it.
       resumed.provisionalLock = false
+      // The load refreshed the record's mirrors (modes / usage / hasHistory);
+      // persist so a later restart restores what this resume saw.
+      this.persistAgents()
       return resumed
     }
     // A chat session runs where its DSH session lives, not in the plugin's
@@ -5687,6 +8233,9 @@ export class BridgeManager {
       // conversation back (a failed first attempt must not trap it).
       session.provisionalLock = this.lockChatAgent(dshSessionId, agentId)
     }
+    // The record is on disk from here: a host restart restores it as parked
+    // instead of the next message starting a context-less new session.
+    this.persistAgents()
     return session
   }
 
@@ -5851,8 +8400,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' } }
@@ -5919,14 +8496,31 @@ export class BridgeManager {
       return
     }
 
+    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: `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`).
     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.
-      if (session.provisionalLock === true) this.rollbackFirstTurn(session)
+      // 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: {
@@ -6064,8 +8658,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.
@@ -6073,9 +8671,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) {