@qodo/sdk 0.13.4 → 2.0.0-next.1

package/dist/client/connection.js

@@ -0,0 +1,2189 @@
+/**
+ * `Connection` — owns the WebSocket, multiplexes inbound envelopes onto
+ * subscriptions, encodes outbound envelopes.
+ *
+ * One `Connection` per `QodoClient.connect()` call. `tasks.start` /
+ * `tasks.continue` register a `TaskSubscription`; `client.receive()` registers
+ * a raw subscription that taps every inbound envelope. The connection routes
+ * inbound envelopes to subscriptions whose `parent_message_id` chain matches.
+ *
+ * **Reconnect + replay.** The Connection survives transport drops:
+ * subscriptions stay alive while the underlying `WSTransport` is replaced via
+ * the same factory. On a fresh transport, every active task subscription's
+ * `task_id` + `lastSeenMessageId` is sent back to the server as a
+ * `task.resubscribe` envelope; the server replays anything after that anchor
+ * from its per-session ring buffer (cap 1000 envelopes per session). No
+ * client-side outbox — durability is server-side. The 1.x `OutboxTurn` /
+ * `Resume` / `ResumeAck` machinery does not exist here.
+ */
+import { AsyncQueue } from './iterator.js';
+import { QodoBackpressureError, QodoColdAddressError } from './errors.js';
+import { GEN_AI_CONVERSATION_ID, QAR_SESSION_ID, QAR_TASK_ID, } from '../observability/attributes.js';
+import { asMessageId, asSessionId, uuidv7 } from './uuid.js';
+/**
+ * A single task's inbound stream. Routes by parent-message chain: every
+ * envelope whose `parent_message_id` is in the chain becomes part of the chain
+ * (its `message_id` joins). Terminal envelopes (`task.done`, `error`) close the
+ * iterator.
+ *
+ * On `Connection`-level reconnect, the matching subscription stays alive and
+ * the `Connection` stitches the resubscribe envelope's id into `chain` so the
+ * server's replayed envelopes route back here transparently.
+ */
+export class TaskSubscription {
+    rootMessageId;
+    onEarlyReturn;
+    onClose;
+    metrics;
+    queue = new AsyncQueue();
+    chain = new Set();
+    /**
+     * Lineage-ownership set — message_ids this subscription OWNS, used to
+     * attribute an inbound `tool.request` to the turn that produced it (so the
+     * SDK's `qar.client.tool.handler` span runs in the right task context).
+     *
+     * Distinct from {@link chain}, which is the broader ROUTING set: `chain`
+     * also accepts envelopes via the `task_id` fallback (a passive same-task
+     * subscription — e.g. an auto-paused prior `tasks.start` sub — absorbs
+     * another turn's stream that way for observation + replay continuity).
+     * `ownedMessages` grows ONLY through real `parent_message_id` lineage: this
+     * subscription's own outbound root(s), plus every inbound envelope whose
+     * parent it ALREADY owns. It never grows via the `task_id` fallback.
+     *
+     * Invariant (by construction): every message is owned by EXACTLY ONE
+     * subscription. Roots are unique per outbound request; a child is owned by
+     * its parent's unique owner. So a `tool.request` — which carries no
+     * `task_id` and links only by `parent_message_id` — has a unique owner: the
+     * subscription whose `ownedMessages` contains its parent. This is why a
+     * passive same-task absorber, which holds the other turn's deltas in `chain`
+     * but never in `ownedMessages` (their parent is a root it doesn't own),
+     * never wins ownership of that turn's tool calls — at any depth.
+     */
+    ownedMessages = new Set();
+    taskId;
+    /**
+     * `message_id` of the most recent inbound envelope that matched this
+     * subscription's chain or `task_id`. Anchor for `task.resubscribe` on
+     * reconnect — the server replays everything after this point. Stays
+     * `undefined` until the first inbound envelope arrives. Connection-scoped
+     * envelopes (`flow.pause` / `flow.resume`) don't update it: they're
+     * session-scoped, not task-scoped, so they can't anchor a per-task replay
+     * window.
+     */
+    lastSeen;
+    /**
+     * Outbound `task.resubscribe` message ids whose direct descendant marks
+     * the start of replay accounting for this subscription. Seeded by
+     * {@link attachOutboundMessageId} (auto-reconnect) and the constructor's
+     * `rootIsReplayAnchor` flag (manual `tasks.resubscribe`). Stays small —
+     * one entry per resubscribe envelope this subscription owns, not one
+     * entry per replay envelope received.
+     */
+    replayAnchors = new Set();
+    /**
+     * Once an envelope absorbed by this subscription has been identified as
+     * a replay descendant (its `parent_message_id` was in `replayAnchors`),
+     * every subsequently-absorbed envelope is also counted as a replay
+     * envelope: QAR's per-session ring buffer replays a contiguous chain
+     * after the anchor, so the post-anchor continuation is logically the
+     * same wire window as the replay itself.
+     *
+     * Sticky boolean rather than a growing chain Set — cheaper memory
+     * profile for long-running subscriptions that survive many reconnects.
+     */
+    replayCountingActive = false;
+    /**
+     * @param rootMessageId  message_id of the outbound envelope that started the
+     *                       task (the `task.start` or `task.continue`).
+     * @param knownTaskId    task_id known up front (only for `tasks.continue` /
+     *                       `tasks.cancel` / `tasks.resubscribe` — `tasks.start`
+     *                       doesn't know the id until the first inbound envelope
+     *                       reveals it). Pre-seeding the matcher closes a
+     *                       routing gap where envelopes that carry
+     *                       `payload.task_id` but no chain link to our outbound
+     *                       message would otherwise be missed.
+     * @param onEarlyReturn  called once if the consumer breaks the iterator
+     *                       before terminal — best-effort `task.cancel`. Pass a
+     *                       no-op for resubscribe-style subscriptions where
+     *                       breaking the loop must NOT cancel the underlying
+     *                       task (the consumer is observing, not driving).
+     * @param onClose        called once when the subscription is no longer
+     *                       routable (terminal received OR consumer broke).
+     */
+    /** Span lifecycle for the task this subscription represents. Closed on terminal/fail/early-return. */
+    span;
+    /**
+     * Resolver for the `task.started` admission ack. Receives both the
+     * inherited `session_id` (server-derived UUID) AND the canonical
+     * `task_id` from the envelope's payload — the two ids are distinct on
+     * the admission-retry path, where a retried `task.start` carries a
+     * fresh `message_id` while the server's canonical task_id stays bound
+     * to the FIRST winning attempt.
+     *
+     * Provided by `TaskClient.subscribeAndSend` for `task.start`
+     * subscriptions only — `task.continue` / `task.cancel` /
+     * `task.resubscribe` already know the session_id + task_id from a
+     * prior admission and don't wire a resolver. `null` once the resolver
+     * has fired (resolved OR rejected) — prevents a second resolution
+     * from a spec-violating duplicate ack.
+     */
+    taskStartedResolver = null;
+    /**
+     * Resolver for the `task.force_resumed` ack — fires when the SDK's
+     * outbound `task.forceResume` envelope's response arrives. Wired by
+     * `TaskClient.forceResume`. Mirrors {@link taskStartedResolver} in
+     * shape and lifecycle (null after fire; rejected if the subscription
+     * closes before the ack lands).
+     */
+    taskForceResumedResolver = null;
+    constructor(rootMessageId, knownTaskId, onEarlyReturn, onClose, span, 
+    /**
+     * Optional transport-counter store. When provided, `consider` increments
+     * `replay_envelopes_received_total` for every absorbed envelope that
+     * descends from a replay anchor, and `replay_anchor_missing_total` for
+     * every `error { code: 'replay_anchor_missing' }` envelope that routes
+     * here.
+     */
+    metrics, 
+    /**
+     * `true` when `rootMessageId` is itself a `task.resubscribe` envelope —
+     * its descendants count as replay envelopes for
+     * `replay_envelopes_received_total`. Set by the manual
+     * `client.tasks.resubscribe(...)` seam; the `tasks.start` /
+     * `tasks.continue` paths leave it `false` so live envelopes don't
+     * masquerade as replay until an auto-replay anchor is stitched in via
+     * {@link attachOutboundMessageId}.
+     */
+    rootIsReplayAnchor = false, 
+    /**
+     * Optional resolver fired with the server-derived `session_id` when
+     * the `task.started` admission ack arrives on this subscription's
+     * chain. Wired by `task.start` paths so the caller's `TaskStartIterable`
+     * can expose the derived id via its `sessionId` Promise.
+     *
+     * Resolver lifecycle:
+     *   - Resolved on inbound `task.started` whose `parent_message_id`
+     *     matches the outbound `task.start.message_id`.
+     *   - Rejected if the subscription terminates (clean close, transport
+     *     fail, terminal `task.done` / `error`) before any `task.started`
+     *     arrives — keeps the consumer's `await stream.sessionId` from
+     *     hanging forever.
+     */
+    taskStartedResolver, 
+    /**
+     * Optional resolver fired with the recovered task's id +
+     * post-recovery state when an inbound `task.force_resumed` ack
+     * arrives on this subscription's chain. Wired by
+     * `TaskClient.forceResume`. Same lifecycle as
+     * {@link taskStartedResolver}: rejected on close/error before
+     * the ack lands.
+     */
+    taskForceResumedResolver) {
+        this.rootMessageId = rootMessageId;
+        this.onEarlyReturn = onEarlyReturn;
+        this.onClose = onClose;
+        this.metrics = metrics;
+        this.chain.add(rootMessageId);
+        // The outbound root is the origin of this subscription's lineage — it
+        // owns it. Every inbound envelope whose parent chain leads back here
+        // (via real `parent_message_id` links) is owned by this subscription.
+        this.ownedMessages.add(rootMessageId);
+        if (rootIsReplayAnchor) {
+            this.replayAnchors.add(rootMessageId);
+        }
+        this.taskId = knownTaskId;
+        this.span = span;
+        if (taskStartedResolver !== undefined) {
+            this.taskStartedResolver = taskStartedResolver;
+        }
+        if (taskForceResumedResolver !== undefined) {
+            this.taskForceResumedResolver = taskForceResumedResolver;
+        }
+        // Stamp `qar.task_id` eagerly when we know the id at construction.
+        // For `task.start` subscriptions the SDK derives `task_id` from the
+        // outbound `task.start.message_id`; for `task.continue` /
+        // `task.cancel` / `task.resubscribe` the caller supplies it. The
+        // lazy stamp inside `consider` stays as defense-in-depth for any
+        // callsite that constructs without an id.
+        if (knownTaskId !== undefined && span !== undefined) {
+            span.setAttribute(QAR_TASK_ID, knownTaskId);
+        }
+    }
+    /** The `task_id` once we've seen the first envelope that carries it. */
+    get currentTaskId() {
+        return this.taskId;
+    }
+    /**
+     * Most-recent inbound envelope's `message_id`, or `undefined` if no inbound
+     * matched yet. Public so `Connection.replayActiveTasks` can read it without
+     * pinning to a specific subscription class.
+     */
+    get lastSeenMessageId() {
+        return this.lastSeen;
+    }
+    /** Whether this subscription has terminated and stopped accepting envelopes. */
+    get isTerminated() {
+        return this.queue.isClosed;
+    }
+    /**
+     * Stitch a new outbound `message_id` (typically a `task.resubscribe`) into
+     * this subscription's chain so the server's replies routed via
+     * `parent_message_id` link back here. Idempotent — Set.add no-ops on dups.
+     *
+     * Called by `Connection` after sending a resubscribe on behalf of an
+     * already-live subscription (the auto-replay path on reconnect).
+     */
+    attachOutboundMessageId(messageId) {
+        this.chain.add(messageId);
+        // A `task.resubscribe` we sent is also a real lineage origin for the
+        // envelopes the server replays in response — own it so those descendants
+        // resolve their tool-call context to this subscription.
+        this.ownedMessages.add(messageId);
+        // The only caller is `Connection.replayActiveTasks`, which stitches a
+        // `task.resubscribe` envelope's id in. Seed `replayAnchors` so the
+        // next absorbed descendant flips `replayCountingActive` on and starts
+        // counting toward `replay_envelopes_received_total`.
+        this.replayAnchors.add(messageId);
+    }
+    consider(env) {
+        // Connection-scoped flow events: broadcast to every active task
+        // iterator regardless of message-id chain — QAR emits these once per
+        // connection state change, and consumers expect them on the same iterator
+        // they're already reading. They never claim the envelope, so raw taps and
+        // peer subscriptions still see them. They DON'T update `lastSeen` —
+        // they're session-scoped, not task-scoped, so they can't anchor a
+        // per-task replay window.
+        if (env.kind === 'flow.pause' || env.kind === 'flow.resume') {
+            this.queue.push(env);
+            return false;
+        }
+        if (!this.matches(env))
+            return false;
+        // Did this envelope reach us as a direct reply to one of our own
+        // outbound messages (chain), or only because its payload `task_id`
+        // equals ours (fallback)? Captured BEFORE `chain.add` below stitches
+        // this envelope's own `message_id` in. The admission / recovery ack
+        // branches gate their self-close on this: an ack that matched only via
+        // the `task_id` fallback belongs to a different request and must not
+        // close THIS subscription.
+        const matchedByChain = this.matchesByChain(env);
+        // Replay-counter accounting. Two states:
+        //   - `replayCountingActive` already true → count this envelope (the
+        //     post-anchor continuation is part of the same wire window).
+        //   - `replayCountingActive` false but env's `parent_message_id` is in
+        //     `replayAnchors` → first replay descendant; flip the flag and
+        //     count this envelope.
+        // Sticky-boolean replaces the prior growing replay-chain Set so memory
+        // stays bounded over long-lived subscriptions.
+        if (this.metrics !== undefined) {
+            if (this.replayCountingActive) {
+                this.metrics.recordReplayEnvelopeReceived();
+            }
+            else {
+                const parent = env.parent_message_id;
+                if (parent !== undefined &&
+                    parent !== null &&
+                    this.replayAnchors.has(parent)) {
+                    this.replayCountingActive = true;
+                    this.metrics.recordReplayEnvelopeReceived();
+                }
+            }
+        }
+        this.chain.add(env.message_id);
+        // Lineage ownership: this envelope belongs to THIS subscription's turn iff
+        // we already own its parent (a real `parent_message_id` link back to our
+        // outbound root). A `task_id`-fallback match (e.g. a passive same-task sub
+        // absorbing another turn's stream) is routed into `chain` above but is
+        // NEVER an ownership link — its parent is a root we don't own — so the
+        // ownership set stays exact and the unique-owner invariant holds at any
+        // depth. See {@link ownedMessages}.
+        const parentId = env.parent_message_id;
+        if (parentId !== undefined && parentId !== null && this.ownedMessages.has(parentId)) {
+            this.ownedMessages.add(env.message_id);
+        }
+        this.lastSeen = env.message_id;
+        if (this.taskId === undefined && envelopeHasTaskId(env)) {
+            this.taskId = env.payload.task_id;
+            // Stamp `qar.task_id` on the span lazily — `tasks.start`'s span doesn't
+            // know the id at open time (the server allocates it server-side and
+            // reports it on the first inbound envelope).
+            if (this.span !== undefined) {
+                this.span.setAttribute(QAR_TASK_ID, this.taskId);
+            }
+        }
+        // Capture the server-derived `session_id` from the `task.started`
+        // admission ack and resolve the caller-facing `sessionId` Promise.
+        // The envelope is NOT yielded on the public `TaskEvent` iterator —
+        // it's the start ack, not a content event. Per the wire contract
+        // the kind is server-emitted exactly once per successful admission,
+        // before any `task.delta`; routing only matters when this
+        // subscription owns the matching outbound `task.start` (so
+        // `taskStartedResolver` was wired).
+        if (env.kind === 'task.started') {
+            if (!matchedByChain) {
+                // This `task.started` reached us only via the `task_id` fallback —
+                // it is NOT the reply to this subscription's own outbound
+                // `task.start`. Two ways that happens, both relying on the chain
+                // seeding above:
+                //   - a sibling's idempotent re-admission ack
+                //     (`task.started { is_new: false }`) on an already-dispatched
+                //     session, which carries this task's canonical id; and
+                //   - a cold `task.resubscribe` replaying the ORIGINAL `task.started`
+                //     (foreign parent) from the per-session ring buffer.
+                // Absorb it — the `chain.add` above already seeded the chain so the
+                // chain-only replayed events that follow (tool.request /
+                // state.update / agent.spawn / bulletin.post / artifact.add) still
+                // route here — but do NOT resolve admission or self-close. Resolving
+                // or closing on a foreign ack is exactly what silently collapsed an
+                // unrelated in-flight consumer stream.
+                return true;
+            }
+            // The per-Task `session_id` is captured by
+            // {@link Connection.dispatch} into `taskSessions[task_id]` (the
+            // authoritative lookup map for outbound encoding). Holding a
+            // per-subscription copy would be dead state — encoding paths
+            // address by `task_id`, not by subscription identity.
+            //
+            // Admission_in_progress retry path: the SDK opens each
+            // `task.start` attempt with `knownTaskId = asTaskId(rootMessageId)`
+            // (the ATTEMPT id), but the server's canonical `task_id` on
+            // `task.started.payload.task_id` may differ — on a deterministic-key
+            // retry the SDK rotates `message_id` per attempt while the
+            // server-canonical task_id stays bound to the winning admission.
+            // Overwrite `this.taskId` with the CANONICAL value so that
+            // subsequent outbound envelopes (`task.cancel` from iterator
+            // early-return, `task.resubscribe` on auto-reconnect) address the
+            // task by the id `Connection.taskSessions` is keyed on. Without
+            // overwrite, post-ack ongoing emits would miss the session map
+            // and raise `QodoColdAddressError` despite admission being fully
+            // complete.
+            //
+            // Idempotent-admission fields: forward-compat — old QAR builds
+            // omit them; the SDK treats the absence as `is_new: true` (the
+            // pre-idempotent-admission default) and leaves `state` /
+            // `previousTaskId` / `previousState` undefined so the typed
+            // admission result's `isNew === true` branch is selected.
+            const payload = env.payload;
+            const canonicalTaskId = payload.task_id;
+            this.taskId = canonicalTaskId;
+            if (this.span !== undefined) {
+                // Stamp the server-derived `session_id` AND re-stamp the canonical
+                // `task_id` onto the open span. Pre-admission the span carries the
+                // attempt id (or none); post-admission both attributes reflect the
+                // canonical values QAR will report on every downstream envelope.
+                this.span.setAttribute(QAR_SESSION_ID, env.session_id);
+                this.span.setAttribute(GEN_AI_CONVERSATION_ID, env.session_id);
+                this.span.setAttribute(QAR_TASK_ID, canonicalTaskId);
+            }
+            // Default `is_new` to `true` when the field is absent (forward-compat
+            // with older QAR builds). `is_new === false` indicates an idempotent
+            // existing-session return — no further envelopes will flow on this
+            // subscription's chain (the existing session's events route on the
+            // chain that opened it). Auto-close after the ack so iterators don't
+            // hang waiting for events that will never arrive.
+            const isNew = payload.is_new ?? true;
+            if (this.taskStartedResolver !== null) {
+                const resolver = this.taskStartedResolver;
+                this.taskStartedResolver = null;
+                resolver.resolve({
+                    sessionId: env.session_id,
+                    taskId: canonicalTaskId,
+                    isNew,
+                    ...(payload.state !== undefined ? { state: payload.state } : {}),
+                    ...(payload.previous_task_id !== undefined
+                        ? { previousTaskId: payload.previous_task_id }
+                        : {}),
+                    ...(payload.previous_state !== undefined
+                        ? { previousState: payload.previous_state }
+                        : {}),
+                });
+            }
+            if (!isNew) {
+                // Idempotent return — close the subscription without firing
+                // `onEarlyReturn` (which would emit a spurious `task.cancel`
+                // against the existing session). Use `close()` rather than
+                // manual `queue.close()` + `onClose(this)` so the span's
+                // `succeed()` fires too — `onClose` is wired to
+                // `connection.unsubscribe` and DOES NOT end spans, so a
+                // manual teardown leaks open spans on every idempotent
+                // admission. Same safe-shutdown shape as `disconnect()` and
+                // consumer-return paths.
+                this.close();
+            }
+            return true;
+        }
+        if (env.kind === 'task.force_resumed') {
+            if (!matchedByChain) {
+                // Same rationale as `task.started`: a `task.force_resumed` that
+                // matched only via the `task_id` fallback is NOT this subscription's
+                // own recovery ack (the forceResume one-shot matches its ack by chain
+                // through the outbound `task.forceResume.message_id`). Absorb for
+                // chain continuity; never one-shot-close on a foreign ack — that
+                // would collapse an unrelated in-flight stream bound to the same
+                // task.
+                return true;
+            }
+            // `task.forceResume` ack — surface the recovered task's id +
+            // post-recovery state to `TaskClient.forceResume`. This is the
+            // one-shot terminal for the forceResume subscription; close the
+            // queue so the iterator (consumed only by SDK-internal wait
+            // logic) drains.
+            const payload = env.payload;
+            const recoveredTaskId = payload.task_id;
+            this.taskId = recoveredTaskId;
+            if (this.span !== undefined) {
+                this.span.setAttribute(QAR_SESSION_ID, env.session_id);
+                this.span.setAttribute(GEN_AI_CONVERSATION_ID, env.session_id);
+                this.span.setAttribute(QAR_TASK_ID, recoveredTaskId);
+            }
+            if (this.taskForceResumedResolver !== null) {
+                const resolver = this.taskForceResumedResolver;
+                this.taskForceResumedResolver = null;
+                resolver.resolve({
+                    sessionId: env.session_id,
+                    taskId: recoveredTaskId,
+                    state: payload.state,
+                });
+            }
+            // forceResume is one-shot — close the subscription after the
+            // ack. Use `close()` (not manual `queue.close()` + `onClose`) so
+            // the span's `succeed()` fires; `onClose` only unregisters and
+            // does not end spans.
+            this.close();
+            return true;
+        }
+        if (isTaskEvent(env)) {
+            this.queue.push(env);
+        }
+        if (env.kind === 'task.done') {
+            const status = env.payload.status;
+            const error = env.payload.error;
+            this.endSpanForDone(status, error);
+            // Terminal without admission ack ⇒ reject the sessionId promise
+            // so `await stream.sessionId` doesn't hang. The wire contract says
+            // `task.done` cannot land before `task.started` on a successfully
+            // admitted task; reaching here with a live resolver means the run
+            // ended without admission (test fixtures, transport-injected
+            // terminals) and the caller deserves a typed rejection.
+            this.rejectTaskStartedIfPending(new Error(`task ended before task.started ack arrived (status=${status})`));
+            this.rejectTaskForceResumedIfPending(new Error(`task ended before task.force_resumed ack arrived (status=${status})`));
+            this.queue.close();
+            this.onClose(this);
+        }
+        else if (env.kind === 'error') {
+            const code = env.payload.code;
+            const message = env.payload.message;
+            if (code === 'replay_anchor_missing') {
+                this.metrics?.recordReplayAnchorMissing();
+            }
+            // `span.fail()` records the exception + sets ERROR status; the wire
+            // `error.code` is captured in the exception message. We deliberately
+            // don't `setAttribute(QAR_*, code)` here — error envelopes are wire
+            // transport-level, not tool-level, and their span semantics belong
+            // to the recorded exception, not a custom attribute key.
+            this.span?.fail(new Error(`server error: ${code}${message !== undefined ? `: ${message}` : ''}`));
+            // Pre-admission failure (e.g. `admission_stalled`, invalid
+            // `idempotency_key`, deps build) closes the subscription before
+            // any `task.started` lands — reject the sessionId promise so the
+            // caller's `await stream.sessionId` surfaces the failure rather
+            // than hanging. The same error envelope still flows through the
+            // event iterator (or the wrap-server-errors layer in TaskClient
+            // for typed-code routes) so the rejection here is additive, not a
+            // replacement.
+            //
+            // EXCEPTION: `admission_in_progress` is retryable. The retry
+            // wrapper at the TaskClient layer dispatches a fresh subscription
+            // that may still resolve the deferred — keep the promise pending
+            // so the eventual `task.started` (on a successful retry) lands
+            // cleanly. The current per-attempt subscription is still closed
+            // (the error envelope is its terminal); only the
+            // promise-rejection step is skipped.
+            if (code !== 'admission_in_progress') {
+                this.rejectTaskStartedIfPending(new Error(`server error before task.started: ${code}${message !== undefined ? `: ${message}` : ''}`));
+                this.rejectTaskForceResumedIfPending(new Error(`server error before task.force_resumed: ${code}${message !== undefined ? `: ${message}` : ''}`));
+            }
+            this.queue.close();
+            this.onClose(this);
+        }
+        return true;
+    }
+    /**
+     * Reject the pending `task.started` resolver, if any. No-op when the
+     * resolver has already fired (resolved earlier on the ack, or rejected
+     * by a prior terminal). Idempotent — every terminal path can call
+     * this without guarding.
+     */
+    rejectTaskStartedIfPending(err) {
+        if (this.taskStartedResolver === null)
+            return;
+        const resolver = this.taskStartedResolver;
+        this.taskStartedResolver = null;
+        resolver.reject(err);
+    }
+    /**
+     * Reject the pending `task.force_resumed` resolver, if any. Mirrors
+     * {@link rejectTaskStartedIfPending}: idempotent; called from every
+     * terminal path so `tasks.forceResume()` Promises don't hang on
+     * close / transport failure.
+     */
+    rejectTaskForceResumedIfPending(err) {
+        if (this.taskForceResumedResolver === null)
+            return;
+        const resolver = this.taskForceResumedResolver;
+        this.taskForceResumedResolver = null;
+        resolver.reject(err);
+    }
+    /**
+     * End the task span for a `task.done` envelope. `completed` and `canceled`
+     * are both clean terminal states (the consumer asked for the cancel, or the
+     * task ran to completion); `failed` records an error.
+     */
+    endSpanForDone(status, error) {
+        if (this.span === undefined)
+            return;
+        if (status === 'failed') {
+            this.span.fail(new Error(error ?? 'task failed'));
+            return;
+        }
+        this.span.succeed();
+    }
+    considerClient(ev) {
+        if (this.queue.isClosed)
+            return;
+        this.queue.push(ev);
+    }
+    fail(err) {
+        this.span?.fail(err);
+        // Transport failure before admission ack ⇒ surface to anyone
+        // awaiting `TaskStartIterable.sessionId` rather than letting them hang.
+        this.rejectTaskStartedIfPending(err);
+        this.rejectTaskForceResumedIfPending(err);
+        this.queue.fail(err);
+        this.onClose(this);
+    }
+    close() {
+        // Clean-close path used by `disconnect()` and consumer `.return()` —
+        // neither is an error from the SDK's perspective (the consumer asked or
+        // the connection is shutting down). `succeed()` is idempotent if the
+        // span already ended via `task.done` arriving first.
+        this.span?.succeed();
+        // Same lifecycle rejection as `fail()` — a clean close before
+        // `task.started` means the consumer never got the admission ack.
+        this.rejectTaskStartedIfPending(new Error('subscription closed before task.started ack arrived'));
+        this.rejectTaskForceResumedIfPending(new Error('subscription closed before task.force_resumed ack arrived'));
+        this.queue.close();
+        this.onClose(this);
+    }
+    next() {
+        // Run the queue read under the SDK span's OTel context so the consumer's
+        // `for await` continuation resumes with the SDK span active. This is
+        // what lets a consumer call `client.tools.respond(...)` from inside the
+        // loop body and have *that* span parent under our task span (and have
+        // its outbound `traceparent` reference our task span's id). Without
+        // this wrap, `getActiveSpan()` at await-resume time falls back to
+        // whatever was active when the consumer originally `for await`-ed,
+        // breaking the cross-call trace tree.
+        if (this.span !== undefined) {
+            return this.span.withContext(() => this.queue.next());
+        }
+        return this.queue.next();
+    }
+    async return() {
+        if (!this.queue.isClosed) {
+            this.onEarlyReturn(this.taskId);
+            // Iterator early-termination is consumer intent, not a failure. The
+            // SDK best-effort sends `task.cancel` (via `onEarlyReturn`); the span
+            // ends with `OK` so traces don't surface canceled tasks as errors.
+            this.span?.succeed();
+            this.queue.close();
+            this.onClose(this);
+        }
+        return { value: undefined, done: true };
+    }
+    async throw(err) {
+        if (!this.queue.isClosed) {
+            this.span?.fail(err);
+            this.queue.close();
+            this.onClose(this);
+        }
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    matches(env) {
+        if (this.matchesByChain(env)) {
+            return true;
+        }
+        if (this.taskId !== undefined && envelopeHasTaskId(env)) {
+            const payloadTaskId = env.payload.task_id;
+            if (payloadTaskId === this.taskId)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Whether `env`'s `parent_message_id` links into this subscription's chain
+     * — i.e. the envelope is a direct reply to an outbound message this
+     * subscription owns (`task.start` / `task.continue` / `task.resubscribe`,
+     * or a prior inbound that already joined the chain).
+     *
+     * Distinct from the broader {@link matches}, which also accepts an envelope
+     * solely because its payload `task_id` equals ours. The admission /
+     * recovery acks (`task.started`, `task.force_resumed`) use THIS predicate —
+     * not the `task_id` fallback — to decide whether to resolve admission or
+     * self-close: those acks carry the canonical `task_id`, which on an
+     * idempotent re-admission (a second `task.start` on an already-dispatched
+     * session) or a buffer replay equals the id of a DIFFERENT subscription
+     * whose task is still streaming. A `task_id`-only match must still absorb
+     * the ack (so a cold resubscribe's replayed `task.started` seeds the chain
+     * for the chain-only events that follow), but must NOT drive that other
+     * subscription's admission/close — see {@link consider}.
+     */
+    matchesByChain(env) {
+        return (env.parent_message_id !== undefined &&
+            env.parent_message_id !== null &&
+            this.chain.has(env.parent_message_id));
+    }
+    /**
+     * Whether this subscription OWNS `env`'s turn — i.e. its `parent_message_id`
+     * is in {@link ownedMessages} (a real lineage link back to our outbound
+     * root, never a `task_id`-fallback absorb). Used by
+     * {@link Connection.runInOwningTaskContext} to attribute an inbound
+     * `tool.request` to the turn that produced it: the owner is unique (each
+     * message is owned by exactly one subscription), so this is unambiguous even
+     * when multiple same-task subscriptions overlap (e.g. a live auto-paused
+     * prior `tasks.start` sub alongside an active `tasks.continue`). A passive
+     * absorber holds the other turn's stream in {@link chain} but never in
+     * {@link ownedMessages}, so it never wins ownership — at any depth.
+     */
+    ownsLineage(env) {
+        return (env.parent_message_id !== undefined &&
+            env.parent_message_id !== null &&
+            this.ownedMessages.has(env.parent_message_id));
+    }
+    /**
+     * Public alias for `matches` — exposed so `Connection.dispatchCancelAcked`
+     * can route a `task.canceling` envelope to the correct subscription
+     * before broadcasting the synthetic `qar.client.cancel_acked` client
+     * event. Same chain + `task_id` matcher used for normal envelope
+     * routing.
+     */
+    matchesEnvelope(env) {
+        return this.matches(env);
+    }
+    /**
+     * Run `fn` inside this subscription's task span context. When the
+     * subscription has no span (no OTel provider configured, or a call site
+     * that didn't supply a span builder), runs `fn` directly — a strict
+     * pass-through.
+     *
+     * Used by {@link Connection.runInOwningTaskContext} to re-attach the
+     * originating task's context around an inbound `tool.request` handler
+     * dispatch, so the handler's `qar.client.tool.handler` span (and any
+     * outbound work it triggers) parents under the task span rather than the
+     * bare WS-receive context.
+     */
+    runInTaskContext(fn) {
+        return this.span !== undefined ? this.span.withContext(fn) : fn();
+    }
+}
+/**
+ * Raw subscription from `client.receive()` — taps every inbound envelope plus
+ * the synthetic `qar.client.*` lifecycle events. The yielded type is
+ * `Envelope | ClientEvent`; consumers narrow on `kind` (the QAR `kind`
+ * discriminator stays disjoint from `qar.client.*`).
+ */
+export class RawSubscription {
+    onClose;
+    queue = new AsyncQueue();
+    constructor(onClose) {
+        this.onClose = onClose;
+    }
+    consider(env) {
+        this.queue.push(env);
+        // Raw taps don't claim envelopes — they always return false so task
+        // subscriptions still see them.
+        return false;
+    }
+    considerClient(ev) {
+        if (this.queue.isClosed)
+            return;
+        this.queue.push(ev);
+    }
+    fail(err) {
+        this.queue.fail(err);
+        this.onClose(this);
+    }
+    close() {
+        this.queue.close();
+        this.onClose(this);
+    }
+    next() {
+        return this.queue.next();
+    }
+    async return() {
+        if (!this.queue.isClosed) {
+            this.queue.close();
+            this.onClose(this);
+        }
+        return { value: undefined, done: true };
+    }
+    async throw(err) {
+        this.queue.close();
+        this.onClose(this);
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+/** Default cap on the paused-queue size. */
+const DEFAULT_PAUSED_QUEUE_MAX = 100;
+/**
+ * Marker `session_id` stamped on synthetic `envelope_parse_error` events
+ * the SDK generates when an inbound frame fails JSON-schema parsing.
+ * Never crosses the wire — consumers seeing it via `client.receive()`
+ * should recognize the zero pattern as "synthetic, not server-derived".
+ *
+ * The zero-UUID is not used as a wire-side cold-address fallback (cold
+ * cancel / continue / resubscribe / respond throw
+ * {@link QodoColdAddressError} locally before encoding). This constant
+ * is dedicated to the in-memory synthetic-event path.
+ */
+const SYNTHETIC_PARSE_ERROR_SESSION_ID = asSessionId('00000000-0000-0000-0000-000000000000');
+/** Default reconnect policy — three attempts at 1s/2s/4s, then give up. */
+const DEFAULT_RECONNECT_MAX_ATTEMPTS = 3;
+const DEFAULT_RECONNECT_INITIAL_BACKOFF_MS = 1000;
+const DEFAULT_RECONNECT_BACKOFF_MULTIPLIER = 2;
+/**
+ * Outbound kinds the SDK throttles when the connection is in `flow.pause`
+ * state. `tool.response` is the server's blocked party — never throttled.
+ * `task.cancel` is user intent to bail — never throttled.
+ * `task.resubscribe` is a recovery path and stays unthrottled too: holding a
+ * resubscribe behind backpressure would defeat the point of replay.
+ */
+const THROTTLED_OUTBOUND_KINDS = new Set([
+    'task.start',
+    'task.continue',
+]);
+/**
+ * Live connection state. Owns the (replaceable) transport and the set of
+ * subscriptions; routes inbound envelopes to subscriptions via `consider`.
+ *
+ * **No connection-level `sessionId`.** Every `task.start` creates a NEW
+ * server-derived session, so an envelope's `session_id` is the TASK's
+ * session — not a property of the WebSocket. The SDK tracks
+ * `task_id → session_id` and `tool_call_id → session_id` here so that
+ * outbound ongoing envelopes can be stamped with the right session at
+ * encode time without coupling consumer code to per-task session
+ * bookkeeping.
+ */
+export class Connection {
+    factory;
+    url;
+    headers;
+    traceContext;
+    metrics;
+    subscriptions = new Set();
+    /**
+     * Map of `task_id → session_id` populated from inbound `task.started`
+     * envelopes. Read by {@link sendEnvelope} when encoding `task.continue`
+     * / `task.cancel` / `task.resubscribe` so each ongoing envelope
+     * carries the same server-derived `session_id` the server bound during
+     * admission — preventing multi-task `session_mismatch` without
+     * exposing per-task session bookkeeping on the public API.
+     *
+     * Lifetime: entries are added when `task.started` lands and PRUNED on
+     * `task.done` (the wire's terminal ack — task is fully finished). Any
+     * later `task.resubscribe` against the same `task_id` would be a
+     * cross-process recovery path that has no in-memory session anyway, so
+     * pruning doesn't regress that scenario. Cleared on transport close.
+     * The auto-reconnect/replay path uses LIVE (non-terminated)
+     * subscriptions and adds the session back via the server's replayed
+     * `task.started`, so it's unaffected.
+     *
+     * **Pre-admission invariant.** A live `TaskSubscription` MAY lack an
+     * entry in this map: between `tasks.start` writing its outbound
+     * `task.start` and the inbound `task.started` ack landing, the
+     * subscription is registered in {@link subscriptions} but the
+     * `session_id` is not yet pinned here. A WS drop during this window
+     * leaves the subscription in an unrecoverable state per the
+     * session-identity contract. {@link replayActiveTasks} pre-checks this
+     * map before attempting `task.resubscribe` and short-circuits to
+     * `sub.fail(QodoColdAddressError)` for un-pinned subs — see that
+     * method's JSDoc for the state-machine narrative.
+     */
+    taskSessions = new Map();
+    /**
+     * Map of `tool_call_id → session_id` populated from inbound `tool.request`
+     * envelopes. Read by {@link sendEnvelope} when encoding `tool.response`,
+     * which carries `responses: ToolResponseItem[]` and inherits the parent
+     * `tool.request`'s session via the first response item's `tool_call_id`.
+     *
+     * Lifetime: entries are added when `tool.request` lands and PRUNED on
+     * EITHER (a) the outbound `tool.response` hits the wire (single-use
+     * — one request, one response), OR (b) the owning task terminates
+     * via `task.done` without the consumer ever responding (manual handler
+     * returned `undefined` to indicate async-respond-later, then the task
+     * timed out / canceled / completed without the response). Without (b)
+     * the map would accumulate orphan `tool_call_id` entries on long-lived
+     * connections. Cleared on transport close.
+     */
+    toolCallSessions = new Map();
+    /**
+     * Reverse index of `session_id → Set<ToolCallId>`. Populated on
+     * inbound `tool.request`
+     * (one entry per call). Used to sweep {@link toolCallSessions} when
+     * the owning task terminates without a `tool.response` ever being
+     * sent for some of its outstanding calls — the manual-handler
+     * respond-later path explicitly allows this, and without the sweep
+     * the per-call map entries would survive forever on long-lived
+     * connections.
+     *
+     * Indexed by `session_id` (not `task_id`) because that's the
+     * dimension `tool.request` envelopes carry on the wire — the SDK
+     * derives the owning session via the envelope's `session_id` field,
+     * not via any task_id field on the payload.
+     */
+    outstandingToolCallsBySession = new Map();
+    /**
+     * Reverse index of outbound `task.continue` message_id →
+     * `{ taskId, sessionId }` for envelopes
+     * that carried a caller-supplied cold-address `sessionId` override.
+     * Populated AFTER the wire write (or queued-drain) succeeds; used to
+     * identify which `taskSessions` entry to prune when the server rejects
+     * the override with `error { code: 'session_mismatch' }`.
+     *
+     * Without this index, a wrong cold-address override would pollute
+     * {@link taskSessions} (because `sendEnvelope`'s post-send write
+     * persists the consumer-supplied value as authoritative) and a
+     * subsequent no-override call for the same task would silently reuse
+     * the already-rejected session instead of raising
+     * {@link QodoColdAddressError}.
+     *
+     * **Generation safety:** the entry stores the sessionId of the
+     * override the offending message carried. Pruning is
+     * conditional: we delete `taskSessions[taskId]` ONLY when the
+     * authoritative entry still matches the rejected sessionId. If a
+     * later send for the same task superseded the override with a fresh
+     * (valid) sessionId, the rejection for the stale message must NOT
+     * blow away the newer authoritative entry. The reverse-map entry for
+     * the offending message_id is deleted unconditionally (it's a per-
+     * message tombstone; the message is finished one way or the other).
+     *
+     * Entries are pruned (a) on inbound `error { code: 'session_mismatch' }`
+     * for a known offending_message_id (with generation check), and (b)
+     * on inbound `task.done` for the matching task_id (terminal sweep).
+     * Cleared on transport-terminal cleanup.
+     */
+    outboundOverrideRefs = new Map();
+    state = 'connected';
+    /** App-level backpressure flag. Flipped by inbound `flow.pause` / `flow.resume`. */
+    paused = false;
+    /**
+     * FIFO of pre-encoded JSON frames that arrived while paused. Drained in
+     * insertion order on `flow.resume`. Pre-encoding at queue-time keeps the
+     * drain path a thin pass-through to the transport.
+     *
+     * Each entry is tagged with the envelope's `messageId` so the owning
+     * `TaskSubscription` can retract its frame on early termination (abort or
+     * iterator break) — without that link, a queued `task.continue` would
+     * still go to the wire on `flow.resume` after the consumer has already
+     * canceled, producing `cancel → continue` reordering on the server.
+     */
+    pausedQueue = [];
+    pausedQueueMax;
+    /** Reconnect policy. */
+    reconnectMaxAttempts;
+    reconnectInitialBackoffMs;
+    reconnectBackoffMultiplier;
+    /**
+     * Pending backoff sleeps. Each entry pairs the timer handle with the
+     * Promise's resolve callback so `disconnect()` mid-reconnect can both
+     * cancel the timer AND wake the loop up so it observes the new state on
+     * the next iteration — without the resolver, clearing the timer would
+     * leave the await pending forever.
+     */
+    pendingSleeps = new Set();
+    /** The active transport. Mutable — replaced on every successful reconnect. */
+    transport;
+    /** Bound handler instance reused across every transport (initial + reconnects). */
+    handlers;
+    constructor(factory, url, headers, initialTransport, handlers, maxPausedQueueSize, reconnect, traceContext, metrics) {
+        this.factory = factory;
+        this.url = url;
+        this.headers = headers;
+        this.traceContext = traceContext;
+        this.metrics = metrics;
+        this.transport = initialTransport;
+        this.handlers = handlers;
+        // Treat <=0 as "fall back to default" — a zero/negative cap would lock out
+        // every throttled send the moment pause arrives, which is never what a
+        // consumer wanted. They should opt in explicitly with a positive integer.
+        this.pausedQueueMax =
+            maxPausedQueueSize !== undefined && maxPausedQueueSize > 0
+                ? maxPausedQueueSize
+                : DEFAULT_PAUSED_QUEUE_MAX;
+        this.reconnectMaxAttempts = pickNonNegativeInt(reconnect?.maxAttempts, DEFAULT_RECONNECT_MAX_ATTEMPTS);
+        this.reconnectInitialBackoffMs = pickPositiveInt(reconnect?.initialBackoffMs, DEFAULT_RECONNECT_INITIAL_BACKOFF_MS);
+        this.reconnectBackoffMultiplier = pickPositiveNumber(reconnect?.backoffMultiplier, DEFAULT_RECONNECT_BACKOFF_MULTIPLIER);
+    }
+    /**
+     * Construct + open a fresh connection through the factory. The connection
+     * captures the factory + url + headers so it can re-open on transport drops
+     * without the caller threading them through again.
+     */
+    static async open(args) {
+        // No connection-level `sessionId` — every `task.start` creates a
+        // NEW server-derived session, so the connection holds no session at
+        // all. Outbound encodes stamp the right per-Task session_id from
+        // {@link Connection.taskSessions} / {@link Connection.toolCallSessions}.
+        //
+        // Handlers are constructed before the `Connection` instance because
+        // the factory needs them. The default `ws` transport can't fire
+        // `onMessage` until 'open' resolves, so the original `connection?.…`
+        // closure was safe with the bundled transport. Custom transports —
+        // an in-memory mock, a non-`ws` browser adapter, a synchronous-replay
+        // test double — can fire callbacks from inside the factory call,
+        // *before* the `Connection` is assigned. With the original code, those
+        // early frames silently no-op'd through the `?.` chain. We instead
+        // queue inbound events until the `Connection` is wired and drain them
+        // synchronously on the next tick, preserving FIFO order.
+        let connection = null;
+        const pending = [];
+        const handlers = {
+            onMessage: (data) => {
+                if (connection !== null)
+                    connection.dispatch(data);
+                else
+                    pending.push({ kind: 'message', data });
+            },
+            onError: (err) => {
+                if (connection !== null)
+                    connection.transportFailed(err);
+                else
+                    pending.push({ kind: 'error', err });
+            },
+            onClose: (code, reason) => {
+                if (connection !== null)
+                    connection.transportClosed(code, reason);
+                else
+                    pending.push({ kind: 'close', code, reason });
+            },
+        };
+        const transport = await args.factory({
+            url: args.url,
+            headers: args.headers,
+            handlers,
+        });
+        connection = new Connection(args.factory, args.url, args.headers, transport, handlers, args.maxPausedQueueSize, args.reconnect, args.traceContext, args.metrics);
+        // Drain anything the transport fired synchronously inside the factory
+        // call. Order matters: messages, errors, closes must replay in the
+        // exact sequence they arrived. Track the first terminal event so that
+        // if the replay moves the connection out of `connected`, we surface
+        // that as a rejection from `open()` rather than handing back an
+        // already-broken connection to `QodoClient.connect()` — which would
+        // otherwise resolve, wire sub-clients, and let the failure go
+        // unobserved.
+        let terminalReason;
+        for (const ev of pending) {
+            if (ev.kind === 'message') {
+                connection.dispatch(ev.data);
+            }
+            else if (ev.kind === 'error') {
+                connection.transportFailed(ev.err);
+                terminalReason ??= ev.err;
+            }
+            else {
+                connection.transportClosed(ev.code, ev.reason);
+                terminalReason ??= new Error(`Transport closed before connect() returned (code=${ev.code}, reason=${ev.reason || '<none>'})`);
+            }
+        }
+        if (!connection.isOpen) {
+            throw (terminalReason ??
+                new Error('Transport closed before connect() returned (no reason captured)'));
+        }
+        return connection;
+    }
+    /**
+     * Encode and send an outbound envelope. Returns the assigned `message_id` so
+     * the caller can track the parent_message_id chain.
+     *
+     * Optionally accepts a pre-allocated `messageId` so subscriptions can be
+     * registered against a known root before the envelope hits the wire — avoids
+     * a race where an inbound reply could be dispatched before the subscription
+     * is in place.
+     *
+     * If the connection is in `flow.pause` and `out.kind` is throttled
+     * (`task.start` / `task.continue`), the encoded frame is enqueued and drained
+     * once `flow.resume` arrives. The returned `messageId` is still allocated
+     * synchronously so callers can register subscriptions against it before the
+     * envelope hits the wire — same invariant as the unpaused path.
+     *
+     * Throws `QodoBackpressureError` when the queue is at its cap.
+     */
+    sendEnvelope(out, opts) {
+        if (!this.canSend()) {
+            throw new Error('Connection is not open');
+        }
+        const messageId = opts?.messageId ?? asMessageId(uuidv7());
+        const parentMessageId = opts?.parentMessageId;
+        // Wire-shape split: `task.start` (a `_StartEnvelopeBase`)
+        // does NOT carry `session_id` on the wire — the server derives it from
+        // `(tenant_id, payload.idempotency_key)` during the ingress
+        // bind-and-derive phase. QAR's Pydantic model has `extra="forbid"`, so
+        // a stray `session_id` field would fail server-side parsing. Build the
+        // wire view WITHOUT `session_id` for `task.start`; every other kind
+        // (`_OngoingEnvelopeBase`) MUST carry the per-Task session — resolved
+        // below via taskSessions / toolCallSessions / explicit override.
+        const baseCommon = {
+            envelope_version: 1,
+            message_id: messageId,
+            ...(parentMessageId !== undefined ? { parent_message_id: parentMessageId } : {}),
+            // Read the live trace context at emit-time so the active OTel span
+            // (typically the per-public-API span the client is currently inside)
+            // becomes the parent of QAR's server-side WS-upgrade span. Without
+            // OTel configured, this is a fresh random 55-char traceparent — the
+            // server's schema enforces a non-empty match, so an actually-empty
+            // string would fail validation rather than continue the trace.
+            trace_context: this.traceContext.current(),
+            ts: new Date().toISOString(),
+        };
+        let json;
+        if (out.kind === 'task.start') {
+            json = JSON.stringify({
+                ...baseCommon,
+                kind: 'task.start',
+                payload: out.payload,
+            });
+        }
+        else if (out.kind === 'task.forceResume') {
+            // `task.forceResume` is a `_StartEnvelopeBase` shape: it operates
+            // on the consumer's `idempotency_key` rather than a server-bound
+            // `session_id`. QAR derives the session UUID server-side using the
+            // same `uuidv5(QAR_NS_V1, tenant_id + ":" + idempotency_key)`
+            // derivation as `task.start` admission, so a stray outbound
+            // `session_id` would (a) be redundant and (b) fail Pydantic
+            // `extra="forbid"` validation on the QAR side. Strip the field at
+            // emit-time, matching the `task.start` path.
+            json = JSON.stringify({
+                ...baseCommon,
+                kind: 'task.forceResume',
+                payload: out.payload,
+            });
+        }
+        else {
+            const sessionId = this.resolveOutboundSessionId(out, opts?.sessionId);
+            const base = { ...baseCommon, session_id: sessionId };
+            let envelope;
+            switch (out.kind) {
+                case 'task.continue':
+                    envelope = { ...base, kind: 'task.continue', payload: out.payload };
+                    break;
+                case 'task.cancel':
+                    envelope = { ...base, kind: 'task.cancel', payload: out.payload };
+                    break;
+                case 'task.resubscribe':
+                    envelope = { ...base, kind: 'task.resubscribe', payload: out.payload };
+                    break;
+                case 'tool.response':
+                    envelope = { ...base, kind: 'tool.response', payload: out.payload };
+                    break;
+            }
+            json = JSON.stringify(envelope);
+        }
+        // Capture the cold-address override info BEFORE the queue/send
+        // branches, but DON'T mutate
+        // {@link taskSessions} yet — that write must wait for send-success
+        // (or for drain-success on the queued path). Stamping the
+        // authoritative map at this point would leave a stale entry behind
+        // if `transport.send` throws, the paused-queue overflows, or the
+        // connection drops mid-pause before the queued frame drains.
+        //
+        // Only `task.continue` actually NEEDS the post-send save: a
+        // subscription started from `tasks.continue(..., { sessionId })`
+        // can trigger an internal `task.cancel` through TWO paths that
+        // both go through `Connection.sendEnvelope` WITHOUT re-threading
+        // the option:
+        //   (a) TaskSubscription.onEarlyReturn — iterator break sends a
+        //       best-effort `task.cancel` (the consumer's iterator break
+        //       implies cancel intent).
+        //   (b) `TaskClient.bindAbort` — the consumer's AbortSignal fires
+        //       a `task.cancel` with reason `'abort signal'`.
+        // Without the post-send save, BOTH paths would raise
+        // `QodoColdAddressError` (the connection has no in-memory
+        // session for this task_id). The save unblocks (a) directly;
+        // (b) is double-protected by `bindAbort` forwarding the
+        // original `opts.sessionId` to its own `sendEnvelope` call.
+        // `task.cancel` and `task.resubscribe` don't spawn follow-up
+        // internal sends (the former is terminal; the latter passes
+        // `suppressEarlyReturnCancel: true`), so they don't need to
+        // leave behind a sticky entry — keeping the map tighter means
+        // a future no-override call for the same task_id correctly
+        // raises `QodoColdAddressError`.
+        const overrideTaskSave = opts?.sessionId !== undefined && out.kind === 'task.continue'
+            ? { taskId: out.payload.task_id, sessionId: opts.sessionId }
+            : undefined;
+        if (this.paused && THROTTLED_OUTBOUND_KINDS.has(out.kind)) {
+            if (this.pausedQueue.length >= this.pausedQueueMax) {
+                // Throw BEFORE mutating any authoritative state (taskSessions,
+                // pausedQueue itself) so a queue-overflow leaves zero side
+                // effects from this call.
+                throw new QodoBackpressureError(this.pausedQueue.length, this.pausedQueueMax);
+            }
+            this.pausedQueue.push({
+                messageId,
+                json,
+                ...(overrideTaskSave !== undefined ? { overrideToSave: overrideTaskSave } : {}),
+            });
+            return messageId;
+        }
+        this.transport.send(json);
+        // Persist the cold-address override
+        // ONLY AFTER the wire write returned without throwing. A
+        // transport-mid-call failure now leaves no stale entry in
+        // {@link taskSessions}, so a subsequent no-override call for the
+        // same task_id correctly raises `QodoColdAddressError` instead of
+        // silently reusing the never-sent override.
+        if (overrideTaskSave !== undefined) {
+            this.taskSessions.set(overrideTaskSave.taskId, overrideTaskSave.sessionId);
+            // Note the outbound
+            // message_id with the sessionId it carried so an inbound
+            // `session_mismatch` for this frame can prune the polluted
+            // authoritative entry above — but ONLY when the entry has not
+            // been superseded by a fresh override for the same task.
+            this.outboundOverrideRefs.set(messageId, {
+                taskId: overrideTaskSave.taskId,
+                sessionId: overrideTaskSave.sessionId,
+            });
+        }
+        // Stamp `resubscribes_sent_total` only after the wire write returned
+        // without throwing — counting before send would over-count when the
+        // transport closes mid-call and `send` raises. `task.resubscribe`
+        // isn't in `THROTTLED_OUTBOUND_KINDS`, so it
+        // never enters the paused-queue branch above; the only success path is
+        // the direct send.
+        if (out.kind === 'task.resubscribe') {
+            this.metrics?.recordResubscribeSent();
+        }
+        // Prune both forward and reverse session-index maps after the
+        // outbound `tool.response` lands on the wire — each `tool_call_id`
+        // is single-use (one request → one response per call). Bounds the
+        // maps on long-lived connections running many tool calls.
+        if (out.kind === 'tool.response') {
+            for (const r of out.payload.responses) {
+                const tcid = r.tool_call_id;
+                const sid = this.toolCallSessions.get(tcid);
+                this.toolCallSessions.delete(tcid);
+                if (sid !== undefined) {
+                    const outstanding = this.outstandingToolCallsBySession.get(sid);
+                    if (outstanding !== undefined) {
+                        outstanding.delete(tcid);
+                        if (outstanding.size === 0) {
+                            this.outstandingToolCallsBySession.delete(sid);
+                        }
+                    }
+                }
+            }
+        }
+        return messageId;
+    }
+    /**
+     * Resolve the per-Task `session_id` for an outbound ongoing envelope.
+     * Caller-supplied `override` wins (the dispatcher path passes the
+     * captured inbound `session_id` directly, and the cold-address
+     * public-API path passes the consumer-supplied option); otherwise look
+     * up by the payload's task_id (`task.continue` / `task.cancel` /
+     * `task.resubscribe`) or by the first response item's tool_call_id
+     * (`tool.response`).
+     *
+     * When neither an override NOR an in-memory entry is available, throw
+     * {@link QodoColdAddressError} synchronously. Throwing locally:
+     *
+     *   - puts the cold-address remediation right in the error message
+     *     (consumer should pass `sessionId` from durable storage),
+     *   - saves a wire round-trip + the misleading `session_mismatch`
+     *     error message ("envelope session_id differs from connection
+     *     session" — true but unactionable),
+     *   - matches the doctrinal correct shape (make it right, not make
+     *     it work).
+     *
+     * The primary cross-task session-leak guard is the lookup itself when
+     * admission HAS completed.
+     */
+    resolveOutboundSessionId(out, override) {
+        if (override !== undefined)
+            return override;
+        switch (out.kind) {
+            case 'task.continue':
+            case 'task.cancel':
+            case 'task.resubscribe': {
+                const taskId = out.payload.task_id;
+                const sessionId = this.taskSessions.get(taskId);
+                if (sessionId === undefined) {
+                    throw new QodoColdAddressError('task', taskId);
+                }
+                return sessionId;
+            }
+            case 'tool.response': {
+                const first = out.payload.responses[0];
+                // `responses` is validated non-empty by `ToolClient.respond` /
+                // the auto-dispatch path; reach here only via direct internal
+                // mis-use, so the throw is a hard invariant. Tag the empty case
+                // explicitly to make the violated invariant visible.
+                if (first === undefined) {
+                    throw new QodoColdAddressError('tool_call', '<empty-responses-array>');
+                }
+                const toolCallId = first.tool_call_id;
+                const sessionId = this.toolCallSessions.get(toolCallId);
+                if (sessionId === undefined) {
+                    throw new QodoColdAddressError('tool_call', toolCallId);
+                }
+                return sessionId;
+            }
+        }
+    }
+    /**
+     * Retract a queued throttled envelope by its `message_id`. Called by
+     * `TaskSubscription` when it terminates early (abort signal, iterator
+     * break, transport failure) so the consumer's cancel intent doesn't race
+     * with their own queued frame on the next `flow.resume`.
+     *
+     * No-op if the messageId isn't queued (already drained, never queued, or
+     * a different envelope kind that doesn't enter the throttle path).
+     * Returns whether an entry was removed — informational only.
+     */
+    dropQueued(messageId) {
+        if (this.pausedQueue.length === 0)
+            return false;
+        const idx = this.pausedQueue.findIndex((entry) => entry.messageId === messageId);
+        if (idx === -1)
+            return false;
+        this.pausedQueue.splice(idx, 1);
+        return true;
+    }
+    /** Send a raw envelope verbatim — escape hatch. */
+    sendRawEnvelope(env) {
+        if (!this.canSend()) {
+            throw new Error('Connection is not open');
+        }
+        this.transport.send(JSON.stringify(env));
+    }
+    /**
+     * Look up the server-derived `session_id` for a known `task_id`.
+     * Used by span recorders that want to stamp `qar.session_id`
+     * on per-Task spans without coupling caller code to the per-Task lookup
+     * map. Returns `undefined` when no `task.started` ack has arrived for
+     * this `task_id` yet (the start path's span is opened pre-admission and
+     * must tolerate this).
+     */
+    getSessionForTask(taskId) {
+        return this.taskSessions.get(taskId);
+    }
+    /**
+     * Look up the `session_id` of the inbound `tool.request` a given
+     * `tool_call_id` came from. Used by `ToolClient.respond` to stamp
+     * its outbound `tool.response` span with the right session without
+     * threading the value through every call site. Returns `undefined` when
+     * no matching `tool.request` arrived (test-only path, or a malformed
+     * consumer call).
+     */
+    getSessionForToolCall(toolCallId) {
+        return this.toolCallSessions.get(toolCallId);
+    }
+    /**
+     * Run `fn` inside the span context of the live `TaskSubscription` that
+     * OWNS `env` by lineage, so an inbound `tool.request` dispatched to the
+     * consumer's handler inherits the originating turn's trace context (its
+     * `qar.client.task.*` span). Without this, the fanout invokes the handler
+     * under the bare WS-receive context and the SDK's `qar.client.tool.handler`
+     * span — plus the consumer's outbound MCP/fetch traceparent — are orphaned
+     * from the task trace.
+     *
+     * Ownership is the unique subscription whose {@link TaskSubscription.ownsLineage}
+     * holds for `env` — its `parent_message_id` traces (through real
+     * `parent_message_id` links) back to that subscription's own outbound root.
+     * This is unambiguous even when same-task subscriptions overlap (a live
+     * auto-paused `tasks.start` sub alongside an active `tasks.continue`): the
+     * passive sub absorbs the active turn's stream into its routing chain via
+     * the `task_id` fallback, but never into its ownership lineage, so it never
+     * wins — at any tool-call depth (multi-round T1→D2→T2).
+     *
+     * Terminated subscriptions are skipped (a live task owns an in-flight tool
+     * call). Falls through to `fn()` unchanged when no owner is found — a strict
+     * no-op for non-OTel consumers, for a `tool.request` whose lineage root was
+     * never sent by this process (cold `task.resubscribe` replay), and for an
+     * owner with no span.
+     */
+    runInOwningTaskContext(env, fn) {
+        for (const sub of this.subscriptions) {
+            if (sub instanceof TaskSubscription && !sub.isTerminated && sub.ownsLineage(env)) {
+                return sub.runInTaskContext(fn);
+            }
+        }
+        return fn();
+    }
+    /** Register a subscription. Caller is responsible for unregistering on close. */
+    subscribe(sub) {
+        this.subscriptions.add(sub);
+    }
+    unsubscribe(sub) {
+        this.subscriptions.delete(sub);
+    }
+    /**
+     * Tear down: close transport, fail all subscriptions cleanly. Idempotent.
+     * Called by `QodoClient.disconnect()` and by the `onClose` transport handler
+     * for clean closes. Mid-reconnect calls switch state to `disconnecting` so
+     * the in-flight loop bails on the next tick.
+     */
+    close() {
+        if (this.state === 'disconnected' || this.state === 'failed')
+            return;
+        const wasReconnecting = this.state === 'reconnecting';
+        this.state = wasReconnecting ? 'disconnecting' : 'disconnected';
+        this.clearBackpressureState();
+        this.clearTerminalState();
+        this.clearPendingTimers();
+        try {
+            this.transport.close(1000, 'client disconnect');
+        }
+        catch {
+            // Best-effort — transport may be wedged after a failure.
+        }
+        if (!wasReconnecting) {
+            // No outstanding async work — close subs synchronously.
+            for (const sub of [...this.subscriptions]) {
+                sub.close();
+            }
+            this.subscriptions.clear();
+        }
+        // For wasReconnecting=true: the reconnect loop sees `disconnecting`
+        // on its next iteration and walks the close path itself, including
+        // sub cleanup. This avoids a race where two paths both try to close
+        // the same subscriptions.
+    }
+    /**
+     * Drop any queued envelopes and clear the paused flag. Called on every
+     * tear-down path (clean close, transport error, transport close) — leaving
+     * frames in the queue past disconnect would either leak memory or surface
+     * stale outbound on a future connection that reused this object.
+     *
+     * Does NOT clear the per-Task / per-Tool-call session-id lookup maps —
+     * those must survive the reconnect window so `replayActiveTasks` can
+     * stamp the right `session_id` on each `task.resubscribe` envelope it
+     * emits. Final cleanup of the session maps lives in
+     * {@link clearTerminalState}, invoked from the actual tear-down paths.
+     */
+    clearBackpressureState() {
+        this.paused = false;
+        this.pausedQueue.length = 0;
+    }
+    /**
+     * Drop the per-Task and per-Tool-call session-id lookup maps. Called
+     * from terminal cleanup paths (`close`,
+     * `cleanCloseAndCleanup`, `failHardAndCleanup`, `finalizeDisconnect`) so
+     * a future `connect()` reusing the same `Connection` object starts with
+     * an empty session-id table. Distinct from {@link clearBackpressureState}
+     * because the reconnect path MUST keep these populated for replay.
+     */
+    clearTerminalState() {
+        this.taskSessions.clear();
+        this.toolCallSessions.clear();
+        this.outstandingToolCallsBySession.clear();
+        this.outboundOverrideRefs.clear();
+    }
+    /** Whether the connection accepts outbound sends right now. */
+    get isOpen() {
+        return this.state === 'connected' && this.transport.isOpen;
+    }
+    /**
+     * Whether the connection is mid-reconnect. `isOpen` is false during this
+     * window; outbound sends throw. Tests + observability surfaces read this
+     * to render a "reconnecting" indicator.
+     */
+    get isReconnecting() {
+        return this.state === 'reconnecting';
+    }
+    /**
+     * Whether the server has signalled `flow.pause` and we have not yet seen
+     * `flow.resume`. While `true`, throttled outbound kinds are queued.
+     */
+    get isPaused() {
+        return this.paused;
+    }
+    /**
+     * Snapshot of the paused-queue depth. Useful for tests and observability;
+     * not a live counter (no subscription, no event).
+     */
+    get pausedQueueDepth() {
+        return this.pausedQueue.length;
+    }
+    /** Raw outbound predicate — connected AND transport is in OPEN state. */
+    canSend() {
+        return this.state === 'connected' && this.transport.isOpen;
+    }
+    dispatch(text) {
+        if (this.state === 'disconnected' || this.state === 'failed')
+            return;
+        let env;
+        try {
+            env = parseEnvelope(text);
+        }
+        catch (err) {
+            // Malformed inbound — synthesize an `error` envelope so consumers see it
+            // rather than silently dropping the frame. The synthetic carries no
+            // parent_message_id, so it won't claim any task subscription; raw taps
+            // see it, task iterators don't.
+            //
+            // The synthetic never reaches the wire, but the `Envelope` shape
+            // requires a `session_id`. Use the zero UUID as a
+            // marker — the value is opaque to consumers (the only ones that
+            // see this are raw taps via `client.receive()`) and the zero pattern
+            // makes "parse-error synthetic" cheap to recognize in logs.
+            const synthetic = {
+                envelope_version: 1,
+                message_id: asMessageId(uuidv7()),
+                session_id: SYNTHETIC_PARSE_ERROR_SESSION_ID,
+                trace_context: this.traceContext.current(),
+                ts: new Date().toISOString(),
+                kind: 'error',
+                payload: {
+                    code: 'envelope_parse_error',
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            };
+            this.fanout(synthetic);
+            return;
+        }
+        // Capture per-Task `session_id` from the admission ack BEFORE
+        // fanout so any subscription that synchronously re-enters
+        // `sendEnvelope` (e.g. a tool-handler completing inside the same tick
+        // that received `task.started`) sees the right session for outbound
+        // ongoing envelopes. Same pattern for `tool.request` → `tool_call_id`
+        // mapping, populated for every call in the batched payload.
+        //
+        // Pruning: a long-lived connection running
+        // many sequential tasks / tool calls would accumulate entries
+        // unboundedly without active eviction. Prune `taskSessions` on
+        // `task.done` (the wire's terminal ack — task is fully finished;
+        // post-done `task.resubscribe` for cross-pod recovery doesn't have
+        // the session in-memory either way) and let `tool.response` send
+        // prune `toolCallSessions` (each response item's `tool_call_id` is
+        // the last reference). Reconnect/replay isn't affected because the
+        // replay path uses `task.resubscribe` against a still-LIVE
+        // subscription's `task_id`, which is added back to the map on the
+        // server's replayed `task.started`.
+        if (env.kind === 'task.started') {
+            const payload = env.payload;
+            this.taskSessions.set(payload.task_id, env.session_id);
+        }
+        else if (env.kind === 'task.force_resumed') {
+            // `task.force_resumed` is the ack for `task.forceResume` — the
+            // recovered session's existing `task_id` is on the payload, and
+            // the inherited `session_id` is the derived UUID. Bind the
+            // per-Task session map so a subsequent
+            // `tasks.continue(taskId)` resolves the right session at
+            // outbound encode time without forcing the consumer to thread
+            // `sessionId` through every call.
+            const payload = env.payload;
+            this.taskSessions.set(payload.task_id, env.session_id);
+        }
+        else if (env.kind === 'task.done') {
+            // Cast through `unknown` because the codegen payload's `task_id` is
+            // the unbranded `string` shape; the SDK overlay brands it as
+            // `TaskId` everywhere else but the inbound parse path doesn't
+            // re-brand. Safe — the wire value IS a TaskId by invariant.
+            const payload = env.payload;
+            const taskId = payload.task_id;
+            const sessionForTask = this.taskSessions.get(taskId);
+            this.taskSessions.delete(taskId);
+            // Sweep any outbound-override
+            // refs pointing at this task — the task is terminal, no further
+            // sends can need the message_id → {taskId, sessionId} lookup.
+            for (const [mid, ref] of this.outboundOverrideRefs) {
+                if (ref.taskId === taskId)
+                    this.outboundOverrideRefs.delete(mid);
+            }
+            // Sweep any outstanding tool_call_ids that were never responded
+            // to before
+            // the task terminated (manual handler returned `undefined` then
+            // the task timed out / canceled / completed without a response).
+            if (sessionForTask !== undefined) {
+                const outstanding = this.outstandingToolCallsBySession.get(sessionForTask);
+                if (outstanding !== undefined) {
+                    for (const tcid of outstanding) {
+                        this.toolCallSessions.delete(tcid);
+                    }
+                    this.outstandingToolCallsBySession.delete(sessionForTask);
+                }
+            }
+        }
+        else if (env.kind === 'error') {
+            // A `session_mismatch` error against an outbound that carried a
+            // caller-supplied cold-address override means THAT override was
+            // wrong. Prune the polluted entry in `taskSessions` so a
+            // subsequent no-override call raises `QodoColdAddressError` —
+            // BUT only when the authoritative entry still matches the
+            // rejected session. If a later send superseded this override
+            // with a newer (valid) sessionId for the same task, the stale
+            // mismatch must NOT blow away the newer entry (generation
+            // safety).
+            //
+            // The reverse-map tombstone for the offending message_id is
+            // always deleted: that message is finished one way or the other.
+            const errorPayload = env.payload;
+            if (errorPayload.code === 'session_mismatch') {
+                const offendingId = typeof errorPayload.offending_message_id === 'string'
+                    ? errorPayload.offending_message_id
+                    : undefined;
+                if (offendingId !== undefined) {
+                    const ref = this.outboundOverrideRefs.get(offendingId);
+                    if (ref !== undefined) {
+                        const authoritative = this.taskSessions.get(ref.taskId);
+                        if (authoritative === ref.sessionId) {
+                            // The override is STILL the authoritative entry — it
+                            // hasn't been superseded by a fresher send. Prune.
+                            this.taskSessions.delete(ref.taskId);
+                        }
+                        // The reverse-map entry is per-message; remove
+                        // unconditionally now that this message has resolved
+                        // (server rejection counts as resolution).
+                        this.outboundOverrideRefs.delete(offendingId);
+                    }
+                    // `tool.response` cleanup: even though the per-send prune
+                    // already removes the tool_call_id mapping post-send, a
+                    // wrong override on `tool.response` would have polluted
+                    // `toolCallSessions` before the prune ran (the wire send
+                    // succeeds before the prune; only the server's rejection
+                    // arrives later). The post-send prune already deletes the
+                    // entry on success, so by the time the session_mismatch
+                    // lands the entry is gone — nothing to clean. This branch
+                    // is here for symmetry with the task-id path; documented
+                    // so future changes don't reintroduce a leak.
+                }
+            }
+        }
+        else if (env.kind === 'tool.request') {
+            const calls = env.payload.calls;
+            let outstanding = this.outstandingToolCallsBySession.get(env.session_id);
+            if (outstanding === undefined) {
+                outstanding = new Set();
+                this.outstandingToolCallsBySession.set(env.session_id, outstanding);
+            }
+            for (const c of calls) {
+                const tcid = c.tool_call_id;
+                this.toolCallSessions.set(tcid, env.session_id);
+                outstanding.add(tcid);
+            }
+        }
+        // App-level backpressure. Update internal state BEFORE fanout so
+        // consumers reading `isPaused` from a TaskEvent handler see the new value.
+        // For `flow.resume`, drain the queue first too — any throttled send the
+        // consumer issues from the same handler then takes the unpaused fast path.
+        if (env.kind === 'flow.pause') {
+            this.paused = true;
+        }
+        else if (env.kind === 'flow.resume') {
+            this.paused = false;
+            this.drainPausedQueue();
+        }
+        this.fanout(env);
+        // Surface `task.canceling` to task iterators as a
+        // `qar.client.cancel_acked` synthetic client event. The envelope
+        // itself still went through `fanout` so raw `client.receive()` taps
+        // observe the wire frame; the synthetic event is what reaches
+        // consumers iterating via `for await (const event of
+        // client.tasks.start(...))` without expanding the `TaskEvent`
+        // switch surface.
+        if (env.kind === 'task.canceling') {
+            this.dispatchCancelAcked(env);
+        }
+    }
+    /**
+     * Translate an inbound `task.canceling` envelope into a typed
+     * `ClientCancelAckedEvent` and route it to the subscription whose chain
+     * (or `task_id`) matches. Scoped — not connection-wide — so a consumer
+     * running multiple tasks only sees the ack for the task they're
+     * iterating.
+     *
+     * Skips taps (`RawSubscription` already received the envelope through
+     * `fanout`); fans into `TaskSubscription` (matching by `task_id` /
+     * chain) and observer ports (no-op `considerClient`).
+     */
+    dispatchCancelAcked(env) {
+        const payload = env.payload;
+        const event = {
+            kind: 'qar.client.cancel_acked',
+            task_id: payload.task_id,
+            ...(typeof payload.received_by_pod === 'string'
+                ? { receivedByPod: payload.received_by_pod }
+                : {}),
+            ...(typeof payload.owning_pod === 'string'
+                ? { owningPod: payload.owning_pod }
+                : {}),
+            ...(typeof payload.cancel_reason === 'string'
+                ? { cancelReason: payload.cancel_reason }
+                : {}),
+            ...(typeof payload.expected_terminal_within_s === 'number'
+                ? { expectedTerminalWithinS: payload.expected_terminal_within_s }
+                : {}),
+        };
+        const snapshot = [...this.subscriptions];
+        for (const sub of snapshot) {
+            if (sub instanceof TaskSubscription) {
+                // Only route to the subscription that owns this task. Other
+                // task subscriptions on the same connection should not see a
+                // cancel-ack for a peer task they don't drive.
+                if (sub.matchesEnvelope(env)) {
+                    sub.considerClient(event);
+                }
+            }
+            else {
+                // Observer ports + raw taps: pass through. `KindObserverPort.considerClient`
+                // is a no-op; `RawSubscription` queues the event for the raw tap so
+                // consumers tapping `client.receive()` see both the wire envelope
+                // (via fanout) AND the typed client event on one iterator.
+                sub.considerClient(event);
+            }
+        }
+    }
+    /**
+     * Flush the paused queue in FIFO order. Stops if the transport closes
+     * mid-drain (a `transport.send` after close would throw and lose the
+     * remaining frames silently). Caller is responsible for ensuring `paused`
+     * is `false` before invoking — this method does not reset the flag.
+     *
+     * Drain failure preserves queue state. The earlier shape ("slice +
+     * clear + iterate") dropped every
+     * REMAINING entry (including their `overrideToSave` metadata) when
+     * `transport.send` threw mid-drain. The post-send-success invariant
+     * says the override write is conditional on wire-success; an entry
+     * that
+     * never reaches the wire MUST stay in the queue so the next drain
+     * (after the transport recovers and `flow.resume` arrives again,
+     * or via the reconnect-loop's eventual retry) can replay it with
+     * the same metadata intact.
+     *
+     * New shape: walk by INDEX without clearing the queue first.
+     *   - For each entry, send + commit override. If both succeed,
+     *     mark the index as drained.
+     *   - If `transport.send` throws OR `canSend()` flips mid-drain,
+     *     stop immediately, splice off only the successfully drained
+     *     prefix. Everything from the failing index onward stays in
+     *     `pausedQueue` for the next drain attempt.
+     *
+     * The naive `while (length > 0) shift()` form is O(n²) because each
+     * `shift()` reindexes the whole array; with a user-configurable cap
+     * the blocking time on a large drain shows up in the inbound-message
+     * handler. Index-walk + single splice at the end keeps the drain O(n).
+     */
+    drainPausedQueue() {
+        if (this.pausedQueue.length === 0)
+            return;
+        let drainedCount = 0;
+        try {
+            for (let i = 0; i < this.pausedQueue.length; i += 1) {
+                if (!this.canSend())
+                    break;
+                const entry = this.pausedQueue[i];
+                this.transport.send(entry.json);
+                // Commit the cold-address override to {@link taskSessions} now
+                // that the queued frame
+                // actually landed on the wire. Doing this at queue-push time
+                // would pollute the map with sessions that never reached the
+                // server if the transport dropped mid-pause.
+                if (entry.overrideToSave !== undefined) {
+                    this.taskSessions.set(entry.overrideToSave.taskId, entry.overrideToSave.sessionId);
+                    // Track the drained message_id → task_id (with sessionId for
+                    // generation-safety) so a subsequent `session_mismatch` can
+                    // prune the polluted entry only when it hasn't been
+                    // superseded.
+                    this.outboundOverrideRefs.set(entry.messageId, {
+                        taskId: entry.overrideToSave.taskId,
+                        sessionId: entry.overrideToSave.sessionId,
+                    });
+                }
+                drainedCount += 1;
+            }
+        }
+        finally {
+            // Splice off ONLY the successfully drained prefix. Any entry
+            // from `drainedCount` onward stays in the queue — its
+            // `overrideToSave` metadata is preserved for the next drain.
+            if (drainedCount > 0) {
+                this.pausedQueue.splice(0, drainedCount);
+            }
+        }
+    }
+    fanout(env) {
+        // Snapshot — `consider` may unregister via `close`/`onClose`.
+        const snapshot = [...this.subscriptions];
+        for (const sub of snapshot) {
+            sub.consider(env);
+        }
+    }
+    broadcastClient(ev) {
+        const snapshot = [...this.subscriptions];
+        for (const sub of snapshot) {
+            sub.considerClient(ev);
+        }
+    }
+    /**
+     * Wire-level error from the transport. If the user hasn't disconnected and
+     * we have something worth replaying, kick off the reconnect loop. Otherwise
+     * fail the subscriptions and shut down.
+     *
+     * Re-entrancy: a custom `WSTransport.close()` may synchronously invoke
+     * `handlers.onClose` (the `WSTransport` interface places no async-vs-sync
+     * contract on close-event timing — only that one fires). If we called
+     * `disposeTransportSafely()` while `state` was still `'connected'`, the
+     * synchronous `onClose` would re-enter `transportClosed`, see state still
+     * `'connected'`, and start its own reconnect loop. Then this method would
+     * return and start ANOTHER one. To prevent this, we transition state OUT
+     * of `'connected'` before disposing — any re-entrant `transportClosed` /
+     * `transportFailed` then sees the guard and returns early.
+     */
+    transportFailed(err) {
+        if (this.state !== 'connected')
+            return;
+        // Hold a guard state so any synchronous re-entry from `transport.close()`
+        // sees a non-connected state and bails. We pick `'reconnecting'` directly
+        // — `runReconnectLoop` would set it anyway, and the no-reconnect branch
+        // overrides it via `failHardAndCleanup`.
+        this.state = 'reconnecting';
+        this.disposeTransportSafely();
+        if (this.shouldAttemptReconnect()) {
+            void this.runReconnectLoop(err.message);
+            return;
+        }
+        this.failHardAndCleanup(err);
+    }
+    /**
+     * Transport closed. Clean codes (1000/1001/1005) end the subs cleanly even
+     * if reconnect would otherwise be possible — the server told us to go.
+     * Unexpected codes drop into the same reconnect loop as `transportFailed`.
+     *
+     * Re-entrancy: same guard as `transportFailed` — state transitions before
+     * disposal so a synchronous `onClose` from `transport.close()` can't fire
+     * a second reconnect loop. Clean closes use a separate guard state
+     * (`'disconnecting'` → `'disconnected'`) for the same reason.
+     */
+    transportClosed(code, reason) {
+        if (this.state !== 'connected')
+            return;
+        const cleanClose = code === 1000 || code === 1001 || code === 1005;
+        // Set guard state BEFORE the dispose. Pick the state we'll end up in:
+        // `'disconnected'` for a clean close, `'reconnecting'` otherwise (or
+        // overridden to `'failed'` when no reconnect is warranted).
+        this.state = cleanClose ? 'disconnected' : 'reconnecting';
+        this.disposeTransportSafely();
+        if (cleanClose) {
+            // We already set `state = 'disconnected'`; cleanCloseAndCleanup is
+            // idempotent on that and just runs the cleanup half.
+            this.cleanCloseAndCleanup();
+            return;
+        }
+        if (this.shouldAttemptReconnect()) {
+            void this.runReconnectLoop(`unexpected close (code=${code}, reason=${reason})`);
+            return;
+        }
+        const err = new Error(`WebSocket closed unexpectedly (code=${code}, reason=${reason})`);
+        this.failHardAndCleanup(err);
+    }
+    /**
+     * Reconnect is worth attempting only when there's at least one in-flight
+     * task subscription that can be replayed. A connection with no live tasks
+     * and only raw taps gains nothing from a reconnect — the user can call
+     * `connect()` fresh next time they need it.
+     */
+    shouldAttemptReconnect() {
+        if (this.reconnectMaxAttempts <= 0)
+            return false;
+        for (const sub of this.subscriptions) {
+            if (sub instanceof TaskSubscription && !sub.isTerminated)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Reconnect loop. Backs off exponentially, retries up to `maxAttempts`. On
+     * success: swap the transport, broadcast `qar.client.reconnected`, fire a
+     * `task.resubscribe` per active task. On exhaustion: broadcast
+     * `qar.client.reconnect_failed`, fail every subscription.
+     *
+     * Mid-loop user disconnect is honored — we check `state` after every async
+     * boundary and bail with a clean close.
+     */
+    async runReconnectLoop(initialCause) {
+        this.state = 'reconnecting';
+        this.clearBackpressureState();
+        let cause = initialCause;
+        let lastError;
+        for (let attempt = 1; attempt <= this.reconnectMaxAttempts; attempt++) {
+            const delayMs = this.reconnectInitialBackoffMs *
+                Math.pow(this.reconnectBackoffMultiplier, attempt - 1);
+            this.broadcastClient({
+                kind: 'qar.client.reconnecting',
+                attempt,
+                delayMs,
+                cause,
+            });
+            await this.sleepCancellable(delayMs);
+            if (this.state !== 'reconnecting') {
+                // User called `disconnect()` (state -> 'disconnecting') or something
+                // else tore us down. Walk the cleanup path; subs are still alive
+                // because we deferred their close in `Connection.close()` while
+                // reconnecting was true.
+                this.finalizeDisconnect();
+                return;
+            }
+            try {
+                const newTransport = await this.factory({
+                    url: this.url,
+                    headers: this.headers,
+                    handlers: this.handlers,
+                });
+                if (this.state !== 'reconnecting') {
+                    // Disconnected while the upgrade was in flight — close the new
+                    // transport so we don't leak it, then walk cleanup.
+                    try {
+                        newTransport.close(1000, 'client disconnect');
+                    }
+                    catch {
+                        // best-effort
+                    }
+                    this.finalizeDisconnect();
+                    return;
+                }
+                this.transport = newTransport;
+                this.state = 'connected';
+                this.broadcastClient({ kind: 'qar.client.reconnected', attempt });
+                this.replayActiveTasks();
+                return;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                cause = lastError.message;
+            }
+        }
+        // Max attempts exhausted — give up.
+        this.broadcastClient({
+            kind: 'qar.client.reconnect_failed',
+            attempts: this.reconnectMaxAttempts,
+            ...(lastError !== undefined ? { lastError: lastError.message } : {}),
+        });
+        this.state = 'failed';
+        const failure = new Error(`Reconnect failed after ${this.reconnectMaxAttempts} attempts` +
+            (lastError !== undefined ? `: ${lastError.message}` : ''));
+        for (const sub of [...this.subscriptions]) {
+            sub.fail(failure);
+        }
+        this.subscriptions.clear();
+    }
+    /**
+     * For each active task subscription, send a `task.resubscribe` envelope
+     * using its `lastSeenMessageId` as the anchor. The new envelope's id is
+     * stitched into the subscription's chain so the server's replayed
+     * envelopes route back transparently.
+     *
+     * **Active-subscription state machine.** A `TaskSubscription`
+     * registered in `this.subscriptions` can be in one of three states at
+     * any point in a connection's lifetime:
+     *
+     *   1. **pre-admission** — `tasks.start` sent its outbound envelope on
+     *      the wire and the SDK eagerly registered the subscription so
+     *      inbound routing can find it. The server-derived `session_id`
+     *      is NOT yet in {@link taskSessions} because no `task.started`
+     *      ack has been observed. `currentTaskId` IS set (derived from
+     *      `task.start.message_id` per the wire contract `task_id ==
+     *      task.start.message_id`).
+     *   2. **admitted** — the `task.started` ack landed; the canonical
+     *      `task_id` is in `currentTaskId` and the matching `session_id`
+     *      is pinned in {@link taskSessions}. Resubscribe is fully
+     *      addressable.
+     *   3. **terminated** — `task.done`, server-error, transport-fail,
+     *      or consumer-driven close has flipped `isTerminated` true.
+     *      `onClose` has already unsubscribed; subs in this state should
+     *      not be in the iterating snapshot.
+     *
+     * `replayActiveTasks` must handle states (1) and (2) explicitly.
+     * State (1) is **unrecoverable** per the session-identity contract:
+     * without an in-memory `session_id`, the SDK cannot construct a
+     * wire-valid `task.resubscribe` for the server's pre-merge
+     * bind-and-derive ingress (the resubscribe envelope MUST carry the
+     * correct `session_id` field per the QAR wire schema).
+     *
+     * **Implementation note.** The implementation pre-checks the per-Task
+     * session map BEFORE attempting the wire send. A state-(1) sub is
+     * failed with a freshly-constructed `QodoColdAddressError` whose
+     * stack starts cleanly inside `replayActiveTasks` — no wire
+     * round-trip is attempted; the failure is local, typed, and
+     * origin-traceable. An earlier implementation called
+     * {@link sendEnvelope} first and relied on the synchronous throw
+     * from {@link resolveOutboundSessionId} to route the failure into
+     * `sub.fail(err)` — functionally correct but the thrown error
+     * carried a misleading stack (the wire-send frames). The current
+     * pre-check approach surfaces a typed local failure instead.
+     * The consumer-facing API surface is unchanged: state-(1) subs still
+     * surface `QodoColdAddressError` on their iterator. Lost-ack
+     * idempotent retry (re-issuing the original `task.start` on the new
+     * transport with the same idempotency-key) lives at the layer
+     * above; the raw `Connection` ships the typed failure.
+     *
+     * Every `TaskSubscription` carries a known `task_id` from construction:
+     * `tasks.continue` / `tasks.cancel` / `tasks.resubscribe` receive it from
+     * the caller, and `tasks.start` derives it from the outbound
+     * `task.start.message_id`. The `currentTaskId === undefined` case is
+     * therefore unreachable here — we keep an invariant assertion rather
+     * than the prior "in-flight task is unrecoverable" `sub.fail` path.
+     */
+    replayActiveTasks() {
+        for (const sub of [...this.subscriptions]) {
+            if (!(sub instanceof TaskSubscription))
+                continue;
+            if (sub.isTerminated)
+                continue;
+            const taskId = sub.currentTaskId;
+            if (taskId === undefined) {
+                // Invariant violation — see method comment. Fail the subscription so
+                // the consumer's iterator doesn't hang silently, but this path should
+                // never execute in practice.
+                const dead = sub;
+                queueMicrotask(() => {
+                    if (!dead.isTerminated) {
+                        dead.fail(new Error('Invariant: TaskSubscription has no task_id at reconnect — task.start should derive task_id from the outbound message_id.'));
+                    }
+                });
+                continue;
+            }
+            // Pre-admission shortcut: a sub with a `task_id` (derived from
+            // `task.start.message_id`) but NO pinned `session_id` in
+            // {@link taskSessions} is in state (1) — `task.started` never
+            // landed before the drop. Fail it directly with a typed
+            // `QodoColdAddressError` whose stack originates here rather than
+            // routing through the wire-encoder's throw. See the JSDoc above
+            // for the rationale.
+            if (this.taskSessions.get(taskId) === undefined) {
+                sub.fail(new QodoColdAddressError('task', taskId));
+                continue;
+            }
+            const sinceMessageId = sub.lastSeenMessageId;
+            try {
+                const messageId = this.sendEnvelope({
+                    kind: 'task.resubscribe',
+                    payload: {
+                        task_id: taskId,
+                        since_message_id: sinceMessageId ?? null,
+                    },
+                });
+                sub.attachOutboundMessageId(messageId);
+            }
+            catch (err) {
+                // Defensive backstop. The pre-check above eliminates the
+                // QodoColdAddressError case, but `sendEnvelope` can still raise
+                // on (a) transport mid-call disconnects (rare — the upgrade
+                // succeeded one tick ago) or (b) a {@link canSend} race where
+                // the transport closed between upgrade and send. Surface the
+                // failure to the one subscription and let the others continue.
+                sub.fail(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+    }
+    cleanCloseAndCleanup() {
+        this.state = 'disconnected';
+        this.clearBackpressureState();
+        this.clearTerminalState();
+        this.clearPendingTimers();
+        for (const sub of [...this.subscriptions]) {
+            sub.close();
+        }
+        this.subscriptions.clear();
+    }
+    failHardAndCleanup(err) {
+        this.state = 'failed';
+        this.clearBackpressureState();
+        this.clearTerminalState();
+        this.clearPendingTimers();
+        for (const sub of [...this.subscriptions]) {
+            sub.fail(err);
+        }
+        this.subscriptions.clear();
+    }
+    /**
+     * Walk the user-initiated disconnect path from inside the reconnect loop.
+     * The subs are still registered (we deferred their close); end them
+     * cleanly so `for await` consumers see `done: true` rather than an error.
+     */
+    finalizeDisconnect() {
+        this.state = 'disconnected';
+        this.clearBackpressureState();
+        this.clearTerminalState();
+        this.clearPendingTimers();
+        for (const sub of [...this.subscriptions]) {
+            sub.close();
+        }
+        this.subscriptions.clear();
+    }
+    disposeTransportSafely() {
+        try {
+            this.transport.close();
+        }
+        catch {
+            // see comments above — best-effort.
+        }
+    }
+    clearPendingTimers() {
+        for (const entry of this.pendingSleeps) {
+            clearTimeout(entry.timer);
+            entry.resolve();
+        }
+        this.pendingSleeps.clear();
+    }
+    /**
+     * Sleep for `ms` milliseconds, cancellable by `clearPendingTimers`. Returns
+     * even if the timer is cleared early — the caller checks `state` after the
+     * await to decide whether to proceed. Cancelling resolves the Promise
+     * rather than rejecting it: cancellation is a flow-control signal, not an
+     * error, and the reconnect loop's post-await state check handles it.
+     */
+    sleepCancellable(ms) {
+        return new Promise((resolve) => {
+            const entry = {
+                timer: setTimeout(() => {
+                    this.pendingSleeps.delete(entry);
+                    resolve();
+                }, ms),
+                resolve,
+            };
+            this.pendingSleeps.add(entry);
+        });
+    }
+}
+const ENVELOPE_KINDS = new Set([
+    'task.start',
+    'task.started',
+    'task.continue',
+    'task.cancel',
+    'task.canceling',
+    'task.resubscribe',
+    'task.delta',
+    'task.done',
+    // Cold-start primitive admit/ack pair. Inbound parser must accept
+    // `task.force_resumed` (the ack) or it falls through to the synthetic
+    // `envelope_parse_error` path and the `tasks.forceResume` Promise
+    // hangs. `task.forceResume` is included for symmetry — it's a
+    // client→server kind but server-side echo / loopback tests + raw
+    // taps (`client.receive()`) still parse it.
+    'task.forceResume',
+    'task.force_resumed',
+    'tool.request',
+    'tool.response',
+    'state.update',
+    'agent.spawn',
+    'bulletin.post',
+    'artifact.add',
+    'flow.pause',
+    'flow.resume',
+    'error',
+]);
+/**
+ * Decode a wire frame into an `Envelope`. Throws if the JSON doesn't shape-match
+ * the discriminated union — the connection turns these into a synthetic `error`
+ * envelope so the frame isn't silently dropped.
+ */
+function parseEnvelope(text) {
+    const raw = JSON.parse(text);
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error('envelope: expected JSON object');
+    }
+    const obj = raw;
+    if (typeof obj.kind !== 'string' || !ENVELOPE_KINDS.has(obj.kind)) {
+        throw new Error(`envelope: unknown kind "${String(obj.kind)}"`);
+    }
+    if (typeof obj.message_id !== 'string') {
+        throw new Error('envelope: missing message_id');
+    }
+    if (typeof obj.session_id !== 'string') {
+        throw new Error('envelope: missing session_id');
+    }
+    if (typeof obj.ts !== 'string') {
+        throw new Error('envelope: missing ts');
+    }
+    if (obj.envelope_version !== 1) {
+        throw new Error(`envelope: unsupported envelope_version ${String(obj.envelope_version)}`);
+    }
+    if (typeof obj.payload !== 'object' || obj.payload === null) {
+        throw new Error('envelope: missing payload');
+    }
+    // The shape passes the discriminator gate — we trust the rest. QAR's
+    // server-side validators are the source of truth; any over-strict checks
+    // here would surface as false-positive `envelope_parse_error` events for
+    // forward-compatible additions.
+    return raw;
+}
+const KINDS_WITH_TASK_ID = new Set([
+    'task.started',
+    'task.continue',
+    'task.cancel',
+    'task.canceling',
+    'task.resubscribe',
+    'task.delta',
+    'task.done',
+    // `task.force_resumed` carries `task_id` on its payload (the recovered
+    // task's id). Membership here lets the `task_id` fallback in
+    // {@link TaskSubscription.matches} ABSORB the ack — e.g. so a cold
+    // `task.resubscribe` that replays a buffered `task.force_resumed` (foreign
+    // parent) still seeds the subscription chain for the events that follow.
+    // Absorption is all the fallback grants: whether the ack drives
+    // admission-resolution / one-shot close is gated separately on a chain
+    // match in {@link TaskSubscription.consider} (`matchedByChain`), so a
+    // fallback-only match never collapses an unrelated in-flight stream. Same
+    // contract applies to `task.started` above.
+    'task.force_resumed',
+]);
+function envelopeHasTaskId(env) {
+    return KINDS_WITH_TASK_ID.has(env.kind);
+}
+const TASK_EVENT_KINDS = new Set([
+    'task.delta',
+    'task.done',
+    'tool.request',
+    'state.update',
+    'agent.spawn',
+    'bulletin.post',
+    'artifact.add',
+    'flow.pause',
+    'flow.resume',
+    'error',
+]);
+function isTaskEvent(env) {
+    return TASK_EVENT_KINDS.has(env.kind);
+}
+function pickPositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1)
+        return fallback;
+    return value;
+}
+/**
+ * Like {@link pickPositiveInt} but allows `0` — used for `reconnect.maxAttempts`
+ * where `0` is a meaningful configuration ("don't reconnect, fail immediately
+ * on transport drop"). Negatives, fractions, and non-integers still fall back.
+ */
+function pickNonNegativeInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0)
+        return fallback;
+    return value;
+}
+function pickPositiveNumber(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0)
+        return fallback;
+    return value;
+}
+//# sourceMappingURL=connection.js.map