dsh-ntr 0.3.2 → 0.3.4

package/lib/bridge.js

@@ -12,8 +12,9 @@ import { delimiter, dirname, join } from 'node:path';
 import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
-import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
+import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, hasUnambiguousModelSelector, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, isAbsolutePath, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
 import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from "./protocol.js";
+import { OUTPUT_CHARS_PER_TOKEN, TurnTpsTracker } from "./tps.js";
 /**
  * Version of this installed package, read from the shipped `package.json` —
  * one level above both `src/` at test time and `lib/` at runtime. The settings
@@ -106,6 +107,11 @@ const DEFAULT_TUNING = {
     turnStallTickMs: 30_000,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
     probeIdleTimeoutMs: 300_000,
+    ambientQuietMs: 10_000,
+    ambientMaxMs: 120_000,
+    backgroundTaskMaxMs: 600_000,
+    backgroundParkedGraceMs: 30_000,
+    ambientStaleMs: 300_000,
 };
 export class AgentBridge {
     def;
@@ -384,11 +390,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) {
-        if (session.running)
+        if (this.promptSlotHeld(session))
             return { ok: false, reason: 'busy' };
         const pending = session.settled;
         if (pending === undefined)
@@ -411,13 +422,20 @@ export class AgentBridge {
         // 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)
+        // 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`). */
+    promptSlotHeld(session) {
+        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).
@@ -427,11 +445,16 @@ export class AgentBridge {
         const settled = new Promise(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
@@ -442,12 +465,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.
      */
     openSettleGate(session) {
         const settle = session.settledResolve;
         session.settled = undefined;
         session.settledResolve = undefined;
+        session.promptInFlight = false;
         settle?.();
     }
     view() {
@@ -939,28 +964,69 @@ 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, text, turnId) {
+    async runPrompt(session, prompt, turnId, turnGen) {
         const conn = this.conn;
         if (conn === undefined || session.closed || session.released)
             throw new AcpError('session_closed', 'acp: session is closed');
         this.touch();
+        const blocks = 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();
             }
+            // 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 result.stopReason;
+                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();
         }
     }
@@ -1006,10 +1072,19 @@ 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.
@@ -1017,6 +1092,11 @@ export class AgentBridge {
     finalizeTurn(session, turnGen, message) {
         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.
@@ -1085,10 +1165,12 @@ export class AgentBridge {
             session.closed = false;
             session.released = false;
             // A resume is a fresh agent-side state: nothing from the dead process's
-            // turn survives it, including the settle gate and the stall markers.
+            // turn survives it, including the settle gate and the stall markers. A
+            // background drain belonged to that process too.
             session.orphanPromptTurnSeq = undefined;
             session.reclaimedTurnSeq = undefined;
             session.activeToolCalls.clear();
+            clearAmbientState(session);
             session.lastAgentActivityAt = Date.now();
             this.openSettleGate(session);
             // Route replay updates into the fresh transcript while the load request
@@ -1150,8 +1232,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);
@@ -1259,6 +1343,12 @@ export class AgentBridge {
         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();
@@ -1331,6 +1421,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 });
@@ -1602,6 +1693,61 @@ 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();
+            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.content) !== '') {
+                session.ambient.sawOutput = true;
+            }
+        }
         if (kind === 'tool_call' || kind === 'tool_call_update') {
             const { toolCallId, status } = params.update;
             if (status === 'completed' || status === 'failed')
@@ -1662,6 +1808,129 @@ export class AgentBridge {
         }
     }
 }
+/** Read the CodeBuddy `_meta` keys off an update or a `{ _meta }` wrapper. */
+function codebuddyMetaOf(source) {
+    if (typeof source !== 'object' || source === null)
+        return undefined;
+    const row = source;
+    const rawMeta = row._meta;
+    if (typeof rawMeta !== 'object' || rawMeta === null)
+        return undefined;
+    const meta = rawMeta;
+    const out = {};
+    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;
+        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;
+        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, requestId) {
+    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, requestId) {
+    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, withinMs) {
+    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, requestId) {
+    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) {
+    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) {
+    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
@@ -1753,6 +2022,7 @@ function snapshot(session) {
         ...(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 } : {}),
@@ -1789,6 +2059,7 @@ function persistedChatSession(session) {
         ...(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 } : {}),
     };
 }
@@ -1806,6 +2077,14 @@ function isPersistedUsage(value) {
     const usage = value;
     return typeof usage.used === 'number' && typeof usage.size === 'number';
 }
+/** Tolerant shape check for a `burst` aggregate read back from disk. */
+function isPersistedBurst(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const burst = value;
+    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
@@ -2484,8 +2763,40 @@ export function releaseAllToolOutputWaiters() {
         for (const waiter of [...set])
             waiter(undefined);
 }
-/** 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 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;
 /**
  * The state of ONE ACP prompt, shared across every driver step of the turn.
  *
@@ -2505,13 +2816,111 @@ class TurnStreamController {
     rollbackFirstTurn;
     segment;
     settled = false;
+    /** Whether the turn's closing work already ran (see `closeTurn`). */
+    closedTurn = false;
     disposed = false;
     seenCalls = new Set();
     announcedKinds = new Map();
     /** Narrative lines (permission asks) that arrived while no segment was open. */
     pendingProse = [];
     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.
+     */
+    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.
+     */
+    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).
+     */
+    turnRequestId;
+    /**
+     * 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).
+     */
+    pendingAmbientUpdates = [];
+    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).
+     */
+    pendingAmbientTruncated = false;
+    /** The ambient wait in progress, if the agent folded this prompt into a drain. */
+    awaitingAmbient;
+    /**
+     * 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.
+     */
+    recentRetiredDrain = false;
+    /** The outcome of a settle whose closing work is waiting one macrotask (see `settle`). */
+    pendingOutcome;
+    closeScheduled = false;
     cursorSeq;
+    /**
+     * 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.
+     */
+    tps = new TurnTpsTracker();
+    tpsSeq;
+    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).
+     */
+    ambientTuning;
+    /**
+     * 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.
+     */
+    dispatches = new Map();
+    /** The detached-worker hold in progress, once a segment carries it. */
+    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.
+     */
+    pendingBackgroundHold;
+    /**
+     * 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}).
+     */
+    backgroundTuning;
+    /**
+     * 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.
+     */
+    constructedAt;
     constructor(manager, hub, session, turnId, 
     /** Releases the agent-side turn slot (the `beginTurn` settler; idempotent). */
     endTurn, rollbackFirstTurn) {
@@ -2523,6 +2932,10 @@ class TurnStreamController {
         this.rollbackFirstTurn = rollbackFirstTurn;
         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));
     }
     unsubscribe;
@@ -2552,6 +2965,12 @@ class TurnStreamController {
      * consuming it, so the next segment replays it again.
      */
     startSegment() {
+        // 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
@@ -2567,6 +2986,15 @@ 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;
@@ -2574,7 +3002,16 @@ class TurnStreamController {
         for (const entry of entries) {
             if (seg.finished)
                 break;
-            if (!this.foldInto(seg, entry.update))
+            const update = entry.update;
+            // 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;
         }
@@ -2584,6 +3021,12 @@ class TurnStreamController {
             const lines = this.pendingProse.splice(0, this.pendingProse.length).join('');
             this.emitProse(seg, 'reasoning', lines);
         }
+        const parkedHold = this.pendingBackgroundHold;
+        if (parkedHold !== undefined && !seg.finished) {
+            // The host opened the continuation step for the Agent card: the hold
+            // finally has a driver step to speak the drain's answer into.
+            this.adoptBackgroundHold(seg, parkedHold);
+        }
         if (this.settled)
             this.finishAfterSettle(seg);
         return seg;
@@ -2593,11 +3036,770 @@ class TurnStreamController {
         if (this.segment !== undefined)
             this.finishSegment(this.segment, reason);
     }
+    /** Whether this turn already streamed prose of its own (not a drain's). */
+    get hasAgentProse() {
+        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, stopReason) {
+        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 = {
+            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() {
+        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() {
+        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. */
+    activeBackgroundHold() {
+        return this.backgroundHold ?? this.pendingBackgroundHold;
+    }
+    /** Whether every KNOWN dispatch has reported (no dispatch at all counts as done). */
+    allDispatchesCompleted() {
+        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, requestId) {
+        if (this.settled || this.disposed || this.closedTurn || this.stale)
+            return;
+        if (this.activeBackgroundHold() !== undefined)
+            return;
+        const hold = {
+            stopReason,
+            requestId,
+            acceptedIds: new Set(),
+            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. */
+    adoptBackgroundHold(seg, hold) {
+        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.
+     */
+    startBackgroundDrain(hold, requestId) {
+        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.
+     */
+    enterBackgroundWorkerPhase(hold) {
+        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. */
+    armBackgroundQuiet(hold) {
+        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.
+     */
+    noteBackgroundHoldActivity() {
+        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. */
+    onBackgroundQuiet(hold) {
+        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. */
+    onBackgroundHard(hold) {
+        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.
+     */
+    onBackgroundGraceExpired(hold) {
+        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.
+     */
+    closeBackgroundHold(hold, options) {
+        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`). */
+    broadcastBackgroundDeferral(line) {
+        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. */
+    clearBackgroundHoldTimers(hold) {
+        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.
+     */
+    clearBackgroundHold(options) {
+        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.
+     */
+    releaseBackgroundHoldIds(hold, options) {
+        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.
+     */
+    flushBackgroundHoldUpdates(seg, hold) {
+        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.
+     */
+    trackBackgroundDispatch(update) {
+        if (this.closedTurn)
+            return;
+        const meta = codebuddyMetaOf(update);
+        const kind = String(update.sessionUpdate ?? '');
+        const row = update;
+        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 = {
+                    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.
+     */
+    noteDispatchProgress() {
+        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. */
+    noteAmbientActivity() {
+        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. */
+    onAmbientQuiet(wait) {
+        if (this.awaitingAmbient !== wait)
+            return;
+        this.finishAmbient(wait);
+    }
+    /** The drain outlived the ceiling: say where the rest will land, then close. */
+    onAmbientHard(wait) {
+        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).
+     */
+    finishAmbient(wait, options) {
+        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). */
+    clearAmbientWait() {
+        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.
+     */
+    bufferAmbientUpdate(seq, update) {
+        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. */
+    flushPendingAmbient(seg) {
+        if (this.pendingAmbientUpdates.length === 0) {
+            this.pendingAmbientTruncated = false;
+            return;
+        }
+        const truncated = this.pendingAmbientTruncated;
+        this.pendingAmbientTruncated = false;
+        const pending = this.pendingAmbientUpdates.splice(0, this.pendingAmbientUpdates.length);
+        this.pendingAmbientChars = 0;
+        if (truncated && !seg.finished) {
+            // The front of the drain's output was evicted from the bounded buffer:
+            // say so rather than letting the turn quietly start mid-story.
+            this.emitProse(seg, 'text', '\n[dsh-ntr] background output was truncated; the ACP transcript view still has every update.\n');
+        }
+        for (const entry of pending) {
+            if (seg.finished)
+                break;
+            this.foldInto(seg, entry.update, entry.seq);
+        }
+    }
+    /** Drop withheld drain updates: this turn is not the drain, or it is closing. */
+    clearPendingAmbient() {
+        this.pendingAmbientUpdates.length = 0;
+        this.pendingAmbientChars = 0;
+        this.pendingAmbientTruncated = false;
+    }
     /** The agent settled its `session/prompt`. Ends the turn's streaming face. */
     settle(outcome) {
         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) {
+        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.
+     */
+    flushScheduledClose() {
+        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.
+     */
+    drainTail() {
+        // 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;
+            // 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.
+     */
+    closeTurn(outcome, ambient) {
+        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
@@ -2609,6 +3811,41 @@ 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' });
             }
@@ -2620,20 +3857,31 @@ 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)
+                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);
         }
@@ -2648,25 +3896,60 @@ 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)
+        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() {
         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)
@@ -2674,10 +3957,30 @@ 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() {
         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();
     }
@@ -2741,12 +4044,24 @@ 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.
+     */
+    zeroOutputLine(stopReason) {
+        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`;
+    }
     onEvent(event) {
         if (this.disposed)
             return;
@@ -2755,9 +4070,50 @@ class TurnStreamController {
             return;
         if (row.type === 'session/update') {
             const typed = event;
+            // 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;
+            // 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;
-            const update = typed.update;
+            // 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
@@ -2770,18 +4126,81 @@ 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))
+            if (this.foldInto(seg, update, typed.seq))
                 this.cursorSeq = typed.seq;
         }
         else if (row.type === 'permission/request') {
+            this.tps.onBreak();
             const typed = event;
             this.pushProse(this.permissionLine(typed));
         }
         else if (row.type === 'permission/expired') {
+            this.tps.onBreak();
             const typed = event;
             this.pushProse(this.expiredLine(typed));
         }
     }
+    /** Feed one live update into the turn's burst tracker. Never called by replay. */
+    trackTps(typed) {
+        if (typed.seq <= this.tpsSeq)
+            return;
+        this.tpsSeq = typed.seq;
+        const update = typed.update;
+        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. */
+    pushLiveTps() {
+        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. */
+    finalizeTps() {
+        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.
      *
@@ -2818,15 +4237,124 @@ class TurnStreamController {
             return;
         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.
+     */
+    isAmbientOwned(update) {
+        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. */
+    noteTurnRequestId(update) {
+        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) {
+        // 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.
+     */
+    isForeignAmbientText(update) {
+        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).
      */
-    foldInto(seg, update) {
+    foldInto(seg, update, seq) {
         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 === '')
@@ -2836,11 +4364,36 @@ 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;
@@ -2854,6 +4407,13 @@ class TurnStreamController {
             }
             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;
@@ -3094,6 +4654,32 @@ export class BridgeManager {
     turnStreamFor(dshSessionId) {
         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() {
+        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() {
+        return {
+            taskMaxMs: this.tuning.backgroundTaskMaxMs,
+            graceMs: this.tuning.backgroundParkedGraceMs,
+        };
+    }
     /** Index a turn's controller, retiring whatever turn it supersedes. */
     rememberTurnStream(dshSessionId, controller) {
         const previous = this.turnStreams.get(dshSessionId);
@@ -3284,6 +4870,12 @@ export class BridgeManager {
     setSessionWorkspaceResolver(resolver) {
         this.sessionWorkspaceResolver = resolver;
     }
+    /**
+     * Set the attachment service or context used to resolve image attachments in user prompts.
+     */
+    setAttachmentResolver(resolver) {
+        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
@@ -3404,6 +4996,7 @@ export class BridgeManager {
                 ...(session.modes === undefined ? {} : { modes: session.modes }),
                 ...(session.availableCommands === undefined ? {} : { availableCommands: session.availableCommands }),
                 ...(session.usage === undefined ? {} : { usage: session.usage }),
+                ...(session.burst === undefined ? {} : { burst: session.burst }),
                 ...(session.released ? { released: true } : {}),
                 ...(session.running ? { running: true } : {}),
                 ...forkRowInfo(session, this.canForkNow(session.agentId)),
@@ -4316,6 +5909,21 @@ export class BridgeManager {
         for (const dshSessionId of this.chatAgentIntent.keys())
             this.syncConversationRoute(dshSessionId);
     }
+    /**
+     * Fold one settled ACP turn's measurable burst into the session aggregate and
+     * persist it. A turn with no measured inter-chunk gap contributes neither
+     * side: adding its tokens with zero time would inflate the session rate.
+     */
+    noteSessionBurst(session, outputTokens, burstMs) {
+        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();
+    }
     persistAgents() {
         const filePath = this.getStoragePath();
         if (!filePath)
@@ -4390,7 +5998,7 @@ export class BridgeManager {
                 continue;
             if (!this.defsMap.has(agentId))
                 continue;
-            const { title, modelId, reasoningEffort, modes, usage, hasHistory } = record;
+            const { title, modelId, reasoningEffort, modes, usage, burst, hasHistory } = record;
             const session = {
                 sessionId,
                 acpSessionId,
@@ -4404,6 +6012,7 @@ export class BridgeManager {
                 ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
                 ...(isPersistedModes(modes) ? { modes } : {}),
                 ...(isPersistedUsage(usage) ? { usage } : {}),
+                ...(isPersistedBurst(burst) ? { burst } : {}),
                 ...(hasHistory === true ? { hasHistory: true } : {}),
                 running: false,
                 turnSeq: 0,
@@ -4678,6 +6287,11 @@ export class BridgeManager {
         const def = this.defsMap.get(agentId);
         if (def === undefined || def.autoDiscoverModels === false || before === undefined)
             return false;
+        // A different model-slot identity is a corrected reading, not newly added
+        // models. Diffing across it would expose an entire real catalog the first
+        // time a parser fix replaces a mislabelled slot (Qoder CN).
+        if (before.model !== undefined && next.model !== undefined && before.model.configId !== next.model.configId)
+            return false;
         const known = new Set((before.model?.choices ?? []).map(choice => choice.value));
         const exposed = new Set(def.exposedModels ?? []);
         const added = (next.model?.choices ?? [])
@@ -5077,6 +6691,12 @@ export class BridgeManager {
         const wanted = modelChoice !== undefined && modelChoice !== '' ? modelChoice : undefined;
         if (wanted === undefined)
             return undefined;
+        // `category` is a UX hint, not identity: an agent may publish several
+        // `category: 'model'` options (Qoder CN ships `reasoning_effort` that way)
+        // and no explicit `model` id. In that case the selector is a guess, so a
+        // "not offered" verdict would refuse a perfectly valid pick — fail open.
+        if (!hasUnambiguousModelSelector(session.configOptions))
+            return undefined;
         const model = parseCatalogOptions(session.configOptions).model;
         if (model === undefined)
             return undefined;
@@ -5320,7 +6940,7 @@ export class BridgeManager {
         const session = await this.bridge(agentId).createSession(cwd);
         return { sessionId: session.sessionId };
     }
-    async prompt(sessionId, text) {
+    async prompt(sessionId, prompt) {
         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
@@ -5339,8 +6959,36 @@ export class BridgeManager {
             located = await this.locateOrResume(sessionId);
         }
         const { bridge, session } = located;
-        if (session.running)
+        // 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 = 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;
@@ -5351,9 +6999,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.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) {
@@ -5364,8 +7015,11 @@ export class BridgeManager {
             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) => {
             if (session.reclaimedTurnSeq === turnGen) {
@@ -5383,6 +7037,7 @@ export class BridgeManager {
                 return;
             }
             this.clearOrphanPrompt(session, turnGen);
+            endTurn();
             session.running = false;
             this.hub.broadcast({
                 type: 'turn/end',
@@ -5390,7 +7045,10 @@ export class BridgeManager {
                 turnId,
                 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 };
     }
     /** The late answer landed (or failed): the turn is no longer an orphan. */
@@ -5698,6 +7356,7 @@ export class BridgeManager {
     }
     sessionWorkspaceResolver;
     acpModeResolver;
+    attachmentResolver;
     /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
     acpModeCache = new Map();
     /** In-flight cold reads behind `chatSessionAcpModeAnswer`, keyed by session id. */
@@ -5982,6 +7641,44 @@ export class BridgeManager {
         });
         return { ok: true, reset: true };
     }
+    /**
+     * 聊天插话的槽位回收：宿主把插话作为同一会话在飞回合的下一步送达，
+     * 拒绝会让整条 host turn 失败。ACP 不能向运行中的 prompt 注入消息，
+     * 所以按插话语义中止当前回合，等 agent 真正结算后再让调用方重发。
+     *
+     * 只处理 `claimTurn` 的 `busy`（agent 仍持有本会话 prompt）；`unsettled`
+     * 说明我们这一侧已经释放过槽位（用户按过停止），保持原样拒绝。
+     *
+     * - 控制器已 settle（响应已到，延后收口还没释放闸门）：什么都不取消，只等闸门；
+     * - agent 真在跑：走用户取消同一条管线（session/cancel + 结算权限 + cancel fallback），
+     *   并立即关闭宿主这一侧的 segment，让闸门在 agent 应答/兜底后打开。
+     */
+    async reclaimChatPrompt(session, controller, signal) {
+        if (session.closed || session.released)
+            return 'ok';
+        if (!controller.hasSettled && session.promptInFlight === true) {
+            await this.bridge(session.agentId).cancel(session);
+            controller.abortActiveSegment();
+        }
+        return this.waitForSettleGate(session, signal);
+    }
+    /** 等 agent 侧 prompt slot 真正释放；步骤被取消时立即返回 aborted。 */
+    waitForSettleGate(session, signal) {
+        const pending = session.settled;
+        if (pending === undefined)
+            return Promise.resolve('ok');
+        if (signal?.aborted)
+            return Promise.resolve('aborted');
+        return new Promise(resolve => {
+            const done = (value) => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve(value);
+            };
+            const onAbort = () => { done('aborted'); };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            void pending.then(() => { done('ok'); });
+        });
+    }
     async *streamPrompt(options) {
         // The plugin's own conversation↔agent mapping decides who serves the turn
         // (see `bindChatAgent`): the driver may arrive here with the previous
@@ -6074,8 +7771,39 @@ 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) => {
+            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) => {
+                    if (typeof resolver.readFile === 'function') {
+                        try {
+                            const res = resolver.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' } };
@@ -6140,13 +7868,8 @@ export class BridgeManager {
             };
             return;
         }
-        // One prompt slot per session, and a turn the user aborted still occupies
-        // the AGENT's slot until it acknowledges the cancel (see `claimTurn`).
-        const claim = await bridge.claimTurn(session);
-        if (!claim.ok) {
-            // A first turn that never got the prompt slot delivered nothing either:
-            // give the conversation back instead of leaving it locked to an agent
-            // that refused the only message it was asked to serve.
+        const hasImages = (selection.images?.length ?? 0) > 0 || (selection.content?.some(b => b.type === 'image') ?? false);
+        if (hasImages && bridge.initResult?.agentCapabilities?.promptCapabilities?.image !== true) {
             if (session.provisionalLock === true)
                 this.rollbackFirstTurn(session);
             yield {
@@ -6154,15 +7877,92 @@ export class BridgeManager {
                 reason: {
                     kind: 'error',
                     failure: {
-                        message: claim.reason === 'busy'
-                            ? 'acp: this session already has a prompt in flight'
-                            : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
-                        code: 'turn_in_flight',
+                        message: `acp: agent "${agentId}" does not support image input`,
+                        code: 'image_unsupported',
                     },
                 },
             };
             return;
         }
+        // One prompt slot per session, and a turn the user aborted still occupies
+        // the AGENT's slot until it acknowledges the cancel (see `claimTurn`).
+        let claim = await bridge.claimTurn(session);
+        if (!claim.ok) {
+            // A STEER ("插话"): the host delivers the user's mid-turn message as the
+            // NEXT step of the SAME host turn, so the conversation's own ACP prompt
+            // is still on air. Refusing would fail the whole host turn. ACP forbids
+            // injecting into a running prompt, so the steer's real semantic — abort
+            // the current turn, then send this one — is spelled cancel + wait +
+            // re-claim here.
+            //
+            // Only `busy` can be a steer: it means the AGENT still holds OUR prompt
+            // (`promptInFlight`). `unsettled` means our side already released the
+            // slot (the person pressed stop, or an earlier steer cancelled): the
+            // agent has not acknowledged yet, and quietly queueing the next message
+            // behind a turn the user stopped is not this path's business — that
+            // stays the honest `turn_in_flight` refusal below.
+            //
+            // Only the conversation's OWN in-flight turn qualifies (its live stream
+            // controller, on this very session). A `/acp` RPC turn has no chat
+            // controller, and another conversation never reaches this session, so
+            // both keep the plain refusal: nothing may be cancelled behind a
+            // caller's back.
+            const chatController = claim.reason === 'busy' && options.sessionId !== undefined
+                ? this.turnStreamFor(options.sessionId)
+                : undefined;
+            if (options.sessionId !== undefined
+                && chatController !== undefined
+                && !chatController.stale
+                && chatController.session === session) {
+                const reclaimed = await this.reclaimChatPrompt(session, chatController, options.signal);
+                if (reclaimed === 'aborted') {
+                    // The person pressed stop while the previous turn was winding down:
+                    // the steer is theirs to re-send, nothing goes to the agent.
+                    yield {
+                        type: 'finish',
+                        reason: { kind: 'aborted', failure: { message: 'aborted', code: 'ABORTED' } },
+                    };
+                    return;
+                }
+                // A first turn that produced nothing rolled its provisional lock back
+                // and CLOSED (and forgot) this session: the steer needs a fresh one.
+                if (session.closed || session.released) {
+                    try {
+                        session = await this.getOrCreateDshSession(options.sessionId, agentId);
+                    }
+                    catch (err) {
+                        yield {
+                            type: 'finish',
+                            reason: { kind: 'error', failure: { message: describeError(err), code: 'session_init_failed' } },
+                        };
+                        return;
+                    }
+                }
+                // Same bridge: the session may have been re-created, but the
+                // conversation is still served by this agent's process.
+                claim = await bridge.claimTurn(session);
+            }
+            if (!claim.ok) {
+                // Never roll the provisional lock back here: a failed claim means
+                // ANOTHER prompt holds the slot (or the agent has not settled it), and
+                // that turn owns the conversation's lock. Closing the session would
+                // kill a turn that is actively streaming — the refusal already tells
+                // the user to retry.
+                yield {
+                    type: 'finish',
+                    reason: {
+                        kind: 'error',
+                        failure: {
+                            message: claim.reason === 'busy'
+                                ? 'acp: this session already has a prompt in flight'
+                                : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
+                            code: 'turn_in_flight',
+                        },
+                    },
+                };
+                return;
+            }
+        }
         // Same-agent model/effort switches ride the SAME ACP session (context
         // stays continuous); switching to another agent lands in a separate one
         // via the `${dshSessionId}:${agentId}` key in getOrCreateDshSession.
@@ -6280,8 +8080,11 @@ 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 = selection.content && selection.content.length > 0
+                ? selection.content
+                : [{ 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.
@@ -6289,9 +8092,76 @@ 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) => {
                 if (session.reclaimedTurnSeq === turnGen) {