@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/acpSession.js

@@ -1,1475 +0,0 @@
-/**
- * One ACP session: `session/new`, `session/prompt`, `session/cancel`, `session/update` routing, and
- * the buffered event/turn sinks the deleted `BridgeSession` SPI required.
- *
- * Built on the SDK's `ClientContext.buildSession(cwd)` / `ActiveSession` convenience wrapper rather
- * than raw `session/new`/`session/prompt` requests: `ActiveSession.prompt(...)` both sends
- * `session/prompt` *and* enqueues the eventual response as a `{kind: 'stop', ...}` message onto the
- * exact same internal queue `nextUpdate()` reads `{kind: 'session_update', ...}` messages from — so
- * one continuous `nextUpdate()` loop (see {@link runReadLoop}) sees every `session/update` in order
- * interleaved with the turn's own completion, with no separate `.onNotification('session/update', …)`
- * registration needed. That registration would not even be possible after the fact in the way this
- * class is constructed (`AcpConnection` is already past `ClientApp.connect()` by the time
- * `AcpSession.open` runs, and `acpClient.ts` documents that `connect()` copies its handler
- * table at connect time) — `buildSession`'s routing is installed unconditionally by the SDK itself,
- * independent of anything a caller registers via `connectAgent`'s `configure` hook.
- *
- * One responsibility lives here rather than in `sessionUpdateMapper.ts`, because this is the layer
- * with a turn's whole lifetime in view, not just one `session/update` at a time:
- *
- * - **`agent_message` synthesis** (see {@link flushMessageCompleted}). The server's
- *   `CoworkEngine` buffers `agent_message_chunk`/`agent_thought_chunk` text and only flushes it on a ~400ms gap
- *   between deltas or on an item-backed event — ending the turn does not flush it. Both deleted
- *   bridges closed every assistant message with `agent_message` (item-backed, so it *is* the
- *   flush); nothing in ACP's own vocabulary plays that role, so this class synthesizes it — once
- *   when the streaming `messageId` changes mid-turn, and once more at turn end. The same event is
- *   also what makes the server attach a turn's `usage_update` figures
- *   (`CoworkEngine.appendCoworkTimelineEvent`'s `MessageCompleted` branch reads and clears
- *   `latestUsageByRun`) — without it those figures are captured and then silently discarded.
- *
- * **`user_message_chunk` folding used to be the second one, and is gone.** It lived here as a
- * per-session accumulator, and `adoption.ts` carried a second copy of the same rule for replay —
- * two implementations that had already drifted (replay split a message on any interleaved event;
- * this one did not). Phase 7 moved the fold to `CoworkEngine`, which was already buffering
- * `agent_message_chunk` by exactly the ACP rule that governs all three chunk kinds (`ContentChunk`,
- * `types.gen.d.ts:3456`: same `messageId` = same message). Chunks now pass straight through, and
- * the server's turn-end / replay-end flush is what closes a message.
- */
-import { randomUUID } from 'node:crypto';
-import { certifiedRuntime, ForegroundOutputBoundary } from '../qoderAdapter/foregroundOutput.js';
-import { BackgroundTerminalRepair, nativeTerminalHistoryPath } from '../qoderAdapter/backgroundTerminal.js';
-import { SubworkBoundary, supportsSubworkMeta } from '../qoderAdapter/subwork.js';
-import { methods } from '@agentclientprotocol/sdk';
-import { jsonRpcErrorCode } from './acpClient.js';
-import { settleUpdates } from './adoption.js';
-import { mapSessionUpdate, SessionMapperState } from './sessionUpdateMapper.js';
-import { SessionMapperScopes } from './sessionScope.js';
-import { newSessionMetaFor } from './activityReporting.js';
-import { buildSessionMcpServers } from './delegationMcp.js';
-import { flatChoicesOf, modesAlreadyRepresented, normalizeConfigOptions, SYNTHESIZED_MODES_CONFIG_ID } from './configOptions.js';
-/**
- * Points the connection's diverted-update stream at the session that owns it.
- *
- * **Belongs here, not in `AcpAgents`.** Both ways a session comes into existence run through this
- * file, and only one of them goes through the agent registry — the first attempt bound from there
- * and every test that opens a session directly then saw *every* update diverted, because an unbound
- * connection cannot tell its own session from a child's and must assume the worse case. Binding
- * where the session is constructed makes "a session exists" and "the transport knows about it" the
- * same moment.
- *
- * An empty id means the agent named no session, so nothing is bound and every update keeps being
- * reported rather than silently handed to an SDK that would drop it.
- */
-function bindDivertedUpdates(connection, ownSessionId, session) {
-    if (ownSessionId.length === 0)
-        return;
-    connection.bindDraftUpdates(ownSessionId, (update) => session.applyDivertedUpdate(update));
-}
-/**
- * The steering extension's JSON-RPC method. **Not an ACP method** — `grep steer` over the pinned
- * SDK's `dist/schema/types.gen.d.ts` returns nothing. It is implemented by `claude-agent-acp`
- * (`acp-agent.js@0.76.0:164`), whose own comment calls it a *"Custom (extension) request method ...
- * Named `_session/steering` per the agreed ACP steering wire protocol"*; the leading underscore is
- * ACP's extension namespace. It is therefore reached through the untyped `request<Response, Params>
- * (method: string, …)` overload rather than `methods.agent.*`, and every caller must check
- * {@link AcpConnection.supportsSteering} first.
- */
-const STEER_METHOD = '_session/steering';
-/**
- * The adapter's *stop one background task* extension method. **Not an ACP method** either — it is
- * `claude-agent-acp`'s own `ASYNC_TASK_STOP_METHOD` (`acp-agent.js@0.79.0:165`), whose own comment
- * reads *"Stops one Claude background task without cancelling the parent prompt turn."*
- * `codex-acp@1.12.0` registers the same literal name with the same params
- * (`dist/index.js:31608`, `:35126-35129`, `:32395-32406`). Reached through the untyped `request`
- * overload, for the reason {@link STEER_METHOD} documents.
- */
-const ASYNC_TASK_STOP_METHOD = '_session/async_task/stop';
-/**
- * Narrow a `_session/steering` response onto {@link SteerOutcome}, or throw.
- *
- * The extension answers with one of three outcomes (`acp-agent.js@0.76.0:1737`, `:1751`, `:1779`):
- *
- * - `injected` — a turn was running and the message went into it.
- * - `promptRequired` (with `reason: "noRunningTurn"`) — no turn was running and we opted in, so the
- *   agent did nothing at all and the content stays host-owned.
- * - `startedNewTurn` — no turn was running and the client did *not* opt in, so the agent detached a
- *   `prompt()` of its own.
- *
- * **`startedNewTurn` throws rather than mapping to anything** (decision D13). We always send
- * `idleBehavior: "promptRequired"` ({@link AcpSession.steer}), so receiving it means the agent
- * ignored the opt-in — and what it handed back is a turn nobody awaits: it never enters our queue,
- * never lands an item, and never produces a `turn_done`, in a system that accounts by turn.
- * Absorbing it as "injected" would mark a message delivered to a turn we are not tracking;
- * absorbing it as "promptRequired" would submit the same message a second time. Neither is a
- * recovery, so this fails where the contract broke, loudly enough to name.
- *
- * An outcome nobody recognises throws for the same reason: silently reading it as `injected` would
- * record a delivery that may never have happened.
- */
-export function mapSteerOutcome(result) {
-    const outcome = result?.outcome;
-    if (outcome === 'injected')
-        return 'injected';
-    if (outcome === 'promptRequired')
-        return 'promptRequired';
-    if (outcome === 'startedNewTurn') {
-        throw new Error(`[acp] the agent answered ${STEER_METHOD} with 'startedNewTurn', a turn this client never ` +
-            "opted into and does not track: we always send _meta.steering.idleBehavior = 'promptRequired'.");
-    }
-    throw new Error(`[acp] unrecognised ${STEER_METHOD} outcome: ${JSON.stringify(outcome)}`);
-}
-/**
- * The value `registerPendingApproval`'s resolver receives when nobody is ever going to answer —
- * the session closed, the connection died, or the agent itself cancelled the request — rather
- * than a real user choice. `PermissionOptionId` is an unconstrained `string`, so a fixed literal
- * like `'deny'` risks colliding with an agent's own option id and turning "nobody answered" into
- * a fabricated selection (review finding: task-5, item 6). Randomized per process start and never
- * sent over the wire to any agent, so no real option id can ever equal it in practice.
- */
-const ABANDONED_ANSWER = `__acp_session_abandoned_${randomUUID()}__`;
-/**
- * The value `registerPendingElicitation`'s resolver receives when nobody is ever going to answer.
- * Unlike {@link ABANDONED_ANSWER}, this needs no randomized sentinel: `CreateElicitationResponse`'s
- * `action` union already has `'cancel'` as a real ACP outcome meaning exactly this ("the client
- * will not provide a response"), so there is no risk of it colliding with a real user answer the
- * way a fixed permission-option-id literal would.
- */
-const ABANDONED_ELICITATION_ANSWER = { action: 'cancel' };
-/** ACP's `StopReason` (`end_turn | max_tokens | max_turn_requests | refusal | cancelled`) → the wire's `TurnStopReason`. `'cancelled'` is handled by the caller (it forces `status: 'interrupted'` instead, which carries no `stopReason` — see {@link AcpSession.finishTurn}), so it never actually reaches this function; the arm is kept so the switch stays exhaustive over every literal `StopReason` can hold. */
-function mapStopReason(reason) {
-    switch (reason) {
-        case 'end_turn':
-            return 'end_turn';
-        case 'max_tokens':
-            return 'max_tokens';
-        case 'max_turn_requests':
-            return 'max_turns';
-        case 'refusal':
-            return 'refusal';
-    }
-}
-function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-/**
- * One `_session/steering` round trip, shared verbatim by {@link AcpSession.open} and
- * {@link AcpSession.attach} — the two differ only in where the session id comes from.
- *
- * The request shape is the extension's `parseSteerRequest` (`acp-agent.js@0.76.0:192-215`): a non-empty
- * `sessionId`, a non-empty `prompt` array of ACP `ContentBlock`s, and an optional
- * `_meta.steering.idleBehavior` whose **only** accepted value is `promptRequired` — anything else is
- * `invalidParams`. We always send it; see {@link mapSteerOutcome} for why.
- *
- * `blocks` is ACP's own `ContentBlock[]`, exactly like {@link AcpSession.prompt} — **this boundary
- * used to narrow it to a `string`, and that narrowing was ours, not the protocol's**. The extension
- * takes a `prompt` array and hands it to the same `promptToClaude(params)` a `session/prompt` goes
- * through, so an image steers as well as it prompts. While this parameter was a `string`, an image
- * attached to a message the reader chose to interject stopped dead here — split off into a queue row
- * of its own, leaving *"this is what I mean"* next to nothing.
- *
- * `priority` is the extension's `_meta.steering.priority`. **`undefined` means the caller is
- * deliberately naming none**, and that is not the same as picking the default: the adapter silently
- * ignores a value it does not recognise and only `next` is lossless, so a timing is only sent when
- * the adapter declared it accepts it. (The adapter's own comment about its internal
- * `STEER_PRIORITY_NOW` / `STEER_PRIORITY_LATER` constants — *"an internal Claude implementation
- * detail, not part of the wire contract"*, `acp-agent.js@0.76.0:181-188` — is about those
- * constants, not about `_meta`, which `parseSteerRequest` passes through whole. 0.76.0 picks the
- * priority itself (`:1762-1763`) and ignores `_meta.steering.priority`. This sentence used to
- * name a symbol `STEER_PRIORITY`; there is no such symbol in 0.76.0.)
- */
-async function steerRequest(connection, sessionId, blocks, priority) {
-    const result = await connection.connection.agent.request(STEER_METHOD, {
-        sessionId,
-        prompt: blocks,
-        _meta: { steering: { idleBehavior: 'promptRequired', ...(priority === undefined ? {} : { priority }) } },
-    });
-    return mapSteerOutcome(result);
-}
-/**
- * One `_session/async_task/stop` round trip, shared by {@link AcpSession.open} and
- * {@link AcpSession.attach} exactly as {@link steerRequest} is — the two differ only in where the
- * session id comes from.
- *
- * The request shape is the adapter's own `parseAsyncTaskStopRequest`
- * (`claude-agent-acp@0.79.0` `dist/acp-agent.js:166-173`): a non-empty `sessionId` and a non-empty
- * `asyncTaskId`, both trimmed strings, and nothing else. `codex-acp@1.12.0` parses the identical
- * pair (`dist/index.js:35126-35129`, a zod object with `.trim().min(1)` on both), so there is one
- * shape here, not a per-vendor branch. The response is `{ stopped: boolean }` on both
- * (`acp-agent.js:1784-1798`, `index.js:32395-32406`), which this layer deliberately does **not**
- * turn into a verdict: `stopped: false` only means the adapter had no live task under that id
- * right now, and the platform's real answer
- * — did the background task actually end — arrives as the agent's own next `async_task_state_update`
- * for this `(sessionId, asyncTaskId)`. Reporting `false` as a failure would make the server show an
- * error for a task that is, by then, already settled.
- *
- * Reached through the untyped `request` overload for the same reason {@link steerRequest} is: this
- * is an adapter extension in ACP's `_`-prefixed namespace, not an ACP method — `grep async_task`
- * over the pinned SDK's `types.gen.d.ts` returns nothing.
- */
-async function asyncTaskStopRequest(connection, sessionId, asyncTaskId) {
-    const result = await connection.connection.agent.request(ASYNC_TASK_STOP_METHOD, {
-        sessionId,
-        asyncTaskId,
-    });
-    if (result?.stopped !== true) {
-        // Logged, never thrown: see this function's own doc for why `stopped: false` is not a failure.
-        console.warn(`[acp] ${ASYNC_TASK_STOP_METHOD} reported no live task '${asyncTaskId}' on session ${sessionId}`);
-    }
-}
-async function providerTaskStopRequest(connection, sessionId, taskId, requestId) {
-    const result = await connection.connection.agent.request('_axom/task/stop', {
-        sessionId, taskId, requestId,
-    });
-    if (result?.state === 'accepted')
-        return 'accepted';
-    if (result?.state === 'unknown')
-        return 'unknown';
-    throw new Error('Provider task stop was rejected');
-}
-/**
- * One `session/set_config_option` (`SetSessionConfigOptionRequest`, `types.gen.d.ts:5102-5132`) or
- * — for the daemon's synthesized {@link SYNTHESIZED_MODES_CONFIG_ID} — `session/set_mode`
- * (`SetSessionModeRequest`, `:5079`), shared by {@link AcpSession.open} and {@link AcpSession.attach}
- * the same way {@link steerRequest} is.
- *
- * Returns the normalized, full snapshot either way. `session/set_config_option`'s response carries
- * the agent's own full `configOptions` list (`SetSessionConfigOptionResponse`, `:2949-2964`; the
- * `configOptions` field itself at `:2953`) — which never carries the synthesized `acp:modes` entry,
- * so a synthesized entry from the last snapshot is carried across by hand. `session/set_mode`'s
- * response carries no list at all (`SetSessionModeResponse`, `:2934-2945`), so that snapshot is
- * built locally by applying `value` to the synthesized entry already in `current()`.
- *
- * `current` and `remember` are how the two construction paths ({@link AcpSession.open}'s closure
- * over its own `let snapshot`, {@link AcpSession.attach}'s over its own) each keep one mutable
- * "latest snapshot" cell without this function needing to know which kind of session it is serving.
- */
-function setConfigOptionRequest(connection, sessionId, current, remember) {
-    return async (configId, value) => {
-        const agent = connection.connection.agent;
-        if (configId === SYNTHESIZED_MODES_CONFIG_ID) {
-            if (typeof value !== 'string') {
-                throw new Error(`[acp] ${SYNTHESIZED_MODES_CONFIG_ID} takes a mode id (a string), got ${typeof value}`);
-            }
-            await agent.request(methods.agent.session.setMode, { sessionId, modeId: value });
-            const next = current().map((o) => (o.id === configId && o.type === 'select' ? { ...o, currentValue: value } : o));
-            remember(next);
-            return next;
-        }
-        const params = typeof value === 'boolean' ? { sessionId, configId, type: 'boolean', value } : { sessionId, configId, value };
-        const response = await agent.request(methods.agent.session.setConfigOption, params);
-        // The agent's reply has no `modes` field to normalize against — a synthesized entry, if there
-        // was one, survives only by being carried across from the last snapshot.
-        //
-        // Carried across under the *same* condition `normalizeConfigOptions` synthesizes under
-        // ({@link modesAlreadyRepresented}), not unconditionally: an agent that only starts declaring
-        // its own equivalent control *after* we synthesized one — it grew a `category: "mode"` option
-        // between the open and this set, or (pi's shape) it already offers the identical choice list
-        // under an id of its own — would otherwise get two pickers for one thing on the same session,
-        // its real one and our stale stand-in for it. The agent's own always wins.
-        const reNormalized = normalizeConfigOptions(response.configOptions, null);
-        const carried = current().find((o) => o.id === SYNTHESIZED_MODES_CONFIG_ID);
-        const carriedChoices = (carried ? flatChoicesOf(carried) : null) ?? [];
-        const synthesized = carried && !modesAlreadyRepresented(reNormalized, carriedChoices) ? carried : undefined;
-        const next = reNormalized.concat(synthesized ? [synthesized] : []);
-        remember(next);
-        return next;
-    };
-}
-/** `payload[key]` narrowed to `string`, or `null` — every messageId/text field this file reads off a mapped `WireEvent` goes through this rather than an `as` cast, since the payload is `Record<string, unknown>` by construction. */
-function stringField(payload, key) {
-    const value = payload[key];
-    return typeof value === 'string' ? value : null;
-}
-/**
- * The queue behind an attached session's `nextUpdate()`, standing in for the one the SDK's
- * `ActiveSession` keeps internally.
- *
- * Three producers feed it and they must interleave in arrival order: `session/update` notifications
- * (via {@link LiveUpdateSource}), the `session/prompt` response that ends a turn, and that same
- * request's rejection. `ActiveSession` routes all three onto one queue — which is what lets
- * {@link AcpSession.runReadLoop} be a single loop — so this reproduces that exactly rather than
- * giving the prompt result its own channel.
- *
- * {@link fail} is the `dispose()` half: it is permanent and drops anything still buffered, because
- * its only caller is a session that is closing. Leaving buffered updates readable there would emit
- * events for a session the manager has already retired.
- */
-class AttachedQueue {
-    items = [];
-    waiters = [];
-    failure = null;
-    push(value) {
-        this.settle({ ok: true, value });
-    }
-    /**
-     * A one-shot rejection — a failed `session/prompt`, not a dead queue. `runReadLoop` turns exactly
-     * this into a `failed` TurnResult and then keeps reading for the next prompt, mirroring how
-     * `ActiveSession.prompt()` routes its own rejection onto the same queue.
-     */
-    pushError(error) {
-        this.settle({ ok: false, error });
-    }
-    fail(error) {
-        if (this.failure)
-            return;
-        this.failure = { error };
-        this.items.length = 0;
-        for (const waiter of this.waiters.splice(0))
-            waiter.reject(error);
-    }
-    next() {
-        const head = this.items.shift();
-        if (head)
-            return head.ok ? Promise.resolve(head.value) : Promise.reject(head.error);
-        if (this.failure)
-            return Promise.reject(this.failure.error);
-        return new Promise((resolve, reject) => {
-            this.waiters.push({ resolve, reject });
-        });
-    }
-    settle(item) {
-        if (this.failure)
-            return;
-        const waiter = this.waiters.shift();
-        if (!waiter) {
-            this.items.push(item);
-            return;
-        }
-        if (item.ok)
-            waiter.resolve(item.value);
-        else
-            waiter.reject(item.error);
-    }
-}
-export class AcpSession {
-    session;
-    connection;
-    outbox = [];
-    /**
-     * This session's `toolCallId → name` memory, for the `tool_call_update`s ACP lets arrive with
-     * no `name` on them ("unchanged", not "unknown" — see {@link SessionMapperState}).
-     *
-     * Per instance, like every other cross-update field here, and for the same reason `inFlightTurns`
-     * is: one `AcpSession` is one ACP session, and a registry shared between two of them would let
-     * one session's tool call name a different session's update.
-     */
-    rootRuntimeId = randomUUID();
-    scopes = new SessionMapperScopes((scope) => new SessionMapperState((raw) => { if (scope.nativeSessionId === this.session.sessionId)
-        this.reportActivity(raw); }));
-    mapperFor(nativeSessionId) {
-        return this.scopes.get({ rootRuntimeId: this.rootRuntimeId, nativeSessionId });
-    }
-    eventSink = null;
-    turnSink = null;
-    backgroundWriterUnconfirmed = false;
-    exactExecutionUnconfirmed = false;
-    /**
-     * This session's latest agent-reported activity-state consumer — `agentSessions.ts`, via
-     * `AcpAgentSession.onActivity`. Kept apart from {@link eventSink} on purpose: an activity push is
-     * a level, not an edge (see the `agent_session_state` frame's own doc comment), so it must never
-     * pass through the `WireEvent`/journal/seq machinery {@link eventSink} feeds.
-     */
-    activitySink = null;
-    draining = false;
-    /**
-     * Every turn this session has started and not yet reported a result for, oldest first.
-     *
-     * A list rather than a single `currentTurn`, because `session/prompt` is a request per turn and
-     * ACP places no bar on a second one going out while the first is still running — the SDK's
-     * `ActiveSession.prompt` enqueues a `{kind:'stop'}` message per call, so two prompts really do
-     * produce two completions on the read queue, in the order the agent answers them. Folding a
-     * second prompt into the first turn (`currentTurn ??=`) meant the second `stop` found no turn to
-     * finish and its result was dropped outright: the second turn's deltas arrived, but no
-     * `agent_message` ever flushed the server's delta buffer for them and no `turn_done` ever
-     * reached the run, which stayed parked on work that had already finished. Pinned by clause 7 of
-     * `contract.ts`.
-     *
-     * Strictly FIFO, which is an assumption worth naming: a stop message is matched to the *oldest*
-     * unfinished turn rather than to the prompt that produced it, because JSON-RPC ids live inside
-     * the SDK and never reach this class. Two overlapping turns that the agent answers out of order
-     * therefore swap results. Both results still arrive, which is what everything downstream needs;
-     * per-prompt attribution would need an id ACP does not put on `session/update` either.
-     */
-    inFlightTurns = [];
-    /**
-     * Whether a `session/prompt` round trip is outstanding on the agent **right now**.
-     *
-     * This is the turn's ground truth: {@link inFlightTurns} is pushed when the prompt goes out and
-     * shifted when the agent answers, so it says what the agent is doing rather than what anything
-     * else recorded about it. `TaskRegistry.snapshot()` reads this getter directly, live, on every
-     * call -- there is no bracket of started/finished events kept elsewhere on the daemon side that
-     * could go stale or outlive it (that bookkeeping set is gone; see the design doc's §4.1/§4.2).
-     * The signal that *can* now outlive the events it describes is the agent's own self-reported
-     * activity (`lastActivityRaw`): a vendor that says `running` and then falls silent stays
-     * "running" until it says otherwise, by deliberate policy (no invented timeout; §4.4). This
-     * getter has no equivalent failure mode -- it cannot outlive the round trip it is asking about,
-     * because it *is* that round trip, sampled live rather than recorded.
-     */
-    get turnRunning() {
-        return this.inFlightTurns.length > 0;
-    }
-    /** Whether this session's stdio is still readable -- false once the read loop died. */
-    get readable() {
-        return this.readLoopDead === null;
-    }
-    nativeTerminalRepair;
-    foregroundOutput;
-    subworkBoundary;
-    closed = false;
-    connectionAborted = false;
-    /**
-     * Why {@link runReadLoop} stopped for good, or `null` while it is still reading. Set at all three
-     * of the loop's permanent exits, so the flag means exactly "no `stop` message can ever arrive
-     * again"; {@link prompt} is the reader.
-     *
-     * Without it, a prompt sent after the loop died was `session/prompt`-ed into a queue nobody reads:
-     * no `TurnResult`, no `turn_done`, no error card and no timeout, and every retry the user makes
-     * joins the same silence. Two of the consequences live outside this file, which is why no
-     * per-file review caught them:
-     *
-     * - `TaskRegistry.canUpdate()` samples {@link turnRunning} live off {@link inFlightTurns} rather
-     *   than accumulating a bracketed ref (2026-09-21 rewrite — the old `agentTasks` Set could go
-     *   stale on its own, holding a ref no real condition still justified; live sampling means a mark
-     *   can no longer outlive the condition that set it). That does not make this concern go away,
-     *   because the condition here would be real, not stale bookkeeping: {@link inFlightTurns} is
-     *   still pushed unconditionally at the bottom of this method, and only {@link finishTurn} pops
-     *   it. A prompt sent into a connection nobody is reading gets no `session/update`, so nothing
-     *   would ever call {@link finishTurn} for that entry — the turn is genuinely, permanently
-     *   unfinished, so live sampling faithfully reports it and pins `turnRunning` to `true`, and with
-     *   it `canUpdate()` to `false`, for the rest of this process's life. Same failure mode as the old
-     *   leak, one call frame earlier: a busy mark nothing will ever clear. This flag's early return is
-     *   what pairs that push with an immediate {@link finishTurn} instead of leaving it stuck.
-     * - Each retry `touch()`es the session, so retrying keeps `lastActivityAt` fresh and `sweepIdle`
-     *   never reclaims it either.
-     *
-     * Deliberately a flag of its own rather than reusing {@link closed}: `close()` short-circuits its
-     * whole body on `closed`, so setting that here would skip `session/cancel` and `dispose()` on a
-     * session that was never actually closed.
-     */
-    readLoopDead = null;
-    /** Tracks the streaming assistant message for `agent_message` synthesis — see {@link flushMessageCompleted}. */
-    sawMessageContent = false;
-    currentMessageId = null;
-    /**
-     * `requestId` → the resolver for one outstanding `session/request_permission` round trip.
-     * `AcpSession` owns this map (rather than `permission.ts` keeping its own) purely so `close()`
-     * can settle every outstanding card the same way the deleted Claude Code bridge's
-     * `denyAllPending()` did — a request with no user left to answer it must not hang the agent
-     * process forever. `permission.ts` is the only thing that populates it, via
-     * {@link registerPendingApproval}; nothing in this file does.
-     */
-    connectionGeneration = randomUUID();
-    permissionsInterrupted = false;
-    permissionOrigins = new Set();
-    // One parent per exact native ID, including edges whose parent has not arrived yet.
-    permissionParents = new Map();
-    unresolvedPermissionOrigins = new Set();
-    pendingApprovals = new Map();
-    settledApprovals = new Map();
-    callbacksComplete = true;
-    publishCallbacks() {
-        this.connection.publishCallbacks?.({ rootSessionId: this.session.sessionId,
-            connectionGeneration: this.connectionGeneration, complete: this.callbacksComplete,
-            pending: this.callbacksComplete ? [...this.pendingApprovals].map(([requestId, entry]) => ({ requestId,
-                originNativeSessionId: entry.originNativeSessionId, rpcRequestId: entry.rpcRequestId })) : [],
-            settled: this.callbacksComplete ? [...this.settledApprovals].map(([requestId, reason]) => ({ requestId, reason })) : [] });
-    }
-    /**
-     * `requestId` → the resolver for one outstanding `elicitation/create` round trip. Parallel to
-     * {@link pendingApprovals}, and drained the same way for the same reason — `close()` and the
-     * connection-abort branch of `runReadLoop` must not leave the agent process blocked inside
-     * `elicitation/create` forever. A separate map rather than reusing `pendingApprovals`, because the
-     * resolved value differs in kind: a `CreateElicitationResponse` object, not a bare option-id
-     * string — see `AgentFrame.AgentElicitationAnswer`'s KDoc for why the two frames (and so the two
-     * maps) do not collapse into one.
-     */
-    pendingElicitations = new Map();
-    readLoopDone;
-    constructor(session, connectionSignal, connection) {
-        this.session = session;
-        this.connection = connection;
-        if (connectionSignal.aborted)
-            this.connectionAborted = true;
-        else
-            connectionSignal.addEventListener('abort', () => {
-                this.connectionAborted = true;
-                this.nativeTerminalRepair?.close();
-            }, { once: true });
-        if (certifiedRuntime(connection.agentInfo))
-            this.foregroundOutput = new ForegroundOutputBoundary(this.session.sessionId);
-        if (supportsSubworkMeta(connection.agentInfo))
-            this.subworkBoundary = new SubworkBoundary(this.session.sessionId);
-        this.readLoopDone = this.runReadLoop();
-    }
-    /** Only actual hosted sessions enable the certified Qoder boundary; probes never read history. */
-    enableBackgroundTerminalRepair(cwd, historyHome, restoreCalls = false) {
-        if (this.closed || this.connectionAborted || this.readLoopDead || this.nativeTerminalRepair)
-            return;
-        const path = nativeTerminalHistoryPath(this.connection.agentInfo, this.session.sessionId, cwd, historyHome);
-        if (!path)
-            return;
-        this.nativeTerminalRepair = new BackgroundTerminalRepair({
-            includeProcess: this.subworkBoundary !== undefined,
-            path, cwd, restoreCalls, nativeSessionId: this.session.sessionId, emit: event => this.emitEvent(event),
-        });
-        this.nativeTerminalRepair.start();
-    }
-    /**
-     * Open a new ACP session via `session/new` and start driving it.
-     *
-     * `nativeSessionId` mirrors the deleted `AgentBridge.open()` contract verbatim: `null` when no
-     * usable id came back, **never** `''` — the server persists any non-null value it is given as an
-     * identity and later resumes from it, so an agent that technically returns an empty string must be
-     * degraded to `null` here rather than trusted at face value.
-     */
-    static async open(connection, options) {
-        // Opts into claude-agent-acp's raw-SDK-message channel (design §5.1/§2.1) for exactly the
-        // session that needs it — `undefined` for every other agent, in which case `buildSession` keeps
-        // taking the plain `cwd` string it always has when no MCP server is configured. The explicit
-        // request path carries the same MCP list as session/load, including any scoped delegation lease.
-        const meta = newSessionMetaFor(connection.agentInfo?.name);
-        const mcpServers = buildSessionMcpServers(options.mcpServers, options.delegationMcp);
-        if (options.delegationMcp)
-            connection.redactStderrSecret(Object.values(options.delegationMcp.headers)[0]);
-        const builder = meta || mcpServers.length > 0
-            ? connection.connection.agent.buildSession({ cwd: options.cwd, mcpServers, ...(meta ? { _meta: meta } : {}) })
-            : connection.connection.agent.buildSession(options.cwd);
-        const activeSession = await builder.start();
-        // `NewSessionResponse` (`acp.d.ts:329`'s `newSessionResponse` getter) carries both halves
-        // `normalizeConfigOptions` needs: `configOptions` (`types.gen.d.ts:2546`) and `modes` (`:2542`).
-        const response = activeSession.newSessionResponse;
-        let snapshot = normalizeConfigOptions(response.configOptions, response.modes);
-        const drivenSession = {
-            sessionId: activeSession.sessionId,
-            // `ActiveSession.prompt`'s own parameter is already `string | ContentBlock | ContentBlock[]`
-            // (`acp.d.ts:338`) — it is this class's `DrivenSession` boundary that was narrow, not the SDK's.
-            prompt: (blocks) => activeSession.prompt(blocks),
-            nextUpdate: () => activeSession.nextUpdate(),
-            dispose: () => activeSession.dispose(),
-            // A notification (`ClientContext.notify`, not `.request`) — `session/cancel` cancels the whole
-            // prompt turn and expects no response, unlike `$/cancel_request`'s per-request
-            // `SendRequestOptions.cancellationSignal` mechanism.
-            cancel: () => connection.connection.agent.notify(methods.agent.session.cancel, { sessionId: activeSession.sessionId }),
-            steer: (blocks, priority) => steerRequest(connection, activeSession.sessionId, blocks, priority),
-            setConfigOption: setConfigOptionRequest(connection, activeSession.sessionId, () => snapshot, (next) => (snapshot = next)),
-            stopAsyncTask: (asyncTaskId) => asyncTaskStopRequest(connection, activeSession.sessionId, asyncTaskId),
-            providerTaskStop: (taskId, requestId) => providerTaskStopRequest(connection, activeSession.sessionId, taskId, requestId),
-        };
-        const session = new AcpSession(drivenSession, connection.connection.signal, connection);
-        // Claude's activity-state notification arrives on the connection, not on this session's own
-        // `session/update` stream (see `activityReporting.ts` and `AcpConnection.bindActivity`'s doc
-        // comment for why `extNotification` cannot be routed the way `session/update` is). Bound
-        // unconditionally: a connection whose agent never sends `_claude/sdkMessage` simply never
-        // invokes this sink.
-        connection.bindActivity((raw) => session.reportActivity(raw));
-        const nativeSessionId = activeSession.sessionId.length > 0 ? activeSession.sessionId : null;
-        bindDivertedUpdates(connection, activeSession.sessionId, session);
-        return { session, nativeSessionId, configOptions: snapshot };
-    }
-    /**
-     * Drive a session the agent has **already loaded** (`session/load`, see `adoption.ts`) instead of
-     * opening a new one — the path a reconnect and an adoption both take.
-     *
-     * ### Why this exists at all
-     *
-     * `agentSessions.ts` is handed a `nativeSessionId` on every reconnect, not only on adoption: the
-     * server persists the id and sends it back with `agent_open`. Answering that by opening a fresh
-     * `session/new` and replaying the old session's history as read-only display would throw away the
-     * agent's own context on every reconnect — the deleted Claude Code bridge really did resume, so
-     * that would be a regression, not an equivalent swap.
-     *
-     * ### Why it is hand-built rather than an SDK call
-     *
-     * The SDK offers no way to attach its `ActiveSession` to an already-loaded session: the class has a
-     * private constructor and the only thing that produces one is `SessionBuilder.start()`, which
-     * *is* `session/new` (`@agentclientprotocol/sdk/dist/acp.d.ts`). So the second construction path is
-     * this: the same {@link DrivenSession} surface, assembled from raw requests —
-     * `prompt` → `session/prompt`, `cancel` → the `session/cancel` notification, `nextUpdate` →
-     * {@link AttachedQueue} fed by `updates.listen(...)` plus the prompt's own completion, `dispose` →
-     * unsubscribe and fail the queue. Everything above this line — the read loop, the outbox, the
-     * `agent_message` synthesis, the pending-approval map — is shared verbatim with
-     * {@link AcpSession.open}; only how the four calls reach the agent differs.
-     *
-     * The caller is responsible for having already issued `session/load` for `sessionId` (and, when it
-     * wants that history, for having captured the replay it produced). Call `updates.listen` here
-     * rather than earlier so nothing is dropped in between: `ReplayCapture` withholds updates from a
-     * listener only while the id is armed, and it is disarmed by the `take()` that ends the replay.
-     *
-     * ### `initial.configOptions` is read lazily, not copied at construction
-     *
-     * `AcpAgents.startSession` (Task 3) must construct this session *before* issuing `session/load` —
-     * the session has to be subscribed to the live update stream before the replay begins — so the
-     * snapshot (which only exists once `session/load`'s response arrives, via `adoption.ts`'s
-     * `ReplaySessionParams.onLoaded`) is not there yet at the moment this runs. An eager
-     * `let snapshot = initial.configOptions` at construction time would therefore capture an empty
-     * array forever. `current()` instead re-reads `initial.configOptions` every time, until a real
-     * `setConfigOption` call produces a snapshot of its own — so a caller that populates `initial`
-     * (a mutable object) after construction is still seen.
-     *
-     * ### Opts claude into activity reporting exactly as {@link AcpSession.open} does
-     *
-     * `AcpSession.open` sends `_meta.claudeCode.emitRawSDKMessages` on `session/new` and calls
-     * `connection.bindActivity(...)` right after constructing its session (`:596`, `:631`). This method
-     * used to do neither, permanently losing activity reporting for every reconnect and every
-     * adoption of a claude session, even though `agentInfo.name` still made it report
-     * `reportsActivity: true` on `agent_opened` — see `protocol/agent.ts`'s `reportsActivity` field doc
-     * for how that gap was measured and closed. The `_meta` half is now sent by the caller: this
-     * method does not issue `session/load` itself (see this method's own opening paragraph — the
-     * caller already did, before calling this), but `adoption.ts`'s `replayNativeSession` — the
-     * function that does issue it — sends the exact same opt-in `AcpSession.open` sends, via the same
-     * `newSessionMetaFor` filter, so there is exactly one place that decides which agents opt in. This
-     * method's own half is `bindActivity` below, called unconditionally right after construction, the
-     * same as `open` — a connection whose agent never sends `_claude/sdkMessage` simply never invokes
-     * the sink.
-     */
-    static attach(connection, sessionId, updates, initial) {
-        const agent = connection.connection.agent;
-        const queue = new AttachedQueue();
-        // Counted, not just forwarded: `settleUpdates` below needs a growth signal for this session's
-        // live stream, the way the replay path uses `ReplayCapture.count`.
-        let delivered = 0;
-        const unsubscribe = updates.listen(sessionId, (update) => {
-            delivered += 1;
-            queue.push({ kind: 'session_update', update });
-        });
-        let snapshot = null;
-        const current = () => snapshot ?? initial.configOptions;
-        const driven = {
-            sessionId,
-            async prompt(blocks) {
-                try {
-                    const response = await agent.request(methods.agent.session.prompt, {
-                        sessionId,
-                        prompt: blocks,
-                    });
-                    // The response resolving does NOT mean this turn's own `session/update` notifications have
-                    // been dispatched — the SDK applies a response synchronously off the reader but hands a
-                    // notification to an un-awaited handler chain (see `settleUpdates`, which documents the
-                    // measurement). Without this drain, the `stop` below jumps the queue ahead of deltas the
-                    // reader had already pulled off the wire, and `agent_message`/`TurnResult` land
-                    // mid-message: the server's CoworkEngine closes the item on `agent_message`, so the
-                    // remaining text arrives orphaned, and an `agent_close` racing the early `turn_done` can
-                    // drop it outright (`AttachedQueue.fail` discards what is still buffered).
-                    //
-                    // Not a `settleUpdates` gap the SDK-routed path shares: `ActiveSession` is routed by a
-                    // *static* handler that runs first in the chain, which is why `AcpSession.open` never
-                    // needed this and `attach` does.
-                    await settleUpdates(sessionId, () => delivered);
-                    // Enqueued, not just returned: the read loop — not this caller — is what turns a completed
-                    // turn into a TurnResult, exactly as `ActiveSession.prompt()` does it.
-                    queue.push({ kind: 'stop', stopReason: response.stopReason });
-                    return { stopReason: response.stopReason };
-                }
-                catch (err) {
-                    // Same routing for the failure: `runReadLoop` reads it off the queue and reports a `failed`
-                    // turn. Rethrown as well so the shape matches `ActiveSession.prompt()` — `AcpSession.prompt`
-                    // swallows it with a `.catch(() => {})` precisely because the queue is the real channel.
-                    // Drained first for the same reason the success path is: an agent that streamed some of a
-                    // turn and *then* errored has the identical reordering hazard, and the failed TurnResult
-                    // must not overtake the text that preceded it.
-                    await settleUpdates(sessionId, () => delivered);
-                    queue.pushError(err);
-                    throw err;
-                }
-            },
-            nextUpdate: () => queue.next(),
-            cancel: () => agent.notify(methods.agent.session.cancel, { sessionId }),
-            steer: (blocks, priority) => steerRequest(connection, sessionId, blocks, priority),
-            setConfigOption: setConfigOptionRequest(connection, sessionId, current, (next) => (snapshot = next)),
-            stopAsyncTask: (asyncTaskId) => asyncTaskStopRequest(connection, sessionId, asyncTaskId),
-            dispose: () => {
-                unsubscribe();
-                queue.fail(new Error(`[acp] session ${sessionId} was disposed`));
-            },
-        };
-        const attached = new AcpSession(driven, connection.connection.signal, connection);
-        // Same wiring `AcpSession.open` does right after constructing its session (`:631`) — see this
-        // method's own doc comment ("Opts claude into activity reporting exactly as `AcpSession.open`
-        // does") for why this half was missing and what closes it.
-        connection.bindActivity((raw) => attached.reportActivity(raw));
-        bindDivertedUpdates(connection, sessionId, attached);
-        return attached;
-    }
-    // -------------------------------------------------------------------------------------------
-    // The surface `agentSessions.ts` drives (carried over from the deleted BridgeSession SPI)
-    // -------------------------------------------------------------------------------------------
-    /**
-     * Send one `session/prompt` turn. `blocks` is ACP's own `ContentBlock[]` (see {@link DrivenSession}
-     * for why this class no longer narrows it to a `string`) — a lone text block is what every caller
-     * sends today; an image block is only ever valid here for a session whose agent advertised
-     * `PromptCapabilities.image` (`AcpConnection.capabilities.promptImage`, surfaced to callers as
-     * `AcpAgentSession.supportsImageInput`), and enforcing that is the caller's job, not this method's.
-     */
-    prompt(blocks, platformTurnId) {
-        // Checked ahead of `closed`, and the reason this branch exists at all: a session can outlive its
-        // read loop without anyone having closed it (a dead connection, an unmappable update), and then
-        // nothing but this call is left to end the turn. Registered as a turn and finished on the spot,
-        // rather than reported some other way, so that "one prompt, one terminal result" holds on this
-        // path exactly as it does on the live one — `agentSessions.ts` unblocks `TaskRegistry` and the
-        // server closes the round off `onTurnDone` and nothing else. See {@link readLoopDead}.
-        if (this.readLoopDead !== null) {
-            this.inFlightTurns.push({ interrupted: false, platformTurnId });
-            this.finishTurn('failed', undefined, this.readLoopDead);
-            return;
-        }
-        if (this.closed) {
-            console.warn('[acp] dropping prompt for a session that is no longer running');
-            return;
-        }
-        if (this.exactExecutionUnconfirmed || (this.inFlightTurns.length > 0 && (platformTurnId !== undefined ||
-            this.inFlightTurns.some((turn) => turn.platformTurnId !== undefined)))) {
-            throw new Error('An exact platform turn is still running; overlapping prompts are unavailable');
-        }
-        this.permissionsInterrupted = false;
-        // One turn per prompt, always — see {@link inFlightTurns} for why an overlapping prompt must not
-        // fold into the turn already running.
-        this.inFlightTurns.push({ interrupted: false, platformTurnId });
-        if (platformTurnId !== undefined)
-            this.exactExecutionUnconfirmed = true;
-        // The `.catch(() => {})` is not error handling — `ActiveSession.prompt()` already routes this
-        // same rejection onto the `nextUpdate()` queue internally (see the file doc comment), and
-        // `runReadLoop`'s catch branch is what turns it into a `TurnResult`. It exists only so the
-        // promise this call itself produces is never flagged as an unhandled rejection.
-        this.session.prompt(blocks).catch(() => { });
-    }
-    /**
-     * Inject a message into the turn that is currently running, instead of queueing it behind that
-     * turn as a second `session/prompt` would.
-     *
-     * **Injecting aborts.** The adapter's own comment (`acp-agent.js@0.76.0:1702-1704`): *"Pre-empting
-     * means ABORTING: the interrupted cycle emits a `result` of its own and the steered message runs
-     * as a second one, so the turn is marked (`Turn.steeredEchoes`) to settle at the SDK's `idle`
-     * instead of that result."* From this class's side that is invisible and must stay so: no
-     * {@link inFlightTurns} entry is pushed here, because steering does **not** create a turn — the
-     * one `stop` message still on its way belongs to the prompt that is already registered. Pushing
-     * one would leave a turn that nothing can ever finish.
-     *
-     * The steered message's own output arrives through `session/update` like any other, **not** in
-     * this response (`:1115-1116`), so the only thing a caller learns here is the disposition.
-     *
-     * Callers must have checked {@link AcpConnection.supportsSteering} — this is an extension, and an
-     * agent that never advertised it answers `Method not found`.
-     *
-     * `blocks` carries the **whole** message, images included, for the reason set out on
-     * {@link steerRequest}; `priority` is the delivery timing, `undefined` meaning the caller is
-     * naming none rather than picking one.
-     */
-    async steer(blocks, priority) {
-        if (this.closed)
-            throw new Error('[acp] cannot steer a session that is no longer running');
-        return this.session.steer(blocks, priority);
-    }
-    /**
-     * `session/set_config_option` — or, for the daemon's synthesized {@link SYNTHESIZED_MODES_CONFIG_ID},
-     * `session/set_mode` — and the resulting normalized snapshot; see {@link setConfigOptionRequest}.
-     */
-    async setConfigOption(configId, value) {
-        return this.session.setConfigOption(configId, value);
-    }
-    /**
-     * Stop **one** background task on this session, leaving the running turn alone — the
-     * `_session/async_task/stop` extension; see {@link asyncTaskStopRequest}.
-     *
-     * No {@link inFlightTurns} bookkeeping, for the same reason {@link steer} does none: this does not
-     * create a turn and, unlike {@link interrupt}, it does not end one either. The adapter's own
-     * comment is explicit that the parent prompt turn keeps running.
-     *
-     * Throws on a closed session rather than warning-and-returning the way {@link interrupt} does: a
-     * dropped interrupt still leaves the turn marked interrupted locally, so the caller's picture
-     * stays true, whereas a dropped stop leaves a background task running with the server told
-     * nothing — the exact silence this whole path exists to remove.
-     */
-    async stopAsyncTask(asyncTaskId) {
-        if (this.closed)
-            throw new Error('[acp] cannot stop a background task on a session that is no longer running');
-        return this.session.stopAsyncTask(asyncTaskId);
-    }
-    async providerTaskStop(taskId, requestId) {
-        if (this.closed)
-            throw new Error('[acp] cannot stop a provider task on a closed session');
-        return this.session.providerTaskStop?.(taskId, requestId) ?? Promise.reject(new Error('Provider task stop unavailable'));
-    }
-    /**
-     * Resolve one pending `session/request_permission` round trip. Unknown/already-answered
-     * `requestId`s are silently ignored, matching the deleted Claude Code bridge's `answer()` — a
-     * platform relaying a stale answer must not throw.
-     */
-    answer(requestId, outcome) {
-        this.settleApproval(requestId, outcome, 'answered');
-    }
-    cancelPendingApproval(requestId, outcome) {
-        this.settleApproval(requestId, outcome, 'canceled');
-    }
-    settleApproval(requestId, outcome, reason) {
-        const entry = this.pendingApprovals.get(requestId);
-        if (!entry || entry.connectionGeneration !== this.connectionGeneration)
-            return;
-        this.pendingApprovals.delete(requestId);
-        if (this.settledApprovals.size >= 64)
-            this.callbacksComplete = false;
-        else
-            this.settledApprovals.set(requestId, reason);
-        this.publishCallbacks();
-        entry.resolve(outcome);
-    }
-    /**
-     * Register a pending `session/request_permission` round trip. `permission.ts` calls this from its
-     * `session/request_permission` handler and resolves the registered callback once the user (or
-     * `close()`) answers it; nothing in this file calls it.
-     */
-    registerPendingApproval(requestId, resolve, address) {
-        const origin = address?.originNativeSessionId ?? this.session.sessionId;
-        if (!origin.trim() || (origin !== this.session.sessionId && !this.permissionOrigins.has(origin))) {
-            console.error(JSON.stringify({ component: 'acp', error: 'invalid_permission_origin', origin, rootRuntimeId: this.rootRuntimeId }));
-            resolve(ABANDONED_ANSWER);
-            return;
-        }
-        if (this.closed || this.readLoopDead !== null || this.connectionAborted || this.permissionsInterrupted) {
-            // A permission request that reaches us after our own close() has nobody left to answer it —
-            // review finding (task-5, item 2): registering it anyway would park a card `close()`'s own
-            // drain already ran past, and the agent would wait forever for a response nothing will send.
-            // Resolve immediately with the same abandonment sentinel `close()`'s drain uses, instead of
-            // ever storing the entry.
-            resolve(ABANDONED_ANSWER);
-            return;
-        }
-        if ([requestId, origin, address?.rpcRequestId ?? requestId].some((value) => !value.trim() || Buffer.byteLength(value, 'utf8') > 256 || /[\x00-\x1f\x7f]/.test(value)) ||
-            this.pendingApprovals.size >= 64 || this.pendingApprovals.has(requestId) || this.settledApprovals.has(requestId)) {
-            this.callbacksComplete = false;
-            this.publishCallbacks();
-            resolve(ABANDONED_ANSWER);
-            return;
-        }
-        this.pendingApprovals.set(requestId, {
-            connectionGeneration: this.connectionGeneration, rootRuntimeId: this.rootRuntimeId,
-            originNativeSessionId: origin, rpcRequestId: address?.rpcRequestId ?? requestId, resolve,
-        });
-        this.publishCallbacks();
-    }
-    /**
-     * Resolve one pending `elicitation/create` round trip. Same contract as {@link answer}: an
-     * unknown or already-answered `requestId` is silently ignored, because a stale elicitation answer
-     * for a request that already settled must not throw.
-     */
-    answerElicitation(requestId, response) {
-        const resolve = this.pendingElicitations.get(requestId);
-        if (!resolve)
-            return;
-        this.pendingElicitations.delete(requestId);
-        resolve(response);
-    }
-    /**
-     * Register a pending `elicitation/create` round trip. Same contract as
-     * {@link registerPendingApproval}: once this session is closed, there is nobody left to answer,
-     * so the resolver settles immediately (`{action: 'cancel'}`, ACP's own real cancellation outcome
-     * — unlike a permission option id, there is no collision to guard against here) instead of ever
-     * being stored.
-     */
-    registerPendingElicitation(requestId, resolve) {
-        if (this.closed) {
-            resolve(ABANDONED_ELICITATION_ANSWER);
-            return;
-        }
-        this.pendingElicitations.set(requestId, resolve);
-    }
-    /**
-     * Emit a wire event that did not come from `session/update` — `permission.ts` calls this from its
-     * `session/request_permission` handler to raise the `permission_request` card. Routed
-     * through the same buffered {@link outbox}/{@link drain} pair every mapped `session/update` event
-     * uses, rather than a separate channel, so a permission card lands in the exact same delivery
-     * order relative to other events (and is subject to the same registration-buffering guarantee: an
-     * event emitted before `onEvent` is registered is queued, not lost — see {@link drain}'s doc
-     * comment) instead of racing a second, independent path a consumer would have to merge itself.
-     */
-    emitEvent(event) {
-        this.nativeTerminalRepair?.observe(event);
-        if (this.closed) {
-            // Same reasoning as `registerPendingApproval` above: once closed, nothing is left reading the
-            // outbox on the other end that could still make sense of a fresh card.
-            return;
-        }
-        const payload = { ...event.payload };
-        if (event.eventName === 'permission_request') {
-            delete payload.callbackContext;
-            const callbackContext = this.callbackContextFor(event);
-            if (callbackContext)
-                payload.callbackContext = callbackContext;
-            const call = payload.toolCall;
-            const meta = call && typeof call === 'object' && !Array.isArray(call)
-                ? call._meta : undefined;
-            const sdkCallback = meta && typeof meta === 'object' && !Array.isArray(meta) &&
-                Object.prototype.hasOwnProperty.call(meta, 'qoderSdk');
-            if (sdkCallback && !callbackContext) {
-                if (typeof payload.requestId === 'string')
-                    this.cancelPendingApproval(payload.requestId, ABANDONED_ANSWER);
-                return;
-            }
-        }
-        const normalized = { ...event, payload,
-            ...(event.acpSessionId === this.session.sessionId ? { acpSessionId: undefined } : {}) };
-        for (const mapped of this.subworkBoundary?.map(normalized) ?? [normalized]) {
-            this.observePermissionOrigin(mapped);
-            this.enqueue({ kind: 'event', event: mapped });
-        }
-    }
-    callbackContextFor(event) {
-        if (event.eventName !== 'permission_request' || event.acpSessionId !== this.session.sessionId)
-            return;
-        const diagnostics = this.connection.runtimeDiagnostics;
-        const profile = diagnostics.profile;
-        const callbacks = diagnostics.callbacks;
-        const requestId = event.payload.requestId;
-        const toolCall = event.payload.toolCall;
-        if (!diagnostics.available || profile?.mode !== 'sdk-adapter' || profile.initialized !== true ||
-            profile.rootConfirmed !== true || profile.rootSessionId !== this.session.sessionId ||
-            !profile.runtimeGeneration || callbacks?.complete !== true ||
-            callbacks.rootSessionId !== this.session.sessionId ||
-            typeof requestId !== 'string' || !this.pendingApprovals.has(requestId) ||
-            !toolCall || typeof toolCall !== 'object' || Array.isArray(toolCall))
-            return;
-        const call = toolCall;
-        const sdkMeta = call._meta && typeof call._meta === 'object' && !Array.isArray(call._meta)
-            ? call._meta.qoderSdk : undefined;
-        if (!sdkMeta || typeof sdkMeta !== 'object' || Array.isArray(sdkMeta))
-            return;
-        const sdk = sdkMeta;
-        const origin = sdk.origin;
-        if (sdk.version !== 1 || sdk.blockingScope !== 'root' || sdk.callbackOnly !== true ||
-            typeof sdk.requestId !== 'string' || !/^[0-9a-f-]{36}$/i.test(sdk.requestId) ||
-            !origin || typeof origin !== 'object' || Array.isArray(origin))
-            return;
-        const source = origin;
-        const toolUseId = call.toolCallId;
-        const agentId = source.agentId;
-        if (source.rootSessionId !== this.session.sessionId || source.runtimeGeneration !== profile.runtimeGeneration ||
-            typeof toolUseId !== 'string' || source.toolUseId !== toolUseId ||
-            !toolUseId || Buffer.byteLength(toolUseId, 'utf8') > 256 ||
-            (agentId !== undefined && (typeof agentId !== 'string' || !agentId || Buffer.byteLength(agentId, 'utf8') > 256)))
-            return;
-        const pending = callbacks.pending.find((entry) => entry.requestId === requestId &&
-            entry.originNativeSessionId === this.session.sessionId);
-        if (!pending || callbacks.pending.length > 64 || this.pendingApprovals.get(requestId)?.rpcRequestId !== pending.rpcRequestId)
-            return;
-        return { rootSessionId: this.session.sessionId, hostGeneration: diagnostics.generation,
-            connectionGeneration: callbacks.connectionGeneration, requestId,
-            runtimeGeneration: profile.runtimeGeneration, toolUseId,
-            ...(agentId ? { agentId } : {}), independent: false };
-    }
-    /**
-     * Applies one `session/update` the transport diverted before the SDK could destroy it.
-     *
-     * Two things arrive here and they differ only in addressing (see `draftInterceptor.ts` for the
-     * measurements): a draft variant on **this** session, and any update at all on a **child**
-     * session this client never opened. Both are mapped by the same mapper as everything else — this
-     * is not a second translation path, it is the same one reached by a different door.
-     *
-     * A child's events are tagged with {@link WireEvent.acpSessionId} so the server can route them to
-     * the projected child session; the frame itself still goes out on this session's ref and seq.
-     * They deliberately bypass {@link routeMappedEvent}'s message-boundary tracking: that accumulator
-     * synthesises `agent_message` for **this** session's turn, and feeding a child's chunks into it
-     * would end the parent's message on the child's boundaries.
-     *
-     * Never throws. Its caller is the stream, and an exception there would stall every later message
-     * on the connection, not just this one.
-     */
-    applyDivertedUpdate(diverted) {
-        const isChild = diverted.sessionId !== this.session.sessionId;
-        let events;
-        try {
-            events = mapSessionUpdate(diverted.update, this.mapperFor(diverted.sessionId));
-        }
-        catch (err) {
-            // An unmapped variant is a contract gap worth naming, not worth killing a session over. The
-            // agent, the session and the variant are what make it actionable.
-            console.warn(`[acp] dropped a diverted '${String(diverted.update.sessionUpdate)}' ` +
-                `for session ${diverted.sessionId}: ${err instanceof Error ? err.message : String(err)}`);
-            return;
-        }
-        for (const event of events) {
-            this.emitEvent(isChild ? { ...event, acpSessionId: diverted.sessionId } : event);
-        }
-    }
-    /**
-     * Cancel the current turn via `session/cancel` — a **notification**, not `$/cancel_request`
-     * (that method cancels one in-flight *request*, via `SendRequestOptions.cancellationSignal`, and is
-     * a different mechanism entirely from ending a whole prompt turn). The current turn is marked
-     * interrupted synchronously so the eventual `TurnResult` reports `'interrupted'` no matter what
-     * `stopReason` the agent's `session/prompt` response ends up carrying — including a `stopReason`
-     * that (incorrectly) claims the turn ended normally.
-     */
-    async interrupt() {
-        if (this.closed) {
-            console.warn('[acp] ignoring interrupt for a session that is no longer running');
-            return;
-        }
-        // Every in-flight turn, not just the newest: `session/cancel` cancels the session's prompt
-        // turn(s) wholesale, so a second overlapping turn must not come back reporting 'completed'
-        // after the user pressed Stop.
-        for (const turn of this.inFlightTurns)
-            turn.interrupted = true;
-        this.permissionsInterrupted = true;
-        this.drainPendingApprovals();
-        this.drainPendingElicitations();
-        try {
-            await this.session.cancel();
-        }
-        catch (err) {
-            // Not rethrown: the turn is already marked interrupted above, so it will report
-            // 'interrupted' regardless of whether the agent ever heard the cancel — a failed notify means
-            // the agent may keep working, which is what the warning is for.
-            console.warn(`[acp] session/cancel notification failed: ${errorMessage(err)}`);
-        }
-    }
-    /**
-     * Idempotent: the first call sends `session/cancel`, denies every still-pending permission card,
-     * then disposes the underlying `ActiveSession` (which fails its update queue); the second call just
-     * awaits the same read-loop exit the first one triggered.
-     *
-     * `session/cancel` is sent **before** `dispose()`, deliberately: `ActiveSession.dispose()`'s own
-     * docstring says it does not close the session on the agent side, only local update routing. With
-     * `dispose()` alone, an in-flight prompt keeps the agent running tools and burning tokens until
-     * whatever holds this session's `AcpConnection` eventually kills the child process — harmless only
-     * while there is exactly one connection per session, which ACP does not guarantee in general. The
-     * cancel is wrapped in its own `try`/`catch` so a failed notify cannot skip or mask the
-     * deny-pending/dispose/read-loop shutdown that must happen regardless.
-     */
-    async close() {
-        if (!this.closed) {
-            this.closed = true;
-            this.nativeTerminalRepair?.close();
-            this.drainPendingApprovals();
-            this.drainPendingElicitations();
-            try {
-                await this.session.cancel();
-            }
-            catch (err) {
-                console.warn(`[acp] session/cancel notification failed during close: ${errorMessage(err)}`);
-            }
-            this.session.dispose();
-        }
-        await this.readLoopDone;
-        this.scopes.clear();
-        this.permissionOrigins.clear();
-        this.permissionParents.clear();
-        this.unresolvedPermissionOrigins.clear();
-    }
-    /**
-     * Resolve every still-pending permission request with {@link ABANDONED_ANSWER} and clear the map.
-     * Shared by `close()` (the request-time answer path `permission.ts` reads) and
-     * `runReadLoop`'s connection-abort branch — review finding (task-5, item 5): the child dying or the
-     * connection otherwise aborting out from under a pending permission left it undrained before, since
-     * only `close()` itself drained it and neither the read loop's own abort handling nor a dead
-     * connection ever calls `close()`.
-     */
-    drainPendingApprovals() {
-        const pending = [...this.pendingApprovals.values()];
-        this.pendingApprovals.clear();
-        this.callbacksComplete = false;
-        this.publishCallbacks();
-        for (const entry of pending)
-            entry.resolve(ABANDONED_ANSWER);
-    }
-    /** {@link pendingElicitations}' half of {@link drainPendingApprovals} — same callers, same reason. */
-    drainPendingElicitations() {
-        for (const resolve of this.pendingElicitations.values())
-            resolve(ABANDONED_ELICITATION_ANSWER);
-        this.pendingElicitations.clear();
-    }
-    onEvent(cb) {
-        this.eventSink = cb;
-        this.drain();
-    }
-    onTurnDone(cb) {
-        this.turnSink = cb;
-        this.drain();
-    }
-    /** Registers this session's activity-state consumer. See {@link activitySink}. */
-    onActivity(cb) {
-        this.activitySink = cb;
-    }
-    /**
-     * Feeds one agent-reported activity-state push into this session's sink — the join point for both
-     * collection paths: codex-acp's `session_info_update._meta.codex.threadStatus`, via
-     * {@link scopes}' injected callback, and claude-agent-acp's `_claude/sdkMessage`
-     * extNotification, wired directly onto the connection in `AcpSession.open` (see there for why
-     * that registration cannot live inside `mapSessionUpdate`'s ordinary flow: the notification is not
-     * a `session/update` at all).
-     */
-    reportActivity(raw) {
-        this.activitySink?.(raw);
-    }
-    // `backfill?()` is deliberately not implemented here: replaying an existing native session's
-    // history is `session/load`, which is `adoption.ts`'s job ("领养"), not this file's. Not
-    // `session/resume(replayFrom)`, as the plan text and an earlier version of this comment said —
-    // ACP v1's `session/resume` explicitly does *not* replay history, and `replayFrom` exists only
-    // under the experimental v2 entry point Global Constraint 1 forbids importing. `adoption.ts`'s
-    // "`session/resume` is deliberately NOT used here" section carries the full reading. A session
-    // with no adopted history simply has no `backfill` method, exactly like an unsupported bridge in
-    // the deleted SPI.
-    // -------------------------------------------------------------------------------------------
-    // session/update routing + turn completion
-    // -------------------------------------------------------------------------------------------
-    /**
-     * One continuous consumer of `ActiveSession.nextUpdate()`, for the session's whole lifetime (not
-     * just one turn): `session_update` messages become buffered wire events, `stop` messages finish the
-     * current turn. See the class doc comment for why a single loop is what makes a second
-     * `.onNotification('session/update', …)` registration unnecessary.
-     */
-    async runReadLoop() {
-        for (;;) {
-            let message;
-            try {
-                message = await this.session.nextUpdate();
-            }
-            catch (err) {
-                if (this.closed) {
-                    // Our own close() disposed the ActiveSession, which fails its queue — expected, not an
-                    // error. Every turn still in flight at that moment must still get a terminal result, or
-                    // the manager's onTurnDone would never fire for it. All of them, not just the oldest: the
-                    // queue is permanently failed, so no further stop message is ever coming for the rest.
-                    this.readLoopDead = errorMessage(err);
-                    this.nativeTerminalRepair?.close();
-                    this.finishAllTurns('interrupted', errorMessage(err));
-                    return;
-                }
-                // `ActiveSession.prompt()` routes its own rejection onto this same queue (see the class doc
-                // comment) — this is that one-shot rejection, not a permanently failed queue (only
-                // `dispose()`/connection-close does that), so the loop keeps running for the next prompt.
-                //
-                // **The one exit on this class where the agent itself answered**, and so the only one that
-                // may claim {@link TurnResult.agentRefused} — unless the connection is what died, in which
-                // case this same throw is a dead queue rather than a reply and the branch just below takes
-                // over. `connectionAborted` is read here rather than after `finishTurn` for no reason but
-                // ordering: both reads happen in the same synchronous run, so they see the same value (the
-                // branch below has always depended on that).
-                // `err` itself, not its message: this is the only frame in which the agent's JSON-RPC code
-                // still exists. `errorMessage(err)` on the same line is what destroyed it before.
-                const peerErrorCode = jsonRpcErrorCode(err);
-                this.finishTurn('failed', undefined, errorMessage(err), !this.connectionAborted, peerErrorCode, !this.connectionAborted && peerErrorCode !== undefined);
-                if (this.connectionAborted) {
-                    // The connection died out from under us without our own close() ever running. Same
-                    // reasoning as the `this.closed` branch above: the queue is now permanently failed, so no
-                    // further stop message is ever coming for any turn still behind the one `finishTurn` above
-                    // just popped — review finding (task-11 fix round 1, finding 1): before the FIFO change a
-                    // single `finishTurn` above always cleared the *only* turn, so this branch never had a
-                    // second one left behind to orphan. And every *later* prompt needs the same treatment,
-                    // which is what {@link readLoopDead} gives it — finishing the turns open right now says
-                    // nothing about the retry the user sends ten seconds from now.
-                    this.readLoopDead = errorMessage(err);
-                    this.nativeTerminalRepair?.close();
-                    this.finishAllTurns('failed', errorMessage(err));
-                    // Nothing will drain pendingApprovals otherwise (review finding, task-5 item 5).
-                    this.drainPendingApprovals();
-                    this.drainPendingElicitations();
-                    return; // the connection itself is gone; further reads would just spin
-                }
-                continue;
-            }
-            if (message.kind === 'session_update') {
-                try {
-                    for (const event of mapSessionUpdate(message.update, this.mapperFor(this.session.sessionId)))
-                        this.routeMappedEvent(event);
-                }
-                catch (err) {
-                    // The third permanent-failure exit, and the reason this mapping call is inside a `try` at
-                    // all: nothing thrown under `mapSessionUpdate` may escape `runReadLoop`. An uncaught throw
-                    // here rejects `readLoopDone`, strands every in-flight turn in `inFlightTurns` on a read
-                    // loop that no longer exists, and skips `drainPendingApprovals`, leaving the agent process
-                    // blocked forever on a permission card nobody will answer.
-                    //
-                    // What this branch is *not*: the handler for an unknown `sessionUpdate` variant. An
-                    // earlier version of this comment claimed it was, and a probe disproved it. Both paths
-                    // that feed this loop parse the notification through the SDK's `zSessionNotification`
-                    // first — `SessionUpdateRouter.handleMessage` for `open()`, `registerAppNotification` for
-                    // the `attach()`/replay handler — and `zSessionUpdate` is a closed union of literals. An
-                    // update naming a variant our pinned SDK does not know fails that parse inside the SDK's
-                    // own dispatch, which prints one `Error handling notification` line and carries on;
-                    // `mapSessionUpdate` is never called for it. Measured against a bare ndjson agent emitting
-                    // `{"sessionUpdate":"brand_new_v2_variant"}`: the surrounding deltas and the turn's own
-                    // completion all arrived normally and this branch never ran. (The tests that do run it
-                    // push into `attach`'s `LiveUpdateSource` directly, which is downstream of that parse.)
-                    //
-                    // So the exhaustiveness guard is unreachable in production today, and what actually
-                    // happens to a future agent's new update variant is that **it disappears silently** —
-                    // one SDK console line, and nothing in Axom at all: no wire event, no card, no diagnostic,
-                    // no record that the agent said anything. Nobody on this branch adjudicated that; it is
-                    // written down here because this is where a reader will come looking for it, and the place
-                    // to change it would be the SDK parse boundary, not this catch.
-                    //
-                    // The branch stays regardless: a throw from anywhere under `mapSessionUpdate` still has to
-                    // be contained, and it is treated as permanent rather than skipped because whatever made
-                    // one update unrepresentable is a property of a *kind* of update, so the next one of that
-                    // kind throws again. Same shutdown as the other two permanent-failure exits — finish every
-                    // turn with the shared cause, drain the approvals, stop reading.
-                    console.error(`[acp] unmappable session/update; ending this session's turns: ${errorMessage(err)}`);
-                    this.readLoopDead = errorMessage(err);
-                    this.nativeTerminalRepair?.close();
-                    this.finishAllTurns('failed', errorMessage(err));
-                    this.drainPendingApprovals();
-                    return;
-                }
-            }
-            else {
-                // ACP's own 'cancelled' stopReason additionally forces 'interrupted' even when this session's
-                // own interrupt() was never called (a defensive backstop, not the primary path — see
-                // `finishTurn`'s interrupted-flag handling for that).
-                const status = message.stopReason === 'cancelled' ? 'interrupted' : 'completed';
-                this.finishTurn(status, message.stopReason, undefined, false, undefined, true);
-            }
-        }
-    }
-    /** Host-owned load history restores addresses, never actionable interactions or live events. */
-    observeReplayEvent(event) {
-        this.nativeTerminalRepair?.observe(event);
-        this.observePermissionOrigin(event);
-        this.observeBackgroundWriter(event);
-    }
-    observeBackgroundWriter(event) {
-        const input = event.payload.rawInput;
-        if (input && typeof input === 'object' && !Array.isArray(input) &&
-            input.run_in_background === true) {
-            // An explicitly requested detached writer has no authenticated termination signal here.
-            this.backgroundWriterUnconfirmed = true;
-        }
-        const output = event.payload.rawOutput;
-        if (output && typeof output === 'object' && !Array.isArray(output)) {
-            const evidence = output;
-            if (evidence.backgrounded === true && (typeof evidence.taskId === 'string' || typeof evidence.pid === 'number')) {
-                this.backgroundWriterUnconfirmed = true;
-            }
-        }
-    }
-    /** Connection-local relations grant approval eligibility only after a complete path to our root. */
-    observePermissionOrigin(event) {
-        if (event.eventName !== 'subagent_spawned')
-            return;
-        const parent = event.acpSessionId ?? this.session.sessionId;
-        const child = event.payload.subagentSessionId;
-        const reject = (reason) => console.warn(JSON.stringify({
-            component: 'acp', error: 'invalid_permission_relation', reason,
-            parent, child, rootRuntimeId: this.rootRuntimeId,
-        }));
-        if (typeof parent !== 'string' || !parent.trim() || typeof child !== 'string' || !child.trim()) {
-            reject('invalid_native_id');
-            return;
-        }
-        if (child === parent || child === this.session.sessionId) {
-            reject(child === parent ? 'self_parent' : 'root_reparent');
-            return;
-        }
-        const existing = this.permissionParents.get(child);
-        if (existing !== undefined) {
-            if (existing !== parent)
-                reject('conflicting_parent');
-            return;
-        }
-        // Include unresolved edges: otherwise two untrusted parents could first form a cycle and
-        // become eligible later when one is named by the root. Rejected edges never enter the graph.
-        for (let ancestor = parent; ancestor !== undefined; ancestor = this.permissionParents.get(ancestor)) {
-            if (ancestor === child) {
-                reject('cycle');
-                return;
-            }
-        }
-        const trusted = parent === this.session.sessionId || this.permissionOrigins.has(parent);
-        if (!trusted && this.unresolvedPermissionOrigins.size >= 1024) {
-            reject('unresolved_capacity');
-            return;
-        }
-        this.permissionParents.set(child, parent);
-        if (!trusted) {
-            this.unresolvedPermissionOrigins.add(child);
-            return;
-        }
-        this.permissionOrigins.add(child);
-        // A bounded fixed-point walk handles arbitrarily reversed arrival order, including replay.
-        // Only relation events run it; ordinary event/approval traffic never scans these edges.
-        let promoted;
-        do {
-            promoted = false;
-            for (const candidate of this.unresolvedPermissionOrigins) {
-                if (this.permissionOrigins.has(this.permissionParents.get(candidate))) {
-                    this.unresolvedPermissionOrigins.delete(candidate);
-                    this.permissionOrigins.add(candidate);
-                    promoted = true;
-                }
-            }
-        } while (promoted);
-    }
-    /**
-     * Routes one mapped `WireEvent` to the outbox, tracking `agent_message_chunk`/`agent_thought_chunk`
-     * on the way through so `agent_message` can be synthesized at the right moments — the one per-turn
-     * accumulator this class still owns instead of `sessionUpdateMapper.ts` (see the class doc comment).
-     *
-     * `user_message_chunk` is deliberately *not* special-cased: it goes to the outbox like any other
-     * event, and the server folds it.
-     */
-    routeMappedEvent(event) {
-        if (this.foregroundOutput && !this.foregroundOutput.accept(event))
-            return;
-        this.nativeTerminalRepair?.observe(event);
-        for (const mapped of this.subworkBoundary?.map(event) ?? [event]) {
-            this.observePermissionOrigin(mapped);
-            this.observeBackgroundWriter(mapped);
-            if ((!this.subworkBoundary || !mapped.acpSessionId || mapped.acpSessionId === this.session.sessionId) &&
-                (mapped.eventName === 'agent_message_chunk' || mapped.eventName === 'agent_thought_chunk')) {
-                this.trackMessageBoundary(mapped);
-            }
-            this.enqueue({ kind: 'event', event: mapped });
-        }
-    }
-    /**
-     * Notes that assistant content/thought is streaming, and — if a *different* `messageId` from the
-     * one currently tracked shows up mid-turn — flushes `agent_message` for the message that just
-     * ended before this chunk's own event reaches the outbox. Without this, two assistant messages in
-     * one turn (e.g. around a tool call) would flush together into the server's single delta buffer
-     * the moment they landed within its ~400ms gap window, reading as one run-on message.
-     */
-    trackMessageBoundary(event) {
-        const messageId = stringField(event.payload, 'messageId');
-        if (this.sawMessageContent && messageId !== null && this.currentMessageId !== null && messageId !== this.currentMessageId) {
-            this.flushMessageCompleted();
-        }
-        this.sawMessageContent = true;
-        if (messageId !== null)
-            this.currentMessageId = messageId;
-    }
-    /**
-     * Synthesizes the existing `agent_message` event — see the class doc comment for why this
-     * class, not `sessionUpdateMapper.ts`, is what emits it. A no-op when no content/thought has
-     * streamed since the last flush (a turn with only tool calls, or an already-flushed
-     * mid-turn message boundary), so this is always safe to call unconditionally.
-     */
-    flushMessageCompleted() {
-        if (!this.sawMessageContent)
-            return;
-        this.enqueue({ kind: 'event', event: { eventName: 'agent_message', payload: { messageId: this.currentMessageId ?? 'turn' } } });
-        this.sawMessageContent = false;
-        this.currentMessageId = null;
-    }
-    /**
-     * Terminate every turn still in flight — for the one path (a permanently failed read queue) where
-     * no further stop message can arrive for any of them.
-     *
-     * `error` is the *shared* cause, handed to every turn rather than only to whichever one happened
-     * to be popped first: one dead queue fails N turns for exactly one reason, and `error` is the only
-     * field that carries it (`agentSessions.ts` records `error: r.error ?? null`; the engine's
-     * `ExternalAgentEventApplier.onTurnDone` substitutes a generic "external agent turn failed" when
-     * it is absent). Passing it on the `'interrupted'` call as well keeps every permanent-failure exit
-     * shaped the same; {@link finishTurn} is the single place that decides a result carries it, and it
-     * still attaches `error` to `failed` results only.
-     */
-    finishAllTurns(status, error) {
-        while (this.inFlightTurns.length > 0)
-            this.finishTurn(status, undefined, error);
-    }
-    /**
-     * @param agentRefused whether this failure is the agent's own answer rather than something this
-     * class synthesised for it — see {@link TurnResult.agentRefused}. Defaulted to `false` so that
-     * every existing exit keeps saying "cannot attribute this", and a new one has to opt in.
-     * @param errorCode the JSON-RPC code of that answer, when there was one. Recorded only under
-     * `agentRefused` — the single `if` below is what keeps the code and the attribution from ever
-     * disagreeing, rather than two conditions someone can later edit apart.
-     */
-    finishTurn(status, stopReason, error, agentRefused = false, errorCode, executionEnded = false) {
-        // The oldest unfinished turn, popped: one stop message (or one prompt rejection) ends exactly
-        // one turn, so a second overlapping turn keeps its own result instead of being swallowed.
-        const turn = this.inFlightTurns.shift();
-        if (!turn)
-            return;
-        if (this.inFlightTurns.length === 0)
-            this.foregroundOutput?.endTurn();
-        // Must land before the TurnResult below. Unconditionally safe to call — a no-op when nothing
-        // was accumulated — so every path that can end a turn (a normal stop, an interrupt, a failed
-        // request, or close() mid-turn) goes through exactly this one place rather than each needing to
-        // remember to flush for itself. The user half of this pair is gone: a buffered user message is
-        // now the server's to close, at `CoworkEngine.endBridgeTurn`, which sees the same turn boundary.
-        this.flushMessageCompleted();
-        // A turn this session itself interrupted always reports 'interrupted', regardless of what the
-        // agent's own response claims — mirrors the deleted Claude Code bridge's finishTurn.
-        const resolved = turn.interrupted ? 'interrupted' : status;
-        if (resolved === 'interrupted') {
-            this.permissionsInterrupted = true;
-            this.drainPendingApprovals();
-            this.drainPendingElicitations();
-        }
-        const result = { status: resolved };
-        if (turn.platformTurnId !== undefined)
-            result.platformTurnId = turn.platformTurnId;
-        if (executionEnded && this.inFlightTurns.length === 0 && !this.backgroundWriterUnconfirmed) {
-            result.executionEnded = true;
-            this.exactExecutionUnconfirmed = false;
-        }
-        if (resolved === 'completed' && stopReason && stopReason !== 'cancelled') {
-            result.stopReason = mapStopReason(stopReason);
-        }
-        // Echoed on every finished turn, matching the deleted Claude Code bridge's TurnResult shape —
-        // ACP's session id is known synchronously from session/new and never renames mid-session the way
-        // Claude Code's occasionally does, but a manager built against the old contract may still expect
-        // this field to be populated whenever it is known, not only the first time.
-        if (this.session.sessionId.length > 0)
-            result.nativeSessionId = this.session.sessionId;
-        if (resolved === 'failed' && error)
-            result.error = error;
-        // Gated on `resolved`, not on the requested `status`: a turn this session interrupted reports
-        // 'interrupted' whatever the agent said, and attributing that to the agent would be a claim
-        // about a result it no longer owns.
-        if (resolved === 'failed' && agentRefused) {
-            result.agentRefused = true;
-            if (errorCode !== undefined)
-                result.errorCode = errorCode;
-        }
-        this.enqueue({ kind: 'turn', result });
-    }
-    enqueue(item) {
-        this.outbox.push(item);
-        this.drain();
-    }
-    /**
-     * Deliver from the head of the outbox for as long as the head's sink exists. Buffering
-     * `session/update` output that arrives before `onEvent`/`onTurnDone` are registered — and flushing
-     * it in order once they are — is a contract the deleted `BridgeSession` SPI's KDoc called out
-     * explicitly: events emitted with no sink registered are otherwise silently lost.
-     *
-     * Stopping at the first undeliverable entry (rather than skipping it) preserves relative order
-     * across the two-step registration a manager does (`onEvent` first, `onTurnDone` second, or vice
-     * versa): a turn result queued ahead of some events must still reach its sink before those events
-     * reach theirs, and a single shared queue drained strictly FIFO is what guarantees that.
-     */
-    drain() {
-        if (this.draining)
-            return;
-        this.draining = true;
-        try {
-            while (this.outbox.length > 0) {
-                const head = this.outbox[0];
-                if (head.kind === 'event') {
-                    const sink = this.eventSink;
-                    if (!sink)
-                        return;
-                    this.outbox.shift();
-                    this.deliver(() => sink(head.event));
-                }
-                else {
-                    const sink = this.turnSink;
-                    if (!sink)
-                        return;
-                    this.outbox.shift();
-                    this.deliver(() => sink(head.result));
-                }
-            }
-        }
-        finally {
-            this.draining = false;
-        }
-    }
-    /** A throwing sink is the consumer's bug; it must not abort the drain. */
-    deliver(call) {
-        try {
-            call();
-        }
-        catch (err) {
-            console.error(`[acp] sink threw: ${errorMessage(err)}`);
-        }
-    }
-}