@superblocksteam/gateway 2.0.0-SNAPSHOT.2161f9a02a4eb5d8

package/dist/sabs/websocket-session-peer.js

@@ -0,0 +1,3241 @@
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+import { createISocketClient, ISocket, SocketHeartbeat, } from "@superblocksteam/shared";
+import { pickOrchestratorBaseUrl } from "../agents/resolve-orchestrator-url.js";
+import { pickEditorProfileKey } from "../integrations/profile-key.js";
+import { HttpOrchestratorClient, } from "../orchestrator/client.js";
+import { recordCheckpointOutcome, recordGatewayFault, } from "../telemetry/metrics.js";
+import { sanitizeAgentFacingText } from "./agent-facing-text.js";
+import { AppState } from "./app-state.js";
+import { buildBrowserContext } from "./browser-context.js";
+import { createEditorClientMethods, loadIntegrationsForPrompt, } from "./editor-client-methods.js";
+import { EditorSocket } from "./editor-socket.js";
+import { appendRecentToolRun, buildRecentToolRun } from "./recent-tool-runs.js";
+import { PromptNotSentError, } from "./session-peer.js";
+import { DEFAULT_SETTLE_MS, TurnCollector } from "./turn-collector.js";
+const RELEASE_TURN_LOCK_METHOD = "editor.releaseTurnLock";
+function editorStructureScopeKey(applicationId, branch) {
+    return `${applicationId}\u0000${branch?.trim() ?? ""}`;
+}
+/**
+ * Whole budget for connecting and getting the prompt acknowledged, so a
+ * session that accepts the socket but never answers cannot strand the MCP call
+ * waiting on it.
+ *
+ * A sandbox that has gone idle since the app was created needs most of a
+ * minute before it acknowledges anything, and the first edit after that pause
+ * was failing on a tighter budget only to succeed on the retry.
+ */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * The sandbox binds its HTTP port before it attaches the socket handler, and
+ * an upgrade arriving in that window gets no response at all rather than a
+ * refusal. One long attempt would spend the whole budget waiting on a session
+ * that was seconds from ready, so each attempt is short and retried.
+ */
+const DEFAULT_CONNECT_ATTEMPT_TIMEOUT_MS = 3_000;
+const CONNECT_RETRY_DELAY_MS = 500;
+/**
+ * How long a lost liveness beat has to stay lost before the turn running on
+ * that socket is given up on.
+ *
+ * The beat is declared lost for *reporting* after a couple of genuine misses,
+ * which is the right threshold for a diagnostic and the wrong one for ending a
+ * turn: a sandbox that misses two beats and then answers is recovering, not
+ * gone. This is the second gate — the silence has to outlast it, and any beat
+ * that succeeds clears it. Two missed beats on the default interval plus this
+ * is a couple of minutes, against a ten-minute turn budget.
+ */
+const DEFAULT_BEAT_LOST_GRACE_MS = 60_000;
+const DEFAULT_BEAT_HEALTH_TIMEOUT_MS = 3_000;
+async function liveEditIsHealthy(input) {
+    if (!input.sessionToken) {
+        return false;
+    }
+    try {
+        const response = await fetch(new URL("/_sb_health", input.liveEditUrl).toString(), {
+            headers: {
+                Authorization: `Bearer ${input.sessionToken}`,
+            },
+            signal: AbortSignal.timeout(DEFAULT_BEAT_HEALTH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const body = await response.json();
+        return (typeof body === "object" &&
+            body !== null &&
+            "applicationId" in body &&
+            body.applicationId === input.applicationId &&
+            "status" in body &&
+            body.status === "healthy");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Consecutive upgrade rejections from one host before asking where the live
+ * edit went. More than one, so an ingress route that briefly answers for a pod
+ * that is not up yet is waited out rather than read as a move.
+ *
+ * Exported so a test can say "kept trying past the point where it asked"
+ * without restating the number.
+ */
+export const HOST_REJECTIONS_BEFORE_RERESOLVE = 2;
+/**
+ * How many times one connect may ask where the session went.
+ *
+ * Bounded because each ask is a Superblocks API round trip, and spaced by a
+ * fresh rejection streak so the asks land across the connect window rather
+ * than all at the start of it - SABS needs time to notice the pod is gone
+ * before it can answer with anywhere different.
+ */
+export const MAX_RERESOLVES_PER_OPEN = 3;
+/** Match AppManager's idle window so a quiet Claude turn does not outlive it. */
+const DEFAULT_IDLE_MS = 30 * 60 * 1000;
+/**
+ * Grace period between a turn settling and the gateway socket being dropped.
+ *
+ * Long enough for the checkpoint and any trailing pushes to land, short enough
+ * that the sandbox is not held open by a peer with nothing left to do.
+ *
+ * Must outlast {@link DEFAULT_SETTLE_MS}. The teardown this release leads to is
+ * read as a dead live edit by any turn whose `completed` had not settled yet,
+ * so releasing inside the settle window would report healthy builds as
+ * failures. `releases the socket only after a completed has had its settle
+ * window` holds this.
+ */
+export const DEFAULT_RELEASE_AFTER_TURN_MS = 30_000;
+/**
+ * Refresh connectLiveEdit while held so local AppManager lastAccessed does not
+ * age out under a long Clark build with no MCP traffic.
+ */
+const DEFAULT_KEEPALIVE_MS = 5 * 60 * 1000;
+/**
+ * How often the held socket proves the gateway is still alive.
+ *
+ * The sandbox expires a gateway peer's liveness signal if nothing refreshes it,
+ * so this has to be comfortably inside that window — a build that runs for
+ * twenty quiet minutes must not look abandoned — while still letting a peer that
+ * really died stop protecting the sandbox promptly.
+ */
+const DEFAULT_HEARTBEAT_MS = 30 * 1000;
+/**
+ * How long one beat waits for its answer before it counts as missed.
+ *
+ * Deliberately far below the prompt budget. `requestWithTracing` takes no
+ * per-request deadline, so a beat issued on the held client inherits the
+ * socket's own — the whole prompt timeout — and a beat that waits that long
+ * cannot report a miss inside any window a caller waits in, nor before three
+ * more beats have been sent after it.
+ */
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15 * 1000;
+/**
+ * Shortest wait for an unanswered beat worth putting in a death report, since
+ * the report states it in whole seconds and anything under one is what a
+ * healthy round trip looks like at the instant a socket closes.
+ */
+const MIN_REPORTED_BEAT_WAIT_MS = 1_000;
+/**
+ * How long to wait after Clark acks the prompt for the generation turn to
+ * reach a settled terminal state (completed after quiet settle, cancelled,
+ * or needs_decision).
+ */
+const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * What a caller is told when the live edit backing its turn is gone. The cause
+ * is appended by whichever path noticed: a close code and heartbeat account
+ * when the socket dropped, nothing when SABS said so outright.
+ */
+const LIVE_EDIT_TERMINATED_REPLY = "The Superblocks live-edit session terminated before the turn finished, so nothing was built. Send the prompt again to start it over.";
+/**
+ * How long a turn waits for Clark's first push before suspecting the sandbox is
+ * not reporting into this socket.
+ *
+ * The dev server routes a turn's pushes to the peer that asked for it, so the
+ * usual cause of silence here is this connection itself — dropped, or opened
+ * against a session that had already lost the turn. A healthy turn reports
+ * `generating` within a second of the acknowledgment, so this window is
+ * silence, not slowness.
+ */
+const DEFAULT_PUSH_WAIT_MS = 10_000;
+/** How long to wait for the flushed pushes after reattaching. */
+const DEFAULT_REATTACH_WAIT_MS = 20_000;
+/**
+ * How long a turn keeps trying to get back onto its live edit after a close it
+ * did not ask for.
+ *
+ * A close is not an answer about the sandbox: the same 1006 covers a proxy
+ * idle-reap, a load-balancer hiccup and a dev server that died. Reaching the
+ * live edit again settles it, and failing to reach it for this long is the
+ * evidence the close itself never was.
+ */
+const DEFAULT_RECONNECT_GRACE_MS = 20_000;
+/**
+ * How many times one turn goes back for a live edit that keeps dropping it.
+ *
+ * A sandbox that closes every socket it accepts is not one a turn can finish
+ * on, and each attempt is cheap enough that an uncapped retry would chase it
+ * for the whole turn budget.
+ */
+const DEFAULT_RECONNECT_ATTEMPTS = 3;
+/**
+ * After the job settles, how long to wait for the dev server to finish flushing
+ * Clark's files before giving up on checkpointing them.
+ */
+const DEFAULT_READY_WAIT_MS = 30_000;
+const PENDING_START_POLL_INTERVAL_MS = 250;
+/**
+ * The role the dev server classifies this connection as. A gateway peer gets
+ * Clark's pushes for the turns it starts and its own sandbox-liveness signal,
+ * without being counted as a browser editor: it never takes the editor
+ * binding, and a user's own tab keeps its presence and its lock.
+ *
+ * Offering the role is not the same as being given it. A `ws` server echoes the
+ * first subprotocol it was offered whether or not it knows the name, so a dev
+ * server that predates the role accepts this socket, answers `gateway`, and
+ * still classifies it as a library socket that never receives Clark's pushes.
+ * The handshake cannot tell the two apart; the acknowledgment can, because only
+ * a server that routed the turn to this peer can name the turn back. See
+ * {@link WebSocketSessionPeer.headlessTurnHandle}.
+ */
+const GATEWAY_PROTOCOL = "gateway";
+const DEFAULT_LLM = {
+    coreModel: "claude-sonnet-4-5",
+    provider: "bedrock",
+};
+/**
+ * Reads a {@link LiveEdit} off the caller-facing pair, which names the same two
+ * things with the prompt's field names.
+ */
+function liveEditOf(source) {
+    return {
+        ...(source.liveEditId ? { id: source.liveEditId } : {}),
+        url: source.liveEditUrl,
+    };
+}
+function isBrowserObserverEvent(event) {
+    return ((event.kind === "message" &&
+        event.message.gatewayObserverSource === "browser") ||
+        (event.kind === "generation_state" &&
+            event.gatewayObserverSource === "browser"));
+}
+export function buildSessionUrl(input) {
+    // liveEditUrl is server-sourced (connectLiveEdit), not caller-supplied, so a
+    // host allowlist would mostly duplicate the Superblocks API's own trust
+    // boundary. The scheme check still matters: anything other than http(s)
+    // would let a compromised response smuggle the session token off-protocol.
+    const url = new URL("/sb-updates", input.liveEditUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Prompt forward failed: live-edit URL must be http(s), got ${url.protocol}`);
+    }
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("peerId", input.peerId);
+    if (input.userId) {
+        url.searchParams.set("userId", input.userId);
+    }
+    url.searchParams.set("applicationId", input.applicationId);
+    return url;
+}
+function isAuthRejection(error) {
+    return error.code === 401 || error.code === 403;
+}
+/**
+ * Whether a host answered the upgrade by denying it serves this live edit, as
+ * opposed to not answering it.
+ *
+ * The difference is the whole reason the connect loop retries. A booting
+ * sandbox binds its port before attaching the socket handler and drops the
+ * upgrade in silence, so a cold start looks like an attempt timeout and is
+ * worth waiting out on the same host. A status in the 404 family is something
+ * answering on that host and saying the session is not there - which is what a
+ * stale session -> host binding looks like from the outside, and no amount of
+ * retrying the same host will fix it.
+ *
+ * 5xx is deliberately not included: that is the session's own host reporting it
+ * is not ready yet, which is the retry case, not a move.
+ */
+function isHostRejection(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // The wording is ws's own for a non-101 response to the handshake.
+    const status = /Unexpected server response: (\d{3})/.exec(message)?.[1];
+    return status === "404" || status === "410";
+}
+/**
+ * ISocket gives up on an unanswered request in two different wordings —
+ * "Request timed out after N seconds" when its own no-response timer fires,
+ * and "Abort timeout" when the underlying signal aborts first. Both mean the
+ * same thing to a caller, and neither says what to do about it.
+ */
+function isTimeout(error) {
+    return /timed out|timeout/i.test(error.message ?? "");
+}
+function isRemoteRejection(error) {
+    // ISocket reserves 7-10 for timeout, connection close, abort, and a request
+    // made after close. Every other numbered code arrived in a response.
+    return (error.code !== undefined &&
+        error.code !== 7 &&
+        error.code !== 8 &&
+        error.code !== 9 &&
+        error.code !== 10);
+}
+function isSocketOpen(ws) {
+    return ws.readyState === WebSocket.OPEN;
+}
+/**
+ * Says what a rejected socket request actually failed on.
+ *
+ * Every rejection this client produces is a plain `{ code, message }` object
+ * and never an `Error` — a refusal from the wire, a no-response timeout, and a
+ * closed connection all take that shape. `String()` on one of those yields
+ * "[object Object]" and throws away the only account of the cause there is.
+ */
+function describeSocketError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error !== "object" || error === null) {
+        return String(error);
+    }
+    const { code, message } = error;
+    if (typeof message === "string" && message.length > 0) {
+        return code === undefined ? message : `${message} (code ${code})`;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+function checkpointFailure(error) {
+    const detail = typeof error === "object" && error !== null
+        ? error
+        : undefined;
+    const rawMessage = error instanceof Error
+        ? error.message
+        : typeof detail?.message === "string" && detail.message.length > 0
+            ? detail.message
+            : describeSocketError(error);
+    const message = sanitizeAgentFacingText(rawMessage).slice(0, 500);
+    const code = typeof detail?.code === "number" ? detail.code : undefined;
+    const status = typeof detail?.status === "number" ? detail.status : undefined;
+    const category = status === 408 || status === 504 || /timed out|timeout/i.test(message)
+        ? "timeout"
+        : status === 401 ||
+            status === 403 ||
+            code === 401 ||
+            code === 403 ||
+            /\b(?:401|403)\b|unauthoriz|forbidden/i.test(message)
+            ? "authentication"
+            : status === 409 || code === 409 || /\b409\b|conflict/i.test(message)
+                ? "conflict"
+                : "downstream";
+    return {
+        category,
+        ...(code === undefined ? {} : { code }),
+        message,
+        ...(status === undefined ? {} : { status }),
+    };
+}
+function normalizeCheckpointWarning(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const warning = value;
+    if (warning.code !== "draft_state_cleanup_failed" ||
+        typeof warning.message !== "string") {
+        return undefined;
+    }
+    const message = sanitizeAgentFacingText(warning.message).trim().slice(0, 500);
+    if (!message) {
+        return undefined;
+    }
+    return {
+        code: "draft_state_cleanup_failed",
+        message,
+    };
+}
+/**
+ * What the socket said on its way out, appended to the disconnect reply.
+ *
+ * The close frame is the only account of why a turn died that reaches the
+ * caller: 1006 is a proxy or network kill that sent no frame at all, 1001 a
+ * sandbox going away, and an application code is a cause the dev server chose
+ * to name. This process's console is not visible to whoever asked for the
+ * build, so a bare "it disconnected" leaves them nothing to act on.
+ */
+function describeClose(close) {
+    const parts = [];
+    if (close.code !== undefined) {
+        parts.push(`code ${close.code}`);
+    }
+    if (close.reason) {
+        parts.push(close.reason);
+    }
+    const closed = parts.length > 0 ? ` The session closed with ${parts.join(": ")}.` : "";
+    // A death that sends no close frame reports only 1006, which names nothing.
+    // The error that arrived just before it is the account of what happened.
+    return close.error ? `${closed} Socket error: ${close.error}.` : closed;
+}
+/**
+ * Whether the close is the live edit naming its own end.
+ *
+ * 4000-4999 is the WebSocket private range: nothing but the peer's own code
+ * puts a value there, so a close carrying one is a statement - a lost live-edit
+ * lock, a deliberate shutdown. Every other code belongs to the transport, and
+ * 1006 in particular is what a death with no close frame reports, which is
+ * equally what a reaped proxy connection reports. Those say the socket ended;
+ * only the application range says the live edit did.
+ */
+function isApplicationClose(close) {
+    return close.code !== undefined && close.code >= 4000 && close.code <= 4999;
+}
+/**
+ * How the liveness beat was faring when the socket went, for the reply.
+ *
+ * Beats landing right up to the close mean the connection was carrying traffic
+ * and cannot have been reaped for idleness, which points at the sandbox rather
+ * than the path to it. A run of failures says the opposite. The close code
+ * distinguishes neither on its own.
+ *
+ * Several of these counts can stand at once, because only an answered beat
+ * clears the account: a refusal answers one beat and leaves every record of
+ * what went missing behind it. The order below is therefore most-specific
+ * first, and a stated cause outranks an inferred one - a refusal is the only
+ * outcome where the peer said why, so it is reported ahead of a silence that
+ * merely happened to look excusable.
+ */
+function describeHeartbeat(heartbeat, at) {
+    return (describeSettledBeats(heartbeat, at) + describeOutstandingBeat(heartbeat, at));
+}
+/**
+ * The beat that never got an answer because the socket went first.
+ *
+ * Appended to whichever clause fired rather than being one of them: an
+ * outstanding beat is a fact about the end of the connection, and it stands
+ * alongside whatever the settled beats say. A refusal followed by silence is a
+ * different death from refusals arriving right up to the close, and the
+ * settled counts alone cannot tell those apart - only an answered beat clears
+ * them, and this beat was never answered at all.
+ *
+ * Sub-second waits say nothing and are left out. A beat is in flight for
+ * exactly as long as an answer takes, so a close landing inside a healthy round
+ * trip would otherwise report a silence of "0s" and indict the request channel
+ * for the very exchange that proves it works.
+ */
+function describeOutstandingBeat(heartbeat, at) {
+    if (heartbeat.pendingSince === undefined) {
+        return "";
+    }
+    const waitingMs = at - heartbeat.pendingSince;
+    if (waitingMs < MIN_REPORTED_BEAT_WAIT_MS) {
+        return "";
+    }
+    const seconds = Math.round(waitingMs / 1000);
+    return ` A beat sent ${seconds}s earlier had still not been answered.`;
+}
+function describeSettledBeats(heartbeat, at) {
+    if (heartbeat.refusals > 0) {
+        const beats = heartbeat.refusals === 1 ? "beat" : "beats";
+        // The refusal's own reason rather than `lastError`: an unanswered beat
+        // after the refusal overwrites that with its own cause while leaving
+        // `refusals` standing, so reading it here would put a timeout's message in
+        // the peer's mouth.
+        const stated = heartbeat.lastRefusalError ?? heartbeat.lastError;
+        const cause = stated ? ` (${stated})` : "";
+        // Reported ahead of the silence counts, and alongside them rather than
+        // instead of them. A refusal is an answer: the connection worked and the
+        // peer named its own reason for the turn dying, which no inferred silence
+        // outranks. But a refusal clears nothing, so "refused, then went quiet" is
+        // a different death from "refusing right up to the close" and the caller
+        // needs both halves to tell them apart.
+        const silence = heartbeat.failures > 0
+            ? ` ${heartbeat.failures} later ${heartbeat.failures === 1 ? "beat" : "beats"} went unanswered.`
+            : "";
+        return ` ${heartbeat.refusals} liveness ${beats} came back refused${cause}.${silence}`;
+    }
+    if (heartbeat.failures > 0) {
+        const beats = heartbeat.failures === 1 ? "beat" : "beats";
+        const cause = heartbeat.lastError ? ` (${heartbeat.lastError})` : "";
+        return ` ${heartbeat.failures} liveness ${beats} failed before it${cause}.`;
+    }
+    if (heartbeat.lapses > 0) {
+        const beats = heartbeat.lapses === 1 ? "beat" : "beats";
+        // A silent request channel on a connection that was demonstrably carrying
+        // traffic. Reporting this as a plain failure would point at the network,
+        // which is the one thing it rules out.
+        return ` ${heartbeat.lapses} liveness ${beats} went unanswered while the socket was still delivering data.`;
+    }
+    if (heartbeat.lastSuccessAt !== undefined) {
+        const seconds = Math.round((at - heartbeat.lastSuccessAt) / 1000);
+        return ` The last liveness beat succeeded ${seconds}s earlier.`;
+    }
+    if (heartbeat.sent > 0) {
+        const beats = heartbeat.sent === 1 ? "beat" : "beats";
+        return ` ${heartbeat.sent} liveness ${beats} sent, none answered.`;
+    }
+    return " No liveness beat had run yet.";
+}
+function decisionFields(decision) {
+    return decision ? { decision } : {};
+}
+async function attempt(url, timeoutMs, onSocketError) {
+    const socket = new WebSocket(url, GATEWAY_PROTOCOL);
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            socket.terminate();
+            reject(new Error("session is not accepting sockets yet"));
+        }, timeoutMs);
+        const settle = (outcome) => {
+            clearTimeout(timer);
+            socket.off("open", onOpen);
+            socket.off("error", onError);
+            outcome();
+        };
+        const onOpen = () => settle(() => {
+            // ISocket attaches its own handlers a tick later. An 'error' landing in
+            // that gap would have no listener, and node throws on an unhandled
+            // emitter 'error' rather than reporting it to the caller. Recording it
+            // rather than discarding it is what makes a later 1006 explainable.
+            socket.on("error", onSocketError);
+            resolve(socket);
+        });
+        const onError = (error) => settle(() => reject(error));
+        socket.once("open", onOpen);
+        socket.once("error", onError);
+    });
+}
+/**
+ * Waits for a lookup, but never past the deadline the caller is already bound
+ * by, and never raises.
+ *
+ * The connect loop clamps every socket attempt to what is left of its budget;
+ * a re-resolve is a Superblocks API round trip made from inside that loop and
+ * has to answer to the same clock. A hung one would otherwise hold the loop
+ * open for as long as it hangs, and `open` would return later than the
+ * deadline it promised by that much. Giving up on it leaves the host already
+ * in hand, which is the same fallback a failed lookup gets.
+ */
+async function withinDeadline(lookup, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        return undefined;
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            lookup.catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), remaining);
+            }),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+async function beforePromptDeadline(work, deadline, signal) {
+    if (signal?.aborted) {
+        throw new PromptNotSentError("Prompt forward cancelled before the live-edit request was sent", signal.reason);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        throw new PromptNotSentError("Prompt forward timed out before the live-edit request was sent");
+    }
+    let timer;
+    let onAbort;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new PromptNotSentError("Prompt forward timed out before the live-edit request was sent")), remaining);
+            }),
+            ...(signal
+                ? [
+                    new Promise((_resolve, reject) => {
+                        onAbort = () => reject(new PromptNotSentError("Prompt forward cancelled before the live-edit request was sent", signal.reason));
+                        signal.addEventListener("abort", onAbort, { once: true });
+                    }),
+                ]
+                : []),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        if (onAbort) {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+async function open(url, attemptTimeoutMs, deadline, onSocketError, 
+/**
+ * Where the live edit is now, asked for only once and only when the host in
+ * hand is denying it. Absent keeps the prompt on the host it was given, and
+ * so does a hook that answers with nothing or fails: the host already in hand
+ * is the better fallback than abandoning the attempt.
+ */
+nextHost) {
+    let current = url;
+    let lastError;
+    let consecutiveRejections = 0;
+    let asks = 0;
+    while (Date.now() < deadline) {
+        try {
+            return await attempt(current, Math.min(attemptTimeoutMs, deadline - Date.now()), onSocketError);
+        }
+        catch (error) {
+            lastError = error;
+            consecutiveRejections = isHostRejection(error)
+                ? consecutiveRejections + 1
+                : 0;
+            // Asked for only after the host has said no more than once: a single
+            // rejection can be an ingress route that exists a moment before the pod
+            // behind it does. Asked again only after another full streak, and never
+            // more than a few times per open.
+            //
+            // The spacing is the point, not politeness. The first ask lands about a
+            // second after the resolve that produced this host, often before SABS
+            // has observed the pod is gone, so it can hand back the same dead
+            // binding. Asking once and never again would spend the rest of the
+            // budget on a host already known to be denying the session.
+            if (nextHost &&
+                asks < MAX_RERESOLVES_PER_OPEN &&
+                consecutiveRejections >= HOST_REJECTIONS_BEFORE_RERESOLVE) {
+                asks += 1;
+                // Re-armed: the next ask waits for a fresh streak rather than
+                // following on the very next rejection.
+                consecutiveRejections = 0;
+                const moved = await withinDeadline(nextHost(), deadline);
+                if (moved && moved.href !== current.href) {
+                    current = moved;
+                    // Straight to the attempt: the delay below is for a host worth
+                    // asking again, and this is a different one.
+                    continue;
+                }
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                break;
+            }
+            await new Promise((resolve) => setTimeout(resolve, Math.min(CONNECT_RETRY_DELAY_MS, remaining)));
+        }
+    }
+    throw new Error(`Prompt forward timed out: ${current.host} did not accept a live-edit socket (${lastError instanceof Error ? lastError.message : String(lastError)})${current.host !== url.host ? ` after moving from ${url.host}` : ""}`);
+}
+/**
+ * The typed `editor.*` surface for a held session.
+ *
+ * Built per call rather than held on the session because the edit-scoped token
+ * travels with the request, not with the socket: a session outlives the token
+ * a given turn was authorized with.
+ */
+function editorSocket(held, sessionToken) {
+    return new EditorSocket(held.client, () => sessionToken ? `Bearer ${sessionToken}` : undefined);
+}
+export class WebSocketSessionPeer {
+    options;
+    held = new Map();
+    promptStarts = new Map();
+    /**
+     * Every server -> editor method the dev server has called on this peer.
+     * Diagnostic only: it answers "did that push ever arrive" without guessing
+     * from what the collector chose to keep.
+     */
+    inboundMethods = new Set();
+    /**
+     * In-flight opens, so overlapping prompts for one app share a socket instead
+     * of each opening their own and orphaning all but the last.
+     */
+    connecting = new Map();
+    /**
+     * Turns keyed by application. An entry outlives the call that started it and
+     * is kept after finishing so a late poll still learns the outcome; the next
+     * prompt for the same app replaces it.
+     */
+    turns = new Map();
+    /** Browser-owned turns observed over an authenticated held session. */
+    observedTurns = new Map();
+    editorStructureByScope = new Map();
+    /** Facts about an application that outlive any one turn. */
+    appState;
+    constructor(options = {}) {
+        this.options = options;
+        this.appState =
+            options.appState ??
+                new AppState({
+                    ...(options.failedStartTtlMs === undefined
+                        ? {}
+                        : { failedStartTtlMs: options.failedStartTtlMs }),
+                    ...(options.maxFailedStarts === undefined
+                        ? {}
+                        : { maxFailedStarts: options.maxFailedStarts }),
+                    ...(options.pendingStartTtlMs === undefined
+                        ? {}
+                        : { pendingStartTtlMs: options.pendingStartTtlMs }),
+                });
+    }
+    /** The per-application facts this peer writes, for the capability layer. */
+    state() {
+        return this.appState;
+    }
+    recordPendingStart(input) {
+        return this.appState.recordPendingStart(input, {
+            ...(input.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: input.idempotencyKey }),
+            ...(input.retryAction ? { retryAction: input.retryAction } : {}),
+        });
+    }
+    clearPendingStart(input) {
+        this.appState.clearPendingStart(input, input.idempotencyKey, undefined, input.pendingStartToken);
+    }
+    async waitForPendingTurn(input) {
+        for (;;) {
+            const turn = this.turns.get(input.applicationId);
+            if (turn &&
+                turn.revision > input.afterRevision &&
+                (input.idempotencyKey === undefined ||
+                    turn.idempotencyKey === input.idempotencyKey) &&
+                (input.pendingStartToken === undefined ||
+                    turn.pendingStartToken === input.pendingStartToken) &&
+                (input.scope.branch === undefined || input.scope.branch === turn.branch)) {
+                return turn;
+            }
+            if (input.signal?.aborted ||
+                !this.appState.pendingStart(input.scope) ||
+                Date.now() >= input.deadlineAtMs) {
+                return undefined;
+            }
+            await new Promise((resolve) => {
+                const settle = () => {
+                    clearTimeout(timer);
+                    input.signal?.removeEventListener("abort", settle);
+                    resolve();
+                };
+                const timer = setTimeout(settle, Math.min(PENDING_START_POLL_INTERVAL_MS, Math.max(0, input.deadlineAtMs - Date.now())));
+                input.signal?.addEventListener("abort", settle, { once: true });
+            });
+        }
+    }
+    /**
+     * Plan waiting on human approve/refine for this application, if any.
+     */
+    pendingPlan(applicationId, requestedBranch) {
+        return this.appState.pendingPlan(applicationId, requestedBranch);
+    }
+    /**
+     * Full needs_decision payload waiting on a human for this application.
+     */
+    pendingDecision(applicationId, requestedBranch) {
+        return this.appState.pendingDecision(applicationId, requestedBranch);
+    }
+    /**
+     * Remember a turn that never reached Superblocks. See
+     * {@link SessionPeer.recordFailedStart}.
+     */
+    recordFailedStart(input) {
+        const pendingCleared = this.appState.clearPendingStart(input, input.idempotencyKey, undefined, input.pendingStartToken);
+        if (input.pendingStartRequired && !pendingCleared) {
+            return;
+        }
+        const running = this.turns.get(input.applicationId);
+        if (running &&
+            !running.finished &&
+            input.branch === running.branch &&
+            !(input.pendingStartRequired && pendingCleared)) {
+            // This failed prompt did not end the turn already running on its branch.
+            // Keeping its newer revision would hide that turn's eventual outcome.
+            console.warn("gateway clark turn never started, but one is running", {
+                applicationId: input.applicationId,
+                organizationId: input.organizationId,
+                reason: input.reason,
+                userId: input.userId,
+            });
+            return;
+        }
+        console.warn("gateway clark turn never started", {
+            applicationId: input.applicationId,
+            organizationId: input.organizationId,
+            reason: input.reason,
+            userId: input.userId,
+        });
+        this.appState.recordFailedStart(input, {
+            ...(input.decision ? { decision: input.decision } : {}),
+            generationStatus: input.generationStatus ?? "live_edit_terminated",
+            reply: input.reason,
+            ...(input.recoveryAction
+                ? { recoveryAction: input.recoveryAction }
+                : {}),
+            ...(input.retryAction ? { retryAction: input.retryAction } : {}),
+            ...(input.retryable === false ? { retryable: false } : {}),
+            // Nothing ran, so nothing is viewable. Reporting "ready" here is how a
+            // caller comes to show the untouched starter template as the app.
+            viewStatus: "unknown",
+        }, input.revision);
+    }
+    /**
+     * Where this application's turn stands for this caller, read without draining
+     * the activity an {@link WebSocketSessionPeer.awaitTurn} poll is owed.
+     *
+     * A running turn is current. Once it finishes, the newer of that turn and an
+     * unscoped failed start wins; explicit branch reads filter before comparing.
+     * Revisions preserve that ordering even when both events share a clock tick.
+     */
+    turnState(input) {
+        const storedTurn = this.latestTurn(input.applicationId);
+        const turn = storedTurn &&
+            input.branch !== undefined &&
+            input.branch !== storedTurn.branch
+            ? undefined
+            : storedTurn;
+        if (this.appState.pendingStart(input)) {
+            return { phase: "running" };
+        }
+        const failed = this.appState.failedStart(input, turn?.revision);
+        if (failed) {
+            return {
+                ...(failed.branch === undefined ? {} : { branch: failed.branch }),
+                generationStatus: failed.generationStatus,
+                phase: "finished",
+                ...(failed.recoveryAction
+                    ? { recoveryAction: failed.recoveryAction }
+                    : {}),
+                ...(failed.retryable === false ? { reply: failed.reply } : {}),
+                ...(failed.retryAction ? { retryAction: failed.retryAction } : {}),
+                ...(failed.retryable === false ? { retryable: false } : {}),
+            };
+        }
+        if (turn && !turn.finished) {
+            return {
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                phase: "running",
+            };
+        }
+        if (!turn?.finished) {
+            return undefined;
+        }
+        return {
+            ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+            ...(turn.finished.checkpointCommitId
+                ? { checkpointCommitId: turn.finished.checkpointCommitId }
+                : {}),
+            ...(turn.finished.checkpointFailure
+                ? { checkpointFailure: turn.finished.checkpointFailure }
+                : {}),
+            ...(turn.finished.checkpointWarning
+                ? { checkpointWarning: turn.finished.checkpointWarning }
+                : {}),
+            generationStatus: turn.finished.generationStatus,
+            phase: "finished",
+            ...(turn.retryAction ? { retryAction: turn.retryAction } : {}),
+            ...(turn.finished.retryable === false
+                ? { retryable: false }
+                : {}),
+        };
+    }
+    clearPendingPlan(applicationId) {
+        this.appState.clearPending(applicationId);
+    }
+    clearPendingDecision(applicationId) {
+        this.appState.clearPending(applicationId);
+    }
+    isHeld(applicationId) {
+        const entry = this.held.get(applicationId);
+        return Boolean(entry && isSocketOpen(entry.ws));
+    }
+    libraryBrowserContext(applicationId, requestedBranch) {
+        const held = this.held.get(applicationId);
+        if (!held || requestedBranch !== held.branchName) {
+            return undefined;
+        }
+        return this.buildHeldBrowserContext(held);
+    }
+    async holdLiveEdit(input) {
+        const segments = String(input.sessionToken ?? "").split(".").length;
+        if (segments !== 3) {
+            throw new Error(`Live-edit hold failed: the live-edit credential is not a JWT (${segments} segment(s)); the session will reject it`);
+        }
+        if (!input.userId.trim()) {
+            throw new Error("Live-edit hold failed: userId is required to identify who the session is held for");
+        }
+        const expectedTurn = this.turns.get(input.applicationId);
+        this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        const held = await this.ensureHeld({
+            applicationId: input.applicationId,
+            branchName: input.branch,
+            keepalive: input.keepalive,
+            liveEdit: liveEditOf(input),
+            userId: input.userId,
+        }, deadline, expectedTurn);
+        if (input.apiKey) {
+            held.apiKey = input.apiKey;
+        }
+        if (input.organizationId) {
+            held.organizationId = input.organizationId;
+        }
+        held.sessionToken = input.sessionToken;
+        await this.resolveHeldProfileKey(held);
+        await this.resolveHeldOrchestrator(held);
+    }
+    release(applicationId) {
+        const entry = this.held.get(applicationId);
+        if (!entry) {
+            return;
+        }
+        this.drop(entry);
+    }
+    closeAll() {
+        for (const applicationId of [...this.held.keys()]) {
+            this.release(applicationId);
+        }
+    }
+    /**
+     * Sends the prompt and waits for Clark's whole turn.
+     *
+     * Kept for callers with nowhere to poll from — the HTTP capability routes
+     * answer a single request — and implemented on the same engine as
+     * {@link startPrompt} so there is one turn lifecycle, not two.
+     */
+    async forwardPrompt(input) {
+        const started = await this.startPrompt(input);
+        if (started.status === "auth_required") {
+            return started;
+        }
+        const turnTimeoutMs = this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+        const readyWaitMs = this.options.readyWaitMs ?? DEFAULT_READY_WAIT_MS;
+        // The turn's own budget already bounds this; the extra slack covers the
+        // checkpoint that follows Clark's terminal state.
+        const deadline = Date.now() + turnTimeoutMs + readyWaitMs + 1_000;
+        for (;;) {
+            const update = await this.awaitTurn({
+                applicationId: input.applicationId,
+                branch: input.branch,
+                signal: input.signal,
+                waitMs: Math.max(0, deadline - Date.now()),
+            });
+            if (update.status === "finished") {
+                const { activity: _activity, elapsedMs: _elapsedMs, status: _status, ...finished } = update;
+                return {
+                    ...finished,
+                    // See startPrompt, which resolved this: the turn may have run on a
+                    // live edit the caller never named.
+                    ...(started.liveEditId ? { liveEditId: started.liveEditId } : {}),
+                    status: "accepted",
+                };
+            }
+            if (update.status === "unknown" || Date.now() >= deadline) {
+                throw new Error("Prompt forward failed: the turn ended without reporting an outcome");
+            }
+        }
+    }
+    claimPromptLane(applicationId) {
+        const ready = this.promptStarts.get(applicationId) ?? Promise.resolve();
+        let release;
+        const hold = new Promise((resolve) => {
+            release = resolve;
+        });
+        const current = ready.then(() => hold);
+        this.promptStarts.set(applicationId, current);
+        void current.then(() => {
+            if (this.promptStarts.get(applicationId) === current) {
+                this.promptStarts.delete(applicationId);
+            }
+        });
+        return { ready, release: () => void ready.then(release) };
+    }
+    async startPrompt(input) {
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const settleMs = this.options.settleMs ?? DEFAULT_SETTLE_MS;
+        // The session rejects a malformed credential with "Invalid token
+        // specified", which reads like the token expired rather than like the
+        // gateway never had one. Say which it is, without quoting the credential.
+        const segments = String(input.sessionToken ?? "").split(".").length;
+        if (segments !== 3) {
+            throw new PromptNotSentError(`Prompt forward failed: the live-edit credential is not a JWT (${segments} segment(s)); the session will reject it`);
+        }
+        if (!input.userId?.trim()) {
+            throw new PromptNotSentError("Prompt forward failed: userId is required to identify who the turn is running for");
+        }
+        const userId = input.userId;
+        const deadline = Date.now() + timeoutMs;
+        const revision = input.revision ?? this.appState.markTurnStarted();
+        const lane = this.claimPromptLane(input.applicationId);
+        let held;
+        try {
+            await beforePromptDeadline(lane.ready, deadline, input.signal);
+            try {
+                const requestedLiveEdit = liveEditOf(input);
+                const current = this.held.get(input.applicationId);
+                const liveEdit = current?.userId === userId &&
+                    current.movedFrom === requestedLiveEdit.url &&
+                    isSocketOpen(current.ws)
+                    ? current.liveEdit
+                    : requestedLiveEdit;
+                const heldInput = {
+                    applicationId: input.applicationId,
+                    branchName: input.branch,
+                    keepalive: input.keepalive,
+                    liveEdit,
+                    ...(input.resolveLiveEdit
+                        ? { resolveLiveEdit: input.resolveLiveEdit }
+                        : {}),
+                    userId,
+                };
+                const opening = this.connect(heldInput, deadline, false);
+                try {
+                    held = await beforePromptDeadline(opening, deadline, input.signal);
+                    if (liveEdit !== requestedLiveEdit) {
+                        held.movedFrom = requestedLiveEdit.url;
+                    }
+                    if (current?.userId === userId &&
+                        current.liveEdit.url === held.liveEdit.url) {
+                        held.syncStatus = current.syncStatus;
+                    }
+                }
+                catch (error) {
+                    void opening.then((stale) => {
+                        if (stale.provisional && !stale.dropping) {
+                            this.drop(stale);
+                        }
+                    }, () => undefined);
+                    throw error;
+                }
+                if (input.apiKey) {
+                    held.apiKey = input.apiKey;
+                }
+                if (input.organizationId) {
+                    held.organizationId = input.organizationId;
+                }
+                held.sessionToken = input.sessionToken;
+                await beforePromptDeadline(this.resolveHeldProfileKey(held), deadline, input.signal);
+                await beforePromptDeadline(this.resolveHeldOrchestrator(held), deadline, input.signal);
+            }
+            catch (error) {
+                throw error instanceof PromptNotSentError
+                    ? error
+                    : new PromptNotSentError(describeSocketError(error), error);
+            }
+            let integrations = [];
+            const editorContext = this.editorContextFor(held);
+            if (editorContext) {
+                try {
+                    integrations = await beforePromptDeadline(loadIntegrationsForPrompt(editorContext), deadline, input.signal);
+                }
+                catch (error) {
+                    if (error instanceof PromptNotSentError) {
+                        throw error;
+                    }
+                    console.warn("gateway failed to prefill prompt integrations", {
+                        applicationId: input.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            await beforePromptDeadline(Promise.resolve(), deadline, input.signal);
+            if (input.pendingStartRequired &&
+                (input.organizationId === undefined ||
+                    input.idempotencyKey === undefined ||
+                    input.pendingStartToken === undefined ||
+                    !this.appState.pendingStart({
+                        applicationId: input.applicationId,
+                        ...(input.branch === undefined ? {} : { branch: input.branch }),
+                        organizationId: input.organizationId,
+                        userId,
+                    }, input.idempotencyKey, input.pendingStartToken))) {
+                throw new PromptNotSentError("A newer start attempt replaced this one before its prompt was sent");
+            }
+            const turn = {
+                abort: new AbortController(),
+                activity: [],
+                ...(held.branchName === undefined ? {} : { branch: held.branchName }),
+                collector: undefined,
+                delivered: 0,
+                heardAtLastReconnect: 0,
+                held,
+                ...(input.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: input.idempotencyKey }),
+                listener: () => undefined,
+                ...(input.pendingStartToken === undefined
+                    ? {}
+                    : { pendingStartToken: input.pendingStartToken }),
+                recentRuns: [],
+                reconnects: 0,
+                revision,
+                ...(input.attachments?.length ? { retryAction: "retry_build" } : {}),
+                startedAt: Date.now(),
+                turnId: randomUUID(),
+                waiters: new Set(),
+            };
+            const report = (message) => {
+                this.note(turn, message);
+                input.onProgress?.(message);
+            };
+            const collector = new TurnCollector(report, {
+                initialSyncStatus: held.syncStatus,
+                settleMs,
+            });
+            const hasDefaultStructure = this.editorStructureByScope.get(editorStructureScopeKey(input.applicationId, held.branchName));
+            if (hasDefaultStructure) {
+                collector.handle({
+                    hasDefaultStructure,
+                    kind: "editor_structure",
+                });
+            }
+            turn.collector = collector;
+            const bufferedEvents = [];
+            let accepted = false;
+            const listener = (event) => {
+                if (accepted) {
+                    collector.handle(event);
+                }
+                else {
+                    bufferedEvents.push(event);
+                }
+            };
+            turn.listener = listener;
+            held.pendingTurn = turn;
+            held.listeners.add(listener);
+            if (held.provisional) {
+                held.heartbeat.start();
+            }
+            return await this.sendPrompt({
+                acceptBufferedEvents: (generationId) => {
+                    collector.nameGeneration(generationId);
+                    accepted = true;
+                    for (const event of bufferedEvents) {
+                        collector.handle(event);
+                    }
+                    bufferedEvents.length = 0;
+                },
+                held,
+                input,
+                integrations,
+                provisional: Boolean(held.provisional),
+                turn,
+            });
+        }
+        catch (error) {
+            if (held?.provisional && !held.dropping) {
+                this.drop(held);
+            }
+            throw error;
+        }
+        finally {
+            lane.release();
+        }
+    }
+    /**
+     * Sends the prompt on a session already holding a subscribed turn, and hands
+     * the turn to {@link runTurn} once the session confirms it took it on.
+     */
+    async sendPrompt(args) {
+        const { held, input, integrations, provisional, turn } = args;
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const browserContext = this.browserContextFor(held);
+        let acknowledgment;
+        try {
+            // The editor and the smoke client both send the credential twice: once
+            // as the RPC payload's `jwt` and once as the ISocket Authorization
+            // header. The session verifies the header; the AI service re-reads the
+            // payload. Dropping either breaks a different hop.
+            acknowledgment = await editorSocket(held, input.sessionToken).aiGenerateWithQueue({
+                ...(browserContext ? { browserContext } : {}),
+                jwt: input.sessionToken,
+                llmConfig: {
+                    coreModel: this.options.coreModel ?? DEFAULT_LLM.coreModel,
+                    disabledTools: ["build_captureScreenshot", "build_navigatePreview"],
+                    // The ai-service gates Clark's testing tools on this flag *and* a
+                    // browser context, so the two travel together or not at all.
+                    ...(browserContext ? { flags: { isTestingEnabled: true } } : {}),
+                    interleavedThinking: false,
+                    provider: this.options.provider ?? DEFAULT_LLM.provider,
+                    thinkingBudgetTokens: "0",
+                    thinkingEnabled: false,
+                    unifiedProviderEnabled: true,
+                },
+                mode: (input.mode ?? "PLAN"),
+                prompt: input.prompt,
+                promptContext: {
+                    attachments: input.attachments ?? [],
+                    entities: [],
+                    // Sent without `metadata` on purpose: it is the expensive
+                    // per-integration detail, and Clark asks for it per integration
+                    // through `aiGetIntegration`. The shared request type does not
+                    // model that yet, so the narrowing is stated here rather than
+                    // widening every field of the payload.
+                    integrations: integrations,
+                },
+                ...(input.planContext
+                    ? {
+                        planContext: {
+                            ...(input.planContext.approved !== undefined
+                                ? { approved: input.planContext.approved }
+                                : {}),
+                            ...(input.planContext.plan
+                                ? { plan: input.planContext.plan }
+                                : {}),
+                            ...(input.planContext.title
+                                ? { title: input.planContext.title }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                ...(input.responseMetadata
+                    ? { responseMetadata: input.responseMetadata }
+                    : {}),
+                queueMode: "interrupt",
+                requestId: turn.turnId,
+                userPreferences: { suggestNextSteps: false },
+            });
+            this.assertHeadlessTurnBound({ acknowledgment, turn });
+            this.appState.clearLiveEditRecovery(input.applicationId);
+        }
+        catch (error) {
+            this.discardUnstartedTurn(turn);
+            const rejection = error;
+            if (isAuthRejection(rejection)) {
+                if (provisional) {
+                    this.drop(held);
+                }
+                else {
+                    this.armIdle(held);
+                    this.armKeepalive(held);
+                }
+                return {
+                    message: "Interactive auth required for datasource access",
+                    status: "auth_required",
+                };
+            }
+            if (isRemoteRejection(rejection)) {
+                if (provisional) {
+                    this.drop(held);
+                }
+                else {
+                    this.armIdle(held);
+                    this.armKeepalive(held);
+                }
+                throw new PromptNotSentError(`Prompt forward failed: ${rejection.message ?? "unknown socket error"}`, error);
+            }
+            else {
+                const priorHeld = this.held.get(input.applicationId);
+                this.supersedeTurn(input.applicationId);
+                if (priorHeld) {
+                    this.drop(priorHeld);
+                }
+                if (held !== priorHeld) {
+                    this.drop(held);
+                }
+            }
+            if (isTimeout(rejection)) {
+                const healthy = await liveEditIsHealthy({
+                    applicationId: input.applicationId,
+                    liveEditUrl: held.liveEdit.url,
+                    sessionToken: held.sessionToken,
+                });
+                if (healthy && input.resolveLiveEdit) {
+                    recordGatewayFault({
+                        fatal: false,
+                        kind: "live_edit_queue_wedged",
+                    });
+                    if (!this.appState.claimLiveEditRecovery(input.applicationId)) {
+                        throw new PromptNotSentError("The replacement live-edit session also stopped responding before a prompt was accepted. Start a new application instead of retrying this build again.", error, {
+                            recoveryAction: "start_new_app",
+                            retryable: false,
+                        });
+                    }
+                    try {
+                        await input.terminateLiveEdit?.();
+                    }
+                    catch (terminationError) {
+                        this.appState.clearLiveEditRecovery(input.applicationId);
+                        throw new PromptNotSentError("The wedged live-edit session could not be disconnected. Send the same instruction again to retry recovery.", terminationError);
+                    }
+                    try {
+                        await input.resolveLiveEdit();
+                    }
+                    catch (resolveError) {
+                        throw new PromptNotSentError("The wedged live-edit session was disconnected, but its replacement could not be resolved. Send the same instruction again to continue recovery.", resolveError);
+                    }
+                    throw new PromptNotSentError("The live-edit session was replaced after its prompt queue stopped responding. Send the same instruction again to continue on the replacement session.", error);
+                }
+                throw new Error(`Prompt forward timed out: the live-edit session accepted the connection but did not acknowledge the prompt within ${timeoutMs}ms (${rejection.message}). The sandbox is usually still waking up when this happens, so retrying the same prompt normally works.`);
+            }
+            throw error instanceof Error
+                ? error
+                : new Error(`Prompt forward failed: ${rejection.message ?? "unknown socket error"}`);
+        }
+        turn.revision = this.appState.markTurnStarted();
+        args.acceptBufferedEvents(acknowledgment?.generationId);
+        input.onProgress?.("Superblocks accepted the prompt");
+        // Only now, with the prompt accepted and a live turn about to go in the
+        // map, is a recorded dead start for this branch out of date. Clearing it
+        // when the slot was claimed instead dropped it before Superblocks had taken
+        // anything, so a retry that came back needing interactive auth - a return,
+        // not a throw, so nothing re-recorded it - left the app with no turn at all
+        // and `get_app` went back to previewing the starter template.
+        this.appState.clearFailedStarts(input.applicationId, turn.branch, turn.revision);
+        this.appState.clearPendingStartsThrough(input.applicationId, turn.revision);
+        // The pending decision goes for the same reason and at the same moment.
+        // Clearing it when the slot was claimed spent the plan on a prompt
+        // Superblocks had not taken: an approve that came back needing interactive
+        // auth left neither a pending plan nor the BUILD latch - which is only set
+        // once a start is accepted - so the retry proposed a plan again instead of
+        // building the one the user had already approved.
+        this.clearPendingDecision(input.applicationId);
+        this.forgetObservedTurn(input.applicationId);
+        const priorHeld = this.held.get(input.applicationId);
+        this.supersedeTurn(input.applicationId);
+        this.turns.set(input.applicationId, turn);
+        delete held.pendingTurn;
+        if (provisional) {
+            delete held.provisional;
+            this.setHeld(held);
+            held.heartbeat.start();
+            if (priorHeld && priorHeld !== held) {
+                this.drop(priorHeld);
+            }
+        }
+        // Deliberately not awaited: the turn outlives the call that started it so a
+        // client with no progress channel can follow it through awaitTurn.
+        void this.runTurn({
+            applicationId: input.applicationId,
+            onProgress: input.onProgress,
+            sessionToken: input.sessionToken,
+            turn,
+        });
+        return {
+            activity: this.drain(turn),
+            // Where the prompt ended up, which is not always where it was sent: a
+            // connect that followed a moved session is holding an id the caller's
+            // own resolve never saw, and this turn's events arrive under that one.
+            ...(held.liveEdit.id ? { liveEditId: held.liveEdit.id } : {}),
+            status: "accepted",
+        };
+    }
+    latestTurn(applicationId) {
+        return (this.observedTurns.get(applicationId) ?? this.turns.get(applicationId));
+    }
+    observeEditorEvent(held, event) {
+        if (held.dropping || this.held.get(held.applicationId) !== held) {
+            return;
+        }
+        let observed = this.observedTurns.get(held.applicationId);
+        const message = event.kind === "message" ? event.message : undefined;
+        const userContent = message?.role === "user" &&
+            typeof message.content === "string" &&
+            message.content.trim()
+            ? message.content.trim()
+            : undefined;
+        const userMessageId = userContent && typeof message?.id === "string" ? message.id : undefined;
+        if (userMessageId && observed?.userMessageIds.has(userMessageId)) {
+            return;
+        }
+        const activeGeneration = event.kind === "generation_state" &&
+            (event.state === "debugging" ||
+                event.state === "generating" ||
+                event.state === "summarizing");
+        if (userContent || activeGeneration) {
+            this.clearPendingDecision(held.applicationId);
+        }
+        const owned = this.turns.get(held.applicationId);
+        if (owned) {
+            if (!owned.finished && !userContent && !activeGeneration) {
+                return;
+            }
+            this.supersedeTurn(held.applicationId);
+        }
+        const distinctGeneration = activeGeneration &&
+            event.kind === "generation_state" &&
+            Boolean(event.generationId &&
+                observed?.generationId &&
+                event.generationId !== observed.generationId);
+        if (observed &&
+            (observed.held !== held ||
+                distinctGeneration ||
+                (userContent && observed.finished))) {
+            this.forgetObservedTurn(held.applicationId);
+            observed = undefined;
+            this.clearPendingDecision(held.applicationId);
+        }
+        if (observed?.finished) {
+            if (!activeGeneration) {
+                return;
+            }
+            if (event.kind === "generation_state" &&
+                event.generationId &&
+                event.generationId === observed.generationId &&
+                observed.finished.generationStatus !== "needs_decision") {
+                return;
+            }
+            observed = undefined;
+            this.clearPendingDecision(held.applicationId);
+        }
+        if (!observed) {
+            this.clearIdleTimer(held);
+            const activity = [];
+            const next = {
+                abort: new AbortController(),
+                activity,
+                ...(held.branchName === undefined ? {} : { branch: held.branchName }),
+                collector: new TurnCollector((message) => this.note(next, message), {
+                    ...(event.kind === "generation_state" && event.generationId
+                        ? { generationId: event.generationId }
+                        : {}),
+                    settleMs: this.options.settleMs ?? DEFAULT_SETTLE_MS,
+                }),
+                delivered: 0,
+                ...(event.kind === "generation_state" && event.generationId
+                    ? { generationId: event.generationId }
+                    : {}),
+                held,
+                recentRuns: [],
+                revision: this.appState.markTurnStarted(),
+                startedAt: Date.now(),
+                userMessageIds: new Set(),
+                waiters: new Set(),
+            };
+            observed = next;
+            this.observedTurns.set(held.applicationId, observed);
+            void this.finishObservedTurn(held.applicationId, observed);
+        }
+        if (userMessageId) {
+            observed.userMessageIds.add(userMessageId);
+        }
+        if (event.kind === "generation_state" &&
+            event.generationId &&
+            !observed.generationId) {
+            observed.generationId = event.generationId;
+            observed.collector.nameGeneration(event.generationId);
+        }
+        if (userContent) {
+            this.note(observed, `User in editor: ${userContent}`);
+        }
+        observed.collector.handle(event);
+    }
+    forgetObservedTurn(applicationId) {
+        const observed = this.observedTurns.get(applicationId);
+        if (!observed) {
+            return;
+        }
+        this.observedTurns.delete(applicationId);
+        this.settleObservedTurn(observed, "cancelled");
+    }
+    async finishObservedTurn(applicationId, turn) {
+        let generationStatus;
+        try {
+            generationStatus = await turn.collector.waitUntilTerminal({
+                signal: turn.abort.signal,
+                timeoutMs: this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,
+            });
+        }
+        catch {
+            return;
+        }
+        if (this.observedTurns.get(applicationId) !== turn || turn.finished) {
+            return;
+        }
+        const decision = turn.collector.decision();
+        if (decision &&
+            (generationStatus === "needs_decision" ||
+                decision.kind === "missing_integrations")) {
+            const reply = turn.collector.reply();
+            this.appState.setPendingDecision(applicationId, {
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                decision,
+                reply,
+            });
+            if (decision.kind === "plan") {
+                this.appState.setPendingPlan(applicationId, {
+                    ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                    ...(decision.messageId ? { messageId: decision.messageId } : {}),
+                    plan: decision.plan,
+                    ...(decision.title ? { title: decision.title } : {}),
+                });
+            }
+            else {
+                this.appState.clearPendingPlan(applicationId);
+            }
+        }
+        turn.finished = {
+            reply: turn.collector.reply(),
+            generationStatus,
+            viewStatus: turn.collector.viewableStatus(),
+            ...decisionFields(decision),
+        };
+        turn.collector.dispose();
+        this.wake(turn);
+        this.armObservedTurnRelease(applicationId, turn);
+    }
+    settleObservedTurn(turn, generationStatus, reply = turn.collector.reply()) {
+        if (turn.finished) {
+            return;
+        }
+        turn.finished = {
+            reply,
+            generationStatus,
+            viewStatus: turn.collector.viewableStatus(),
+            ...decisionFields(turn.collector.decision()),
+        };
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    armObservedTurnRelease(applicationId, turn) {
+        if (this.observedTurns.get(applicationId) !== turn ||
+            this.held.get(applicationId) !== turn.held ||
+            !turn.finished) {
+            return;
+        }
+        if (turn.finished.generationStatus === "needs_decision") {
+            this.armIdle(turn.held);
+        }
+        else {
+            this.armObservedPostTurnRelease(turn);
+        }
+        this.armKeepalive(turn.held);
+    }
+    armObservedPostTurnRelease(turn) {
+        const held = turn.held;
+        this.clearTimers(held);
+        const delayMs = this.options.releaseAfterTurnMs ?? DEFAULT_RELEASE_AFTER_TURN_MS;
+        held.idleTimer = setTimeout(() => {
+            if (this.observedTurns.get(held.applicationId) === turn &&
+                this.held.get(held.applicationId) === held) {
+                this.drop(held, { preserveFinishedObserved: true });
+            }
+        }, delayMs);
+        held.idleTimer.unref?.();
+    }
+    async awaitTurn(input) {
+        const pollStartedAtMs = Date.now();
+        // The deadline is the end of the poll. Answers with activity or nothing.
+        const deadlineAtMs = pollStartedAtMs + Math.max(0, input.waitMs);
+        // The floor is the minimum time the poll will wait to collect activity for before it answers.
+        // If the turn is finished (ex: needs a user decision), it will answer immediately.
+        const floorAtMs = pollStartedAtMs +
+            Math.min(Math.max(0, input.floorMs ?? 0), Math.max(0, input.waitMs));
+        const storedTurn = this.latestTurn(input.applicationId);
+        // Filter out turns that are not for the requested branch.
+        let turn = storedTurn &&
+            input.branch !== undefined &&
+            input.branch !== storedTurn.branch
+            ? undefined
+            : storedTurn;
+        // check if there is a pending turn for the requested branch.
+        const pendingScope = input.organizationId && input.userId
+            ? {
+                applicationId: input.applicationId,
+                ...(input.branch === undefined ? {} : { branch: input.branch }),
+                organizationId: input.organizationId,
+                userId: input.userId,
+            }
+            : undefined;
+        const pending = pendingScope
+            ? this.appState.pendingStart(pendingScope)
+            : undefined;
+        if (pendingScope && pending) {
+            const started = await this.waitForPendingTurn({
+                afterRevision: turn?.revision ?? 0,
+                applicationId: input.applicationId,
+                ...(pending.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: pending.idempotencyKey }),
+                pendingStartToken: pending.token,
+                scope: pendingScope,
+                signal: input.signal,
+                deadlineAtMs,
+            });
+            if (started) {
+                turn = started;
+            }
+            else if (this.appState.pendingStart(pendingScope)) {
+                return { activity: [], elapsedMs: 0, status: "running" };
+            }
+            else {
+                const currentTurn = this.latestTurn(input.applicationId);
+                turn =
+                    currentTurn &&
+                        input.branch !== undefined &&
+                        input.branch !== currentTurn.branch
+                        ? undefined
+                        : currentTurn;
+            }
+        }
+        // The same recency order as turnState. A poll that cannot say who it is for
+        // reads no failed-start record at all; those records belong to callers.
+        const failed = input.organizationId && input.userId
+            ? this.appState.failedStart({
+                applicationId: input.applicationId,
+                ...(input.branch === undefined ? {} : { branch: input.branch }),
+                organizationId: input.organizationId,
+                userId: input.userId,
+            }, turn?.revision)
+            : undefined;
+        // A turn that never started took no time, and there is no activity to
+        // relay. Reporting it as finished is what stops the caller polling a session
+        // that was never there.
+        if (failed) {
+            return { activity: [], elapsedMs: 0, status: "finished", ...failed };
+        }
+        if (!turn) {
+            if (pendingScope && this.appState.pendingStart(pendingScope)) {
+                return { activity: [], elapsedMs: 0, status: "running" };
+            }
+            return { activity: [], elapsedMs: 0, status: "unknown" };
+        }
+        const remainingWaitMs = Math.max(0, deadlineAtMs - Date.now());
+        if (
+        // If the turn is finished answer immediately.
+        !turn.finished &&
+            (remainingWaitMs > 0 || input.waitMs === 0) &&
+            // Even if there is activity, we will wait until the floor is closed to answer.
+            (turn.delivered >= turn.activity.length || Date.now() < floorAtMs)) {
+            await new Promise((resolve) => {
+                // Ends the wait and hands the caller whatever the turn has by now.
+                const settle = () => {
+                    clearTimeout(deadlineTimer);
+                    clearTimeout(floorTimer);
+                    turn.waiters.delete(onWake);
+                    input.signal?.removeEventListener("abort", settle);
+                    resolve();
+                };
+                // Called on every wake (any activity)
+                const onWake = () => {
+                    // Settle if the turn is finished or the floor is reached.
+                    if (turn.finished || Date.now() >= floorAtMs) {
+                        settle();
+                    }
+                };
+                // Settle if there is activity.
+                // Called when the floor timer expires.
+                const onFloor = () => {
+                    if (turn.delivered < turn.activity.length) {
+                        settle();
+                    }
+                };
+                const deadlineTimer = setTimeout(settle, remainingWaitMs);
+                const floorTimer = setTimeout(onFloor, Math.max(0, floorAtMs - Date.now()));
+                turn.waiters.add(onWake);
+                input.signal?.addEventListener("abort", settle, { once: true });
+            });
+        }
+        // Now drain the turn and return the activity.
+        const activity = this.drain(turn);
+        const elapsedMs = Date.now() - turn.startedAt;
+        const recentRuns = turn.recentRuns.length > 0 ? [...turn.recentRuns] : undefined;
+        if (turn.finished) {
+            return {
+                activity,
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                elapsedMs,
+                status: "finished",
+                ...turn.finished,
+                viewStatus: this.currentViewStatus(input.applicationId, turn.branch, turn.finished.viewStatus),
+                ...(turn.retryAction ? { retryAction: turn.retryAction } : {}),
+                ...(recentRuns ? { recentRuns } : {}),
+            };
+        }
+        return {
+            activity,
+            ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+            elapsedMs,
+            status: "running",
+            ...(recentRuns ? { recentRuns } : {}),
+            viewStatus: this.currentViewStatus(input.applicationId, turn.branch, turn.collector.viewableStatus()),
+        };
+    }
+    /**
+     * Follows the turn to its end on the held session: terminal state, then the
+     * checkpoint that commits Clark's draft. Never throws — a caller polling for
+     * news has to be told what happened, and the only place left to report a
+     * failure is the turn record itself.
+     */
+    async runTurn(input) {
+        const turn = input.turn;
+        const { collector } = turn;
+        const turnTimeoutMs = this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+        const readyWaitMs = this.options.readyWaitMs ?? DEFAULT_READY_WAIT_MS;
+        const report = (message) => {
+            this.note(turn, message);
+            input.onProgress?.(message);
+        };
+        // The session the turn opened on, kept only so its listener is detached at
+        // the end even if the turn moved off it in between.
+        const opening = turn.held;
+        let checkpointOutcome;
+        try {
+            if (turn.finished) {
+                return;
+            }
+            if (!(await collector.waitForClarkPush({
+                signal: turn.abort.signal,
+                timeoutMs: this.pushWaitMs(),
+            }))) {
+                if (turn.finished) {
+                    return;
+                }
+                await this.reattach({ report, turn });
+                if (turn.finished) {
+                    return;
+                }
+                if (!(await collector.waitForClarkPush({
+                    signal: turn.abort.signal,
+                    timeoutMs: this.options.reattachWaitMs ?? DEFAULT_REATTACH_WAIT_MS,
+                }))) {
+                    if (turn.finished) {
+                        return;
+                    }
+                    console.warn("gateway clark turn detached", {
+                        applicationId: input.applicationId,
+                        inboundMethods: [...this.inboundMethods].sort(),
+                    });
+                    turn.finished ??= {
+                        reply: collector.reply(),
+                        generationStatus: "detached",
+                        viewStatus: collector.viewableStatus(),
+                        ...decisionFields(collector.decision()),
+                    };
+                    return;
+                }
+            }
+            if (turn.finished) {
+                return;
+            }
+            const generationStatus = await collector.waitUntilTerminal({
+                signal: turn.abort.signal,
+                timeoutMs: turnTimeoutMs,
+            });
+            if (turn.finished) {
+                return;
+            }
+            console.info("gateway clark turn states", {
+                applicationId: input.applicationId,
+                draftPending: collector.needsDraftAccept(),
+                generationStatus,
+                inboundMethods: [...this.inboundMethods].sort(),
+                states: collector.stateSequence(),
+                workSignals: collector.workSignals(),
+            });
+            // Any turn that produced work asks for the accept, not only one still
+            // holding `hasDraft: true` when it ends. A build normally does report a
+            // draft, but the dev server sometimes flushes the files itself first, and
+            // `aiAcceptDraft` is what mints the checkpoint either way. Accepting with
+            // nothing pending is a no-op that returns no commit id. A turn that
+            // produced nothing is `no_changes` and never reaches here, so Clark
+            // answering a question in chat cannot checkpoint the bare template.
+            if (generationStatus === "completed") {
+                const lane = this.claimPromptLane(input.applicationId);
+                await lane.ready;
+                try {
+                    if (turn.finished || this.turns.get(input.applicationId) !== turn) {
+                        return;
+                    }
+                    // TODO(ENG-5922): `turn.held` is a dead session when the turn was kept
+                    // alive on the relay, so this accept cannot land and the caller gets a
+                    // finished turn with no commit.
+                    checkpointOutcome = await this.checkpoint({
+                        collector,
+                        held: turn.held,
+                        onProgress: report,
+                        readyWaitMs,
+                        sessionToken: input.sessionToken,
+                        turnId: turn.turnId,
+                    });
+                }
+                finally {
+                    lane.release();
+                }
+            }
+            if (turn.finished || this.turns.get(input.applicationId) !== turn) {
+                return;
+            }
+            if (generationStatus === "completed") {
+                this.clearPendingDecision(input.applicationId);
+            }
+            const decision = collector.decision();
+            if (decision &&
+                (generationStatus === "needs_decision" ||
+                    decision.kind === "missing_integrations")) {
+                const reply = collector.reply();
+                this.appState.setPendingDecision(input.applicationId, {
+                    ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                    decision,
+                    ...(turn.recentRuns.length > 0
+                        ? { recentRuns: [...turn.recentRuns] }
+                        : {}),
+                    reply,
+                });
+                if (decision.kind === "plan") {
+                    this.appState.setPendingPlan(input.applicationId, {
+                        ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                        ...(decision.messageId ? { messageId: decision.messageId } : {}),
+                        plan: decision.plan,
+                        ...(decision.title ? { title: decision.title } : {}),
+                    });
+                }
+                else {
+                    this.appState.clearPendingPlan(input.applicationId);
+                }
+            }
+            // Disconnect / supersede already wrote the authoritative outcome; never
+            // overwrite that with a later collector timeout or terminal status.
+            turn.finished ??= {
+                ...(checkpointOutcome?.status === "saved" && checkpointOutcome.commitId
+                    ? { checkpointCommitId: checkpointOutcome.commitId }
+                    : {}),
+                ...(checkpointOutcome?.status === "failed"
+                    ? { checkpointFailure: checkpointOutcome.failure }
+                    : {}),
+                ...(checkpointOutcome?.status === "saved" && checkpointOutcome.warning
+                    ? { checkpointWarning: checkpointOutcome.warning }
+                    : {}),
+                reply: collector.reply(),
+                generationStatus,
+                ...(turn.recentRuns.length > 0
+                    ? { recentRuns: [...turn.recentRuns] }
+                    : {}),
+                viewStatus: collector.viewableStatus(),
+                ...decisionFields(decision),
+            };
+        }
+        catch (error) {
+            if (!turn.finished) {
+                console.warn("gateway clark turn failed", {
+                    applicationId: input.applicationId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            // A disconnect / supersede already settled the turn with the reason; the
+            // abort it caused says less than what is already recorded.
+            turn.finished ??= {
+                reply: collector.reply(),
+                generationStatus: "timeout",
+                viewStatus: collector.viewableStatus(),
+                ...decisionFields(collector.decision()),
+            };
+        }
+        finally {
+            opening.listeners.delete(turn.listener);
+            turn.held.listeners.delete(turn.listener);
+            collector.dispose();
+            // A superseded turn must not arm timers or keepalive on a held session
+            // that now belongs to a newer prompt.
+            const stillMapped = this.turns.get(input.applicationId) === turn;
+            // Nor may a turn that outlived its socket. `recoverTurn` keeps a turn
+            // running on the SABS relay after the close took its session out of the
+            // held map, and `turn.held` still points at that dead object. Arming a
+            // keepalive on it leaves an interval nothing can ever clear - the release
+            // timer no-ops precisely because the session is not current - so it goes
+            // on calling connectLiveEdit for the life of the process.
+            const sessionStillHeld = this.held.get(input.applicationId) === turn.held;
+            if (!sessionStillHeld) {
+                this.clearTimers(turn.held);
+            }
+            else if (stillMapped) {
+                try {
+                    await turn.held.client.requestWithTracing(RELEASE_TURN_LOCK_METHOD, this.turnCorrelator(turn.turnId), {}, `Bearer ${input.sessionToken}`);
+                }
+                catch (error) {
+                    console.warn("gateway could not release the live-edit turn lock", {
+                        applicationId: input.applicationId,
+                        message: describeSocketError(error),
+                        turnId: turn.turnId,
+                    });
+                }
+                if (turn.finished?.generationStatus === "needs_decision") {
+                    this.armIdle(turn.held);
+                }
+                else {
+                    this.armPostTurnRelease(turn.held, turn);
+                }
+                this.armKeepalive(turn.held);
+            }
+            this.wake(turn);
+        }
+    }
+    pushWaitMs() {
+        return this.options.pushWaitMs ?? DEFAULT_PUSH_WAIT_MS;
+    }
+    /**
+     * Checks that the session took this prompt on as a turn belonging to this
+     * peer, and gives up on it now if it did not.
+     *
+     * A dev server that predates the gateway role accepts the socket, echoes the
+     * role it was offered, and then treats the connection as a library socket: the
+     * prompt is acknowledged and Clark's pushes go to the browser binding
+     * instead. The turn would spend its whole budget looking detached, and a
+     * rollout with one stale sandbox in it would look like Clark hanging. Only a
+     * server that bound the turn can name it back, so the missing handle is the
+     * mismatch, reported where it is still cheap to act on.
+     */
+    assertHeadlessTurnBound(input) {
+        if (input.acknowledgment?.headlessTurn?.turnId === input.turn.turnId) {
+            return;
+        }
+        throw new Error(`Prompt forward failed: the live-edit session acknowledged the prompt but did not bind it to this ${GATEWAY_PROTOCOL} peer, so nothing about the turn would report back. The sandbox is running a dev server from before the ${GATEWAY_PROTOCOL} role. Keep the MCP connection running and retry this app action shortly.`);
+    }
+    /**
+     * The field the session reads to decide which turn a call belongs to. Sent on
+     * the calls that make up a turn's lifetime, so a turn keeps reporting into
+     * this caller across a reattach and no other session can be handed it.
+     */
+    turnCorrelator(turnId) {
+        return turnId ? { headlessTurnId: turnId } : {};
+    }
+    /**
+     * Moves a turn onto a fresh socket while the one it is on is still open,
+     * because Clark has stopped pushing to it. A turn that was running unseen
+     * becomes visible again from where it got to.
+     *
+     * The socket it came in on is still the better of the two whenever the
+     * replacement fails to take the turn over: the sandbox is demonstrably alive,
+     * and it is still pushing this turn somewhere. A caller mid-turn has nothing
+     * to gain from an exception here, so there is no failure to report but the
+     * log line.
+     */
+    async reattach(input) {
+        const previous = input.turn.held;
+        input.report("Reattaching to the Superblocks session");
+        const outcome = await this.takeOverTurn({
+            deadline: Date.now() + (this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            previous,
+            turn: input.turn,
+        });
+        if (outcome.kind === "took_over" || outcome.kind === "stale") {
+            return;
+        }
+        console.warn("gateway clark reattach failed", {
+            applicationId: previous.applicationId,
+            message: outcome.kind === "unreachable"
+                ? outcome.message
+                : "the live-edit session would not hand the turn over",
+        });
+    }
+    /**
+     * Whether this turn gets another go at its live edit, booking it if so.
+     *
+     * The allowance is for a live edit that cannot hold a socket, and a turn that
+     * has heard from Clark since its last reconnect is not that: it is getting
+     * somewhere, so its allowance starts over. Without that, a long build behind
+     * a proxy that reaps every few minutes runs out of goes and is failed for the
+     * very reason this path exists to survive.
+     */
+    takeReconnectAllowance(turn, heardAt) {
+        if (heardAt > turn.heardAtLastReconnect) {
+            turn.reconnects = 0;
+        }
+        turn.heardAtLastReconnect = heardAt;
+        const allowed = this.options.reconnectAttempts ?? DEFAULT_RECONNECT_ATTEMPTS;
+        if (turn.reconnects >= allowed) {
+            return false;
+        }
+        turn.reconnects += 1;
+        return true;
+    }
+    /**
+     * Opens a replacement connection and asks the live edit to hand `turn` over
+     * to it.
+     *
+     * Everything that belongs to the session rather than to the socket is carried
+     * across first: the credential the claim itself is made with is one of those
+     * things, and so is the orchestrator a mid-turn tool call needs. The turn's
+     * listener goes on the replacement before the claim, so a push that arrives
+     * while it is in flight is not dropped.
+     *
+     * The turn is claimed before the old socket is let go. The session releases a
+     * turn when the connection holding it closes, so closing first leaves the
+     * claim nothing to take over; claiming first makes the old socket's close a
+     * no-op scoped to a peer that is no longer the owner.
+     *
+     * Nothing has moved when this fails: the listener is back where it was and
+     * the replacement is closed, which leaves the caller free to decide what a
+     * socket it could not replace means.
+     */
+    async takeOverTurn(input) {
+        // One attempt at a time per turn. Both paths that reach for a replacement
+        // answer the same stall - the pushes stop, then the close lands - and the
+        // second cannot see the first from `turn.held`, which the first has not
+        // reassigned yet. Two attempts would each claim the turn on their own
+        // socket and orphan the loser, so the second waits on the first and acts
+        // on what it achieved.
+        const running = input.turn.takingOver;
+        if (running) {
+            return await running;
+        }
+        const attempt = this.attemptTakeOver(input);
+        input.turn.takingOver = attempt;
+        try {
+            return await attempt;
+        }
+        finally {
+            if (input.turn.takingOver === attempt) {
+                input.turn.takingOver = undefined;
+            }
+        }
+    }
+    async attemptTakeOver(input) {
+        const { previous, turn } = input;
+        let fresh;
+        try {
+            fresh = await this.reconnect(previous, input.deadline);
+        }
+        catch (error) {
+            return {
+                kind: "unreachable",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        this.carryOver(fresh, previous);
+        fresh.pendingTurn = turn;
+        fresh.listeners.add(turn.listener);
+        previous.listeners.delete(turn.listener);
+        fresh.heartbeat.start();
+        const claim = fresh.sessionToken === undefined
+            ? "refused"
+            : await this.proveIdentity({
+                held: fresh,
+                sessionToken: fresh.sessionToken,
+                turnId: turn.turnId,
+            });
+        // Opening and claiming take seconds, and the turn can settle inside them:
+        // a relayed terminal event, its own budget running out, a newer prompt
+        // taking the app. runTurn arms the post-turn timers once, against the
+        // session the turn held when it ended, so a replacement committed after
+        // that is a socket nothing will ever close. Nothing has been committed at
+        // this point but the listener, so there is nothing to undo beyond letting
+        // the replacement go.
+        if (turn.finished || turn.held !== previous) {
+            delete fresh.pendingTurn;
+            fresh.listeners.delete(turn.listener);
+            if (fresh.listeners.size === 0 &&
+                this.turns.get(fresh.applicationId)?.held !== fresh) {
+                this.drop(fresh);
+            }
+            return { kind: "stale" };
+        }
+        if (claim === "unreachable") {
+            delete fresh.pendingTurn;
+            fresh.listeners.delete(turn.listener);
+            this.drop(fresh);
+            return {
+                kind: "unreachable",
+                message: "the live-edit session stopped answering on a fresh socket",
+            };
+        }
+        if (claim === "refused") {
+            delete fresh.pendingTurn;
+            fresh.listeners.delete(turn.listener);
+            // Go back to the socket the turn was on, but only while it is still
+            // there: a live edit that would not hand the turn over is still pushing
+            // it to the connection that started it. A replacement for a socket that
+            // already closed has nothing to go back to, and re-registering a dead
+            // session would leave the next prompt to discover it.
+            if (isSocketOpen(previous.ws)) {
+                previous.listeners.add(turn.listener);
+                this.setHeld(previous);
+            }
+            this.drop(fresh);
+            return { kind: "refused" };
+        }
+        delete fresh.pendingTurn;
+        delete fresh.provisional;
+        turn.held = fresh;
+        this.setHeld(fresh);
+        fresh.heartbeat.start();
+        this.drop(previous);
+        return { kind: "took_over" };
+    }
+    /**
+     * Carries onto a replacement socket everything that belongs to the session
+     * rather than to the connection: who the turn runs as, what it is allowed to
+     * do, and which orchestrator its tool calls go to. A replacement missing any
+     * of it is connected but cannot act for the caller.
+     */
+    carryOver(fresh, previous) {
+        fresh.apiKey = previous.apiKey;
+        fresh.branchName = previous.branchName;
+        fresh.orchestrator = previous.orchestrator;
+        fresh.orchestratorUrl = previous.orchestratorUrl;
+        fresh.organizationId = previous.organizationId;
+        fresh.profileKey = previous.profileKey;
+        fresh.profiles = previous.profiles;
+        fresh.sessionToken = previous.sessionToken;
+        fresh.syncStatus = previous.syncStatus;
+    }
+    /**
+     * Makes one authenticated read on a freshly opened socket.
+     *
+     * The dev server trusts a peer's identity per connection and does not carry
+     * it over from the peer this one replaced, so it withholds the pushes it
+     * scopes to a caller — Clark's step-by-step task status — until the new
+     * connection has proven who it is. Reading the chat is the cheapest way to
+     * prove it, and it costs a turn nothing when the read fails.
+     *
+     * Naming `turnId` is what makes this call a reattach rather than just an
+     * authenticated read: the session only moves a turn onto a connection that
+     * can say which turn it is taking over.
+     *
+     * Answers whether it worked, because a caller mid-reattach has to decide
+     * between two sockets on it.
+     */
+    async proveIdentity(input) {
+        try {
+            await editorSocket(input.held, input.sessionToken).aiChatGetMessages({
+                force: false,
+                ...this.turnCorrelator(input.turnId),
+            });
+            return "claimed";
+        }
+        catch (error) {
+            const message = describeSocketError(error);
+            console.warn("gateway clark reattach identity call failed", {
+                applicationId: input.held.applicationId,
+                message,
+            });
+            // A call that went unanswered says the socket opened onto something that
+            // is not servicing requests, which is the same fact a lost liveness beat
+            // reports and nothing like a session declining to hand a turn over.
+            return isTimeout({ message }) ? "unreachable" : "refused";
+        }
+    }
+    async reconnect(previous, deadline) {
+        return await this.connect({
+            applicationId: previous.applicationId,
+            branchName: previous.branchName,
+            keepalive: previous.keepalive,
+            // Both halves, so a reattach keeps listening on the session it was
+            // already on: the socket is being replaced, not the live edit.
+            liveEdit: previous.liveEdit,
+            // The address in hand is one this turn has already been served on, so
+            // a session that moved out from under it denies every attempt made
+            // here. Re-resolving on the way in is not enough for a turn that
+            // outlives its socket.
+            ...(previous.resolveLiveEdit
+                ? { resolveLiveEdit: previous.resolveLiveEdit }
+                : {}),
+            userId: previous.userId,
+        }, deadline, false);
+    }
+    setHeld(held) {
+        this.held.set(held.applicationId, held);
+        this.publishEditorStructure(held);
+    }
+    recordEditorStructure(held, hasDefaultStructure) {
+        held.editorHasDefaultStructure = hasDefaultStructure;
+        this.publishEditorStructure(held);
+    }
+    publishEditorStructure(held) {
+        if (held.dropping ||
+            this.held.get(held.applicationId) !== held ||
+            !held.editorHasDefaultStructure) {
+            return;
+        }
+        this.editorStructureByScope.set(editorStructureScopeKey(held.applicationId, held.branchName), held.editorHasDefaultStructure);
+    }
+    currentViewStatus(applicationId, branch, fallback) {
+        const hasDefaultStructure = this.editorStructureByScope.get(editorStructureScopeKey(applicationId, branch));
+        if (!hasDefaultStructure) {
+            return fallback;
+        }
+        return hasDefaultStructure === "no" ? "ready" : "unknown";
+    }
+    /** Lines this caller has not been handed yet. */
+    drain(turn) {
+        const pending = turn.activity.slice(turn.delivered);
+        turn.delivered = turn.activity.length;
+        return pending;
+    }
+    wake(turn) {
+        for (const waiter of [...turn.waiters]) {
+            waiter();
+        }
+    }
+    /** Adds a line to what the next poll on this turn is handed. */
+    note(turn, message) {
+        turn.activity.push(message);
+        this.wake(turn);
+    }
+    /**
+     * Records the outcome of a turn from outside runTurn, and ends the collector
+     * waits so runTurn cannot overwrite it with a later timeout of its own. The
+     * first outcome written wins: it is the one callers have already been shown.
+     */
+    settleTurn(turn, finished) {
+        turn.finished ??= finished;
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    /**
+     * Mirrors the browser editor's auto-accept: wait for the dev server to flush
+     * Clark's files, then commit the draft. Failing to checkpoint costs the caller
+     * a committed app, not the generation itself, so this never throws.
+     */
+    async checkpoint(input) {
+        const inSync = await input.collector.waitUntilInSync({
+            timeoutMs: input.readyWaitMs,
+        });
+        console.info("gateway clark checkpoint sync wait", {
+            applicationId: input.held.applicationId,
+            inSync,
+        });
+        if (!inSync) {
+            input.onProgress?.("Clark's files are still saving; the app will finish in the editor");
+            recordCheckpointOutcome("sync_timeout");
+            return {
+                failure: {
+                    category: "timeout",
+                    message: "Clark's files did not finish saving before the checkpoint deadline",
+                },
+                status: "failed",
+            };
+        }
+        input.onProgress?.("Saving a checkpoint");
+        try {
+            const result = await editorSocket(input.held, input.sessionToken).aiAcceptDraft({
+                screenshotDataUrl: null,
+                silently: true,
+                ...this.turnCorrelator(input.turnId),
+            });
+            input.collector.markCheckpointed();
+            const commitId = result?.commitId?.trim() ? result.commitId : undefined;
+            const warning = commitId
+                ? normalizeCheckpointWarning(result?.warning)
+                : undefined;
+            // The accept writes draftCommitted on the server. The warm sandbox still
+            // holds the chat it loaded earlier, so a browser that opens this same
+            // session and loads chat without force never sees the checkpoint card.
+            // Force-reloading now puts the server message into the sandbox store.
+            if (commitId) {
+                try {
+                    await editorSocket(input.held, input.sessionToken).aiChatGetMessages({
+                        force: true,
+                        ...this.turnCorrelator(input.turnId),
+                    });
+                }
+                catch (error) {
+                    console.warn("gateway clark chat reload after checkpoint failed", {
+                        applicationId: input.held.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            console.info("gateway clark checkpoint saved", {
+                applicationId: input.held.applicationId,
+                commitId: commitId ?? "none",
+            });
+            input.onProgress?.(warning?.message ??
+                (commitId ? "Checkpoint saved" : "App already up to date"));
+            recordCheckpointOutcome(warning ? "cleanup_warning" : commitId ? "saved" : "unchanged");
+            return {
+                ...(commitId ? { commitId } : {}),
+                status: "saved",
+                ...(warning ? { warning } : {}),
+            };
+        }
+        catch (error) {
+            const failure = checkpointFailure(error);
+            recordCheckpointOutcome(`${failure.category}_failure`);
+            console.warn("gateway clark checkpoint failed", {
+                applicationId: input.held.applicationId,
+                message: `${failure.message}${failure.code === undefined ? "" : ` (code ${failure.code})`}`,
+            });
+            input.onProgress?.("Could not save a checkpoint for Superblocks' changes");
+            return { failure, status: "failed" };
+        }
+    }
+    async ensureHeld(input, deadline, expectedTurn) {
+        this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
+        const existing = this.held.get(input.applicationId);
+        // A connect that followed a moved session left this record pointing
+        // somewhere the prompt's own resolve never saw. Overlapping forwards are
+        // ordinary - Clark retries - so the prompt behind the move still names the
+        // host the session left; reading that as a different session would drop
+        // the socket the move just won and dial the host that stopped answering.
+        const sameUrl = existing?.liveEdit.url === input.liveEdit.url;
+        if (existing &&
+            (sameUrl || existing.movedFrom === input.liveEdit.url) &&
+            isSocketOpen(existing.ws)) {
+            // The held map is keyed by applicationId alone. Reusing a socket opened
+            // for a different user would attribute Clark work to the wrong principal
+            // and keep their session JWT on the wire.
+            if (existing.userId !== input.userId) {
+                this.drop(existing);
+            }
+            else {
+                existing.branchName = input.branchName;
+                // A new prompt is a new turn, and the beat-lost clock measures one
+                // turn's silence. Carrying a running clock across would judge this
+                // prompt on how quiet the socket was before it was sent.
+                existing.beatLoss = undefined;
+                // The caller resolved the live edit for this prompt, so its id is at
+                // least as fresh as whatever an earlier prompt left here - but only
+                // when it named the host this socket is on. A prompt reusing through
+                // `movedFrom` resolved before the move, so its id is the one the move
+                // replaced, and taking it would undo what the move established. An
+                // absent id is not news either way and must not clear what is here.
+                if (sameUrl && input.liveEdit.id) {
+                    existing.liveEdit = {
+                        id: input.liveEdit.id,
+                        url: existing.liveEdit.url,
+                    };
+                }
+                if (input.keepalive) {
+                    existing.keepalive = input.keepalive;
+                }
+                if (input.resolveLiveEdit) {
+                    existing.resolveLiveEdit = input.resolveLiveEdit;
+                }
+                return existing;
+            }
+        }
+        const pending = this.connecting.get(input.applicationId);
+        if (pending) {
+            // Settle behind the open already in flight, then re-decide: it may have
+            // produced the socket this caller wants, or failed and left nothing.
+            await pending.catch(() => undefined);
+            return await this.ensureHeld(input, deadline, expectedTurn);
+        }
+        if (existing) {
+            this.drop(existing);
+        }
+        const connect = this.connect(input, deadline, true, expectedTurn);
+        this.connecting.set(input.applicationId, connect);
+        try {
+            return await connect;
+        }
+        finally {
+            this.connecting.delete(input.applicationId);
+        }
+    }
+    async connect(input, deadline, publish = true, expectedTurn) {
+        // Unique per connection. The dev server ignores the disconnect of a peerId
+        // that is no longer the bound one, so a reattach that closes its
+        // predecessor afterwards keeps the binding it just took; reusing one id
+        // would have that close clear it.
+        const peerId = `gateway-held-${input.applicationId}-${randomUUID()}`;
+        const url = buildSessionUrl({
+            applicationId: input.applicationId,
+            liveEditUrl: input.liveEdit.url,
+            peerId,
+            userId: input.userId,
+        });
+        // Where the session turned out to be, which is what the held record has to
+        // remember: the value the prompt arrived with describes where it was looked
+        // for, not where the socket ended up.
+        let liveEdit = input.liveEdit;
+        const resolveLiveEdit = input.resolveLiveEdit;
+        const close = {};
+        const ws = await open(url, this.options.connectAttemptTimeoutMs ??
+            DEFAULT_CONNECT_ATTEMPT_TIMEOUT_MS, deadline, (error) => {
+            close.error = error.message;
+        }, resolveLiveEdit &&
+            (async () => {
+                try {
+                    const moved = await resolveLiveEdit();
+                    const next = buildSessionUrl({
+                        applicationId: input.applicationId,
+                        liveEditUrl: moved.liveEditUrl,
+                        peerId,
+                        userId: input.userId,
+                    });
+                    // Recorded whether or not the host changed. A resolve that lands
+                    // back on the same host is still the freshest word on which live
+                    // edit that host is serving. Recorded only once the URL is built,
+                    // so a session that cannot be reached does not overwrite the one
+                    // the socket may yet connect to. Taken as one value: a resolve that
+                    // names a host but not the session on it leaves this with no id
+                    // rather than the one from before the move, so the turn falls back
+                    // to the socket instead of listening on a live edit that moved.
+                    liveEdit = liveEditOf(moved);
+                    console.warn("gateway re-resolved a live-edit host", {
+                        applicationId: input.applicationId,
+                        from: new URL(input.liveEdit.url).host,
+                        liveEditId: liveEdit.id,
+                        peerId,
+                        to: next.host,
+                    });
+                    return next;
+                }
+                catch (error) {
+                    // Reported rather than raised: the connect loop's fallback is the
+                    // host already in hand, and losing that to a failed lookup would
+                    // turn a recoverable stale binding into no attempt at all.
+                    console.warn("gateway could not re-resolve a live-edit host", {
+                        applicationId: input.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                        peerId,
+                    });
+                    return undefined;
+                }
+            }));
+        // Registered before ISocket takes the socket so it runs ahead of ISocket's
+        // own close handler, which is handed neither code nor reason.
+        ws.on("close", (code, reason) => {
+            close.code = code;
+            const text = reason?.toString().trim();
+            if (text) {
+                close.reason = text;
+            }
+        });
+        // Same cast the smoke client uses: ISocket's browser WebSocket type and
+        // the `ws` package's Node type are structurally compatible at runtime but
+        // not assignable under TypeScript's DOM lib.
+        const heldRef = {
+            current: undefined,
+        };
+        const socket = new ISocket(ws, createEditorClientMethods(() => {
+            const held = heldRef.current;
+            if (!held) {
+                return undefined;
+            }
+            return (event) => {
+                if (event.kind === "sync_status" && event.status) {
+                    held.syncStatus = event.status;
+                }
+                if (event.kind === "editor_structure") {
+                    this.recordEditorStructure(held, event.hasDefaultStructure);
+                }
+                if (isBrowserObserverEvent(event)) {
+                    this.observeEditorEvent(held, event);
+                    return;
+                }
+                if (held.listeners.size > 0) {
+                    for (const listener of [...held.listeners]) {
+                        listener(event);
+                    }
+                    return;
+                }
+            };
+        }, (method) => {
+            this.inboundMethods.add(method);
+        }, {
+            getContext: () => this.editorContextFor(heldRef.current),
+            onToolRun: (run) => {
+                const current = heldRef.current;
+                if (!current) {
+                    return;
+                }
+                const turn = current.pendingTurn ?? this.turns.get(current.applicationId);
+                if (!turn ||
+                    turn.finished ||
+                    (turn.held !== current && current.pendingTurn !== turn)) {
+                    return;
+                }
+                turn.recentRuns = appendRecentToolRun(turn.recentRuns, buildRecentToolRun(run));
+                const mark = run.success ? "passed" : "failed";
+                const line = `API test ${mark}: ${run.name}`;
+                turn.activity.push(line);
+                this.wake(turn);
+            },
+            respondToToolPermission: async (payload) => {
+                const current = heldRef.current;
+                if (!current) {
+                    return;
+                }
+                const turn = current.pendingTurn ?? this.turns.get(current.applicationId);
+                if (!turn ||
+                    turn.finished ||
+                    (turn.held !== current && current.pendingTurn !== turn)) {
+                    return;
+                }
+                try {
+                    await editorSocket(current, current.sessionToken).aiRespondToToolPermission({
+                        approved: payload.approved,
+                        ...this.turnCorrelator(turn.turnId),
+                        messageId: payload.messageId,
+                        requestId: payload.requestId ?? payload.messageId,
+                    });
+                }
+                catch (error) {
+                    console.warn("gateway auto-approve tool permission failed", {
+                        applicationId: current.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            },
+        }), [], {
+            onClose: () => {
+                const current = this.held.get(input.applicationId);
+                if (current?.ws === ws) {
+                    console.error("gateway held session closed", {
+                        applicationId: input.applicationId,
+                        requested: Boolean(current.dropping),
+                    });
+                    this.clearTimers(current);
+                    current.heartbeat.stop();
+                    this.held.delete(input.applicationId);
+                }
+                const held = heldRef.current;
+                if (held?.provisional === true || (!held && !publish)) {
+                    return;
+                }
+                // Its own closes - a reattach swapping sockets, a release - leave the
+                // turn either running elsewhere or already settled.
+                if (held?.dropping) {
+                    return;
+                }
+                const observed = held
+                    ? this.observedTurns.get(held.applicationId)
+                    : undefined;
+                if (held && observed?.held === held && !observed.finished) {
+                    const applicationEnded = isApplicationClose(close);
+                    this.settleObservedTurn(observed, applicationEnded ? "live_edit_terminated" : "detached", applicationEnded
+                        ? LIVE_EDIT_TERMINATED_REPLY + describeClose(close)
+                        : observed.collector.reply());
+                    return;
+                }
+                // An application code is the live edit stating its own end, so there
+                // is nothing left to get back onto. Any other close is the
+                // transport's, and a turn is not over because the socket carrying it
+                // is: the gateway goes and looks before saying so.
+                if (!held || isApplicationClose(close)) {
+                    this.abandonTurnOnDisconnect(input.applicationId, close, held?.heartbeat.account);
+                    return;
+                }
+                void this.recoverTurn({ close, previous: held });
+            },
+            timeouts: {
+                connectionTimeoutInSeconds: undefined,
+                // Held across prompts, so budget each RPC the full timeout rather than
+                // whatever remained of the connect deadline from the first open.
+                noResponseTimeoutInSeconds: (this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS) / 1000,
+            },
+        });
+        const client = createISocketClient(socket);
+        const heartbeat = this.buildHeartbeat(heldRef);
+        const held = {
+            applicationId: input.applicationId,
+            branchName: input.branchName,
+            client,
+            heartbeat,
+            idleTimer: undefined,
+            keepalive: input.keepalive,
+            keepaliveTimer: undefined,
+            listeners: new Set(),
+            liveEdit,
+            ...(input.resolveLiveEdit
+                ? { resolveLiveEdit: input.resolveLiveEdit }
+                : {}),
+            ...(liveEdit.url === input.liveEdit.url
+                ? {}
+                : { movedFrom: input.liveEdit.url }),
+            peerId,
+            ...(!publish ? { provisional: true } : {}),
+            socket,
+            userId: input.userId,
+            ws,
+        };
+        heldRef.current = held;
+        if (publish) {
+            try {
+                this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
+            }
+            catch (error) {
+                this.drop(held);
+                throw error;
+            }
+            this.setHeld(held);
+        }
+        // Inbound frames are what separates a dead connection from a request
+        // channel that stopped answering on a live one.
+        ws.on("message", () => {
+            heartbeat.recordReceive();
+        });
+        // Beats for as long as the socket is held, including the grace period after
+        // a turn settles: the checkpoint lands in that window and the sandbox has
+        // to still be there for it.
+        if (publish) {
+            heartbeat.start();
+        }
+        return held;
+    }
+    assertReadOnlyHoldCurrent(applicationId, expectedTurn) {
+        const current = this.turns.get(applicationId);
+        const ownsPublishedSession = current && this.held.get(applicationId) === current.held;
+        if (current !== expectedTurn ||
+            (current && (!current.finished || ownsPublishedSession))) {
+            throw new Error("Live-edit hold skipped because the application has an active turn or completed a turn while the session opened");
+        }
+    }
+    /**
+     * The liveness beat for one held socket.
+     *
+     * Everything about pacing, deadlines and when to believe a silence lives in
+     * {@link SocketHeartbeat}; what belongs here is only what is specific to this
+     * peer - which call to make, what counts as unanswered on this client, and
+     * who to tell.
+     */
+    buildHeartbeat(heldRef) {
+        return new SocketHeartbeat({
+            beat: async () => {
+                const held = heldRef.current;
+                if (!held?.sessionToken) {
+                    // Unreachable behind `shouldBeat`. Thrown rather than returned so a
+                    // beat that never went out can never be recorded as one that landed.
+                    throw new Error("live-edit session went away before the beat was sent");
+                }
+                await editorSocket(held, held.sessionToken).ping(this.turnCorrelator((held.pendingTurn ?? this.turns.get(held.applicationId))?.turnId));
+            },
+            describeError: describeSocketError,
+            intervalMs: this.options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+            // This client rejects with a plain `{ code, message }` object rather than
+            // an Error, so a timeout is only recognizable from the rendered message.
+            isUnanswered: (error) => isTimeout({ message: describeSocketError(error) }),
+            maxConsecutiveMisses: this.options.heartbeatMaxMisses,
+            maxConsecutiveUnanswered: this.options.heartbeatMaxUnanswered,
+            onLost: (account) => {
+                const held = heldRef.current;
+                console.warn("gateway liveness beat lost", {
+                    applicationId: held?.applicationId,
+                    failures: account.failures,
+                    lapses: account.lapses,
+                    message: account.lastError,
+                });
+            },
+            onOutcome: (outcome, durationMs, account) => {
+                const held = heldRef.current;
+                if (outcome !== "success") {
+                    console.warn(`gateway liveness beat ${outcome}`, {
+                        applicationId: held?.applicationId,
+                        durationMs,
+                        failures: account.failures,
+                        lapses: account.lapses,
+                        message: account.lastError,
+                    });
+                }
+                if (!held) {
+                    return;
+                }
+                if (held.provisional) {
+                    return;
+                }
+                // The clock measures silence, so anything that is not silence ends it.
+                // A success and a refusal both prove the peer answered this beat - and
+                // a refusal must never cost a turn, since it is an application-level
+                // problem on a reachable connection. A lapse is the heartbeat's own
+                // verdict that inbound traffic explained the quiet, which un-latches
+                // its alarm too. Only a genuinely unanswered beat keeps the clock.
+                if (outcome !== "grace" && outcome !== "miss") {
+                    held.beatLoss = undefined;
+                    return;
+                }
+                // Started here rather than from `onLost`, which fires only on the edge
+                // into the lost state. A refusal stops this clock without un-latching
+                // that state, so the edge has already been spent and would never come
+                // again - and silence returning after a refusal could then never end
+                // the turn. `miss` is that same edge as the heartbeat draws it: `grace`
+                // is still inside the missed-beat allowance, so it keeps a clock that
+                // is already running without starting one.
+                if (outcome === "miss") {
+                    held.beatLoss ??= { at: Date.now() };
+                }
+                const beatLoss = held.beatLoss;
+                if (!beatLoss) {
+                    return;
+                }
+                const graceMs = this.options.beatLostGraceMs ?? DEFAULT_BEAT_LOST_GRACE_MS;
+                if (Date.now() - beatLoss.at >= graceMs && !beatLoss.healthCheck) {
+                    beatLoss.healthCheck = this.confirmBeatLostSession(held, account, beatLoss);
+                }
+            },
+            // The sandbox grants liveness on proof of authorization, so a beat sent
+            // before this session has a credential would be refused; skipping it
+            // costs nothing, because a session with no credential has no turn to
+            // protect yet either.
+            shouldBeat: () => {
+                const held = heldRef.current;
+                return (held !== undefined &&
+                    Boolean(held.sessionToken) &&
+                    isSocketOpen(held.ws));
+            },
+            timeoutMs: this.options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS,
+        });
+    }
+    async confirmBeatLostSession(held, heartbeat, beatLoss) {
+        const applicationId = held.applicationId;
+        const turn = this.turns.get(applicationId);
+        const activeTurn = turn?.held === held &&
+            !turn.finished &&
+            !turn.collector.status() &&
+            !turn.collector.isSettling()
+            ? turn
+            : undefined;
+        const observed = this.observedTurns.get(applicationId);
+        const activeObserved = observed?.held === held &&
+            !observed.finished &&
+            !observed.collector.status() &&
+            !observed.collector.isSettling()
+            ? observed
+            : undefined;
+        const activeTurnStateCount = activeTurn?.collector.stateSequence().length;
+        const activeObservedStateCount = activeObserved?.collector.stateSequence().length;
+        if (!activeTurn && !activeObserved) {
+            if (held.beatLoss === beatLoss) {
+                held.beatLoss = undefined;
+            }
+            return;
+        }
+        const healthy = await liveEditIsHealthy({
+            applicationId,
+            liveEditUrl: held.liveEdit.url,
+            sessionToken: held.sessionToken,
+        });
+        const turnIsCurrent = activeTurn !== undefined &&
+            this.turns.get(applicationId) === activeTurn &&
+            !activeTurn.finished &&
+            !activeTurn.collector.status() &&
+            !activeTurn.collector.isSettling() &&
+            activeTurn.collector.stateSequence().length === activeTurnStateCount;
+        const observedIsCurrent = activeObserved !== undefined &&
+            this.observedTurns.get(applicationId) === activeObserved &&
+            !activeObserved.finished &&
+            !activeObserved.collector.status() &&
+            !activeObserved.collector.isSettling() &&
+            activeObserved.collector.stateSequence().length ===
+                activeObservedStateCount;
+        if (held.dropping ||
+            this.held.get(applicationId) !== held ||
+            held.beatLoss !== beatLoss) {
+            return;
+        }
+        held.beatLoss = undefined;
+        if (healthy || (!turnIsCurrent && !observedIsCurrent)) {
+            return;
+        }
+        this.abandonTurnOnBeatLost(held, heartbeat, turnIsCurrent ? activeTurn : undefined, observedIsCurrent ? activeObserved : undefined);
+    }
+    armIdle(held) {
+        if (held.idleTimer) {
+            clearTimeout(held.idleTimer);
+        }
+        const idleMs = this.options.idleMs ?? DEFAULT_IDLE_MS;
+        held.idleTimer = setTimeout(() => {
+            this.release(held.applicationId);
+        }, idleMs);
+        held.idleTimer.unref?.();
+    }
+    /**
+     * Ends a turn whose live edit is gone.
+     *
+     * The dev server exits on its own when its lock is lost, and it says nothing
+     * on the way out. A turn left waiting on that socket burns its entire budget
+     * — ten minutes — before the caller is told anything.
+     *
+     * Reached only once the live edit being gone is established, which a close on
+     * its own never does: either it named its own end in the application range,
+     * or {@link recoverTurn} could not get back to it for the whole reconnect
+     * grace. `live_edit_terminated` is a claim about the sandbox, so it is worth
+     * only as much as the evidence behind it. The close code and heartbeat
+     * account go in the reply, since they are the only account of the cause that
+     * reaches the caller.
+     */
+    abandonTurnOnDisconnect(applicationId, close = {}, heartbeat) {
+        const turn = this.turns.get(applicationId);
+        if (!turn || turn.finished) {
+            return;
+        }
+        const beats = heartbeat ? describeHeartbeat(heartbeat, Date.now()) : "";
+        console.warn("gateway clark turn abandoned", {
+            applicationId,
+            beatFailures: heartbeat?.failures,
+            beatLapses: heartbeat?.lapses,
+            // A refusal never counts as a failure, so without these two a death that
+            // the reply explains in full - every answer an error, or a silence the
+            // socket's own traffic excused - logs as `beatFailures: 0`, which reads
+            // as a beat that had nothing to report.
+            beatRefusals: heartbeat?.refusals,
+            beatsSent: heartbeat?.sent,
+            beatsUnanswered: heartbeat?.unanswered,
+            closeCode: close.code,
+            closeError: close.error,
+            closeReason: close.reason,
+            lastBeatError: heartbeat?.lastError,
+            lastBeatSuccessAt: heartbeat?.lastSuccessAt,
+            pendingBeatSentAt: heartbeat?.pendingSince,
+            reason: "live-edit session disconnected",
+        });
+        this.settleAsLiveEditTerminated(turn, describeClose(close) + beats);
+    }
+    /**
+     * Ends a turn SABS has just said has no live edit left to run on.
+     *
+     * A socket close is the other trigger for this same outcome, and it is the
+     * slower one: the dev server exits silently when it loses its lock, so the
+     * close can be minutes late or never arrive at all. This event is the control
+     * plane stating the session is gone, which is the same fact without waiting
+     * for a connection to notice it.
+     *
+     * Only for a turn that has not settled itself, though. Every healthy build
+     * ends with its session torn down too, and reading that as a dead live edit
+     * would report each finished app as a failure. A collector that already
+     * settled on a terminal state keeps it; the teardown is the outcome only for
+     * a turn still waiting for one. The disconnect path needs no such guard - an
+     * unsolicited close mid-turn is abnormal in its own right, where a teardown
+     * is what the end of every turn looks like.
+     *
+     * Settled, not merely reached: a terminal state is provisional until the
+     * quiet window closes, because a build that resumes after a false
+     * completed/idle clears it. A teardown inside that window therefore still
+     * ends the turn - which is the honest answer, since the checkpoint that
+     * would follow runs over the socket to the dev server that just died and
+     * could not have landed either way.
+     */
+    abandonTurnOnSessionTerminated(applicationId, turn) {
+        if (turn.finished || turn.collector.status()) {
+            return;
+        }
+        console.warn("gateway clark turn abandoned", {
+            applicationId,
+            reason: "SABS terminated the live-edit session",
+        });
+        this.settleAsLiveEditTerminated(turn, "");
+    }
+    /**
+     * Ends a turn whose socket has stopped answering.
+     *
+     * Three gates answer different questions. `SocketHeartbeat`
+     * declares the beat lost after consecutive genuine misses, having already
+     * excused a run of unanswered beats and every silence that inbound traffic
+     * explained - the right threshold for a diagnostic, and too eager for this: a
+     * sandbox that misses two beats and answers the next was recovering, and its
+     * turn has to survive that. So the loss also has to outlast
+     * {@link DEFAULT_BEAT_LOST_GRACE_MS}, and any beat that succeeds clears it.
+     * Finally, an independent HTTP request must fail to confirm that this same
+     * application's dev server is healthy.
+     *
+     * What is left is a request channel that has been silent for minutes on a
+     * socket that never closed, with a turn waiting on it - which without this
+     * waits out the whole turn budget.
+     *
+     * This is the only trigger that reaches a half-open socket. An unsolicited
+     * close is the ordinary one and never arrives for a connection that stays up
+     * with nothing behind it, and the SABS `session: terminated` event cannot
+     * reach a gateway with no inbound route - which is every gateway run on a
+     * laptop, where a loopback public URL leaves SABS no way to post at all.
+     *
+     * The socket is deliberately left in place. Whether a connection proven
+     * wedged should also be torn down rather than handed to the next prompt is a
+     * separate question from whether this turn should keep waiting on it.
+     */
+    abandonTurnOnBeatLost(held, heartbeat, turn, observed) {
+        const applicationId = held.applicationId;
+        if (held.dropping || this.held.get(applicationId) !== held) {
+            return;
+        }
+        // The same rule the disconnect and SABS paths use: settle only a turn that
+        // has not settled itself. A finished turn's socket keeps beating through
+        // the post-turn grace, so a sandbox reaped in that window must not
+        // overwrite the outcome the caller already has.
+        if (turn &&
+            this.turns.get(applicationId) === turn &&
+            turn.held === held &&
+            !turn.finished &&
+            !turn.collector.status()) {
+            console.warn("gateway clark turn abandoned", {
+                applicationId,
+                beatFailures: heartbeat.failures,
+                beatLapses: heartbeat.lapses,
+                beatsSent: heartbeat.sent,
+                lastBeatError: heartbeat.lastError,
+                reason: "the live-edit socket stopped answering",
+            });
+            this.settleAsLiveEditTerminated(turn, describeHeartbeat(heartbeat, Date.now()) +
+                " The live-edit health check could not confirm the same app was healthy.");
+            return;
+        }
+        if (observed &&
+            this.observedTurns.get(applicationId) === observed &&
+            observed.held === held &&
+            !observed.finished) {
+            this.settleObservedTurn(observed, "detached");
+            this.armObservedTurnRelease(applicationId, observed);
+        }
+    }
+    /**
+     * Records a dead live edit as the turn's outcome and ends every wait on it.
+     * `evidence` is appended to the reply because it is the only account of the
+     * cause that reaches the caller.
+     */
+    settleAsLiveEditTerminated(turn, evidence) {
+        this.settleTurn(turn, {
+            reply: LIVE_EDIT_TERMINATED_REPLY + evidence,
+            generationStatus: "live_edit_terminated",
+            viewStatus: turn.collector.viewableStatus(),
+        });
+    }
+    /**
+     * Decides what a close the gateway did not ask for actually means, by going
+     * back for the live edit rather than inferring from the close.
+     *
+     * The reattach machinery exists for exactly this: a turn whose socket went
+     * away is one the gateway can move onto a replacement. Abandoning here is
+     * what used to make that unreachable, and it charged a recoverable blip the
+     * whole turn - the caller is told to send the prompt again, and the work
+     * already done in it is discarded.
+     *
+     * Each of the three outcomes is a different thing to tell the caller:
+     *
+     * - taken over: nothing to tell. The turn carries on where it got to.
+     * - unreachable for the whole grace: the termination the close only hinted
+     *   at, now with the evidence to say so.
+     * - reached but refused the turn: the sandbox is alive and building where
+     *   this gateway cannot watch it, which is `detached`. Calling that a death
+     *   would send the caller to retry a build that is still running.
+     *
+     * A reconnect that fails while SABS is still relaying the turn settles
+     * nothing: the socket is one of two ways this turn reports, and the events
+     * still arriving are the better account of whether the build is alive.
+     *
+     * Never throws: nothing awaits this, and every outcome it can reach belongs
+     * on the turn rather than on the socket handler that started it.
+     */
+    async recoverTurn(input) {
+        const applicationId = input.previous.applicationId;
+        const turn = this.turns.get(applicationId);
+        // A turn that has moved on from this session, or already has an outcome,
+        // has nothing riding on the socket that just closed.
+        if (!turn || turn.finished || turn.held !== input.previous) {
+            return;
+        }
+        const heartbeat = input.previous.heartbeat.account;
+        const heardAt = turn.collector.lastEventAt();
+        if (!this.takeReconnectAllowance(turn, heardAt)) {
+            console.warn("gateway clark turn reconnects exhausted", {
+                applicationId,
+                attempts: turn.reconnects,
+                closeCode: input.close.code,
+            });
+            this.abandonTurnOnDisconnect(applicationId, input.close, heartbeat);
+            return;
+        }
+        this.note(turn, "Reconnecting to the Superblocks live-edit session");
+        const outcome = await this.takeOverTurn({
+            deadline: Date.now() +
+                (this.options.reconnectGraceMs ?? DEFAULT_RECONNECT_GRACE_MS),
+            previous: input.previous,
+            turn,
+        });
+        if (turn.finished || outcome.kind === "stale") {
+            return;
+        }
+        if (outcome.kind === "took_over") {
+            this.note(turn, "Reconnected to the Superblocks live-edit session");
+            return;
+        }
+        // TODO(ENG-5922): nothing tries to reconnect again from here. A turn kept
+        // alive on the relay reaches its terminal state with no socket, so the
+        // checkpoint that would commit Clark's work cannot land and the turn
+        // completes without one.
+        if (turn.collector.lastEventAt() > heardAt) {
+            console.warn("gateway clark turn kept on the relay", {
+                applicationId,
+                closeCode: input.close.code,
+                outcome: outcome.kind,
+            });
+            this.note(turn, "Lost the live-edit socket; still following the build through Superblocks");
+            return;
+        }
+        if (outcome.kind === "unreachable") {
+            this.abandonTurnOnDisconnect(applicationId, input.close, heartbeat);
+            return;
+        }
+        console.warn("gateway clark turn not handed back", {
+            applicationId,
+            closeCode: input.close.code,
+        });
+        this.settleTurn(turn, {
+            reply: turn.collector.reply(),
+            generationStatus: "detached",
+            viewStatus: turn.collector.viewableStatus(),
+            ...decisionFields(turn.collector.decision()),
+        });
+    }
+    /**
+     * Ends a prior turn for `applicationId` before a newer prompt claims the map
+     * slot. Callers polling the old turn see `cancelled`; its runTurn exits via
+     * AbortSignal and must not keep listening or arming release on the held
+     * session.
+     */
+    supersedeTurn(applicationId) {
+        const prior = this.turns.get(applicationId);
+        this.turns.delete(applicationId);
+        if (!prior) {
+            return;
+        }
+        this.cancelTurn(prior);
+    }
+    cancelTurn(turn) {
+        turn.finished ??= {
+            reply: "This turn was replaced by a newer prompt on the same app, so its work was cancelled.",
+            generationStatus: "cancelled",
+            viewStatus: turn.collector.viewableStatus(),
+        };
+        turn.held.listeners.delete(turn.listener);
+        this.held.get(turn.held.applicationId)?.listeners.delete(turn.listener);
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    discardUnstartedTurn(turn) {
+        if (turn.held.pendingTurn === turn) {
+            delete turn.held.pendingTurn;
+        }
+        turn.held.listeners.delete(turn.listener);
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    armPostTurnRelease(held, turn) {
+        this.clearTimers(held);
+        const delayMs = this.options.releaseAfterTurnMs ?? DEFAULT_RELEASE_AFTER_TURN_MS;
+        held.idleTimer = setTimeout(() => {
+            const active = this.turns.get(held.applicationId);
+            if (active && active !== turn && !active.finished) {
+                return;
+            }
+            if (this.held.get(held.applicationId) === held) {
+                this.drop(held);
+            }
+        }, delayMs);
+        held.idleTimer.unref?.();
+    }
+    armKeepalive(held) {
+        if (held.keepaliveTimer) {
+            clearInterval(held.keepaliveTimer);
+            held.keepaliveTimer = undefined;
+        }
+        if (!held.keepalive) {
+            return;
+        }
+        const keepaliveMs = this.options.keepaliveMs ?? DEFAULT_KEEPALIVE_MS;
+        held.keepaliveTimer = setInterval(() => {
+            void held.keepalive?.().catch(() => {
+                // Best-effort: a failed connect refresh must not tear down the held
+                // session socket; the next MCP call will reconnect if needed.
+            });
+        }, keepaliveMs);
+        held.keepaliveTimer.unref?.();
+    }
+    /**
+     * Clears the turn timers only. The beat is stopped separately on purpose: it
+     * belongs to the socket and outlives these, which the post-turn grace period
+     * resets.
+     */
+    clearIdleTimer(held) {
+        if (held.idleTimer) {
+            clearTimeout(held.idleTimer);
+            held.idleTimer = undefined;
+        }
+    }
+    clearTimers(held) {
+        this.clearIdleTimer(held);
+        if (held.keepaliveTimer) {
+            clearInterval(held.keepaliveTimer);
+            held.keepaliveTimer = undefined;
+        }
+    }
+    drop(held, options = {}) {
+        console.error("gateway held session released", {
+            applicationId: held.applicationId,
+        });
+        held.dropping = true;
+        const observed = this.observedTurns.get(held.applicationId);
+        if (observed?.held === held &&
+            !(options.preserveFinishedObserved && observed.finished)) {
+            this.forgetObservedTurn(held.applicationId);
+        }
+        this.clearTimers(held);
+        held.heartbeat.stop();
+        // Only if it is still the current session: a reattach registers its
+        // replacement before closing this one, and unregistering by app id alone
+        // would take the replacement out of the map with it.
+        if (this.held.get(held.applicationId) === held) {
+            this.held.delete(held.applicationId);
+        }
+        try {
+            held.socket.close("held session released");
+        }
+        catch {
+            // Socket may already be closed.
+        }
+        try {
+            if (held.ws.readyState === WebSocket.OPEN ||
+                held.ws.readyState === WebSocket.CONNECTING) {
+                held.ws.close();
+            }
+        }
+        catch {
+            // Ignore double-close.
+        }
+    }
+    editorContextFor(held) {
+        if (!held?.apiKey ||
+            !held.organizationId ||
+            !held.sessionToken ||
+            !this.options.server ||
+            !held.orchestrator) {
+            return undefined;
+        }
+        return {
+            apiKey: held.apiKey,
+            applicationId: held.applicationId,
+            branchName: held.branchName,
+            organizationId: held.organizationId,
+            orchestrator: held.orchestrator,
+            profileKey: held.profileKey ?? pickEditorProfileKey(this.options.profileKey, []),
+            server: this.options.server,
+            sessionToken: held.sessionToken,
+            waitUntilFilesSynced: async () => {
+                const collector = this.turns.get(held.applicationId)?.collector;
+                if (!collector) {
+                    return true;
+                }
+                return await collector.waitUntilInSync({
+                    timeoutMs: this.options.readyWaitMs ?? DEFAULT_READY_WAIT_MS,
+                });
+            },
+        };
+    }
+    /**
+     * Context the sandbox needs before it will let Clark drive a browser.
+     *
+     * Absent when headless testing is off or the session is missing something
+     * the app shell cannot boot without — Clark then runs the turn with its
+     * ordinary tools rather than failing it.
+     */
+    browserContextFor(held) {
+        if (!this.options.testingEnabled) {
+            return undefined;
+        }
+        return this.buildHeldBrowserContext(held);
+    }
+    /**
+     * Library iframe bootstrap from a held session. Used for Gateway's own
+     * live-canvas screenshot even when Clark's in-sandbox Playwright is off.
+     */
+    buildHeldBrowserContext(held) {
+        if (!held.orchestratorUrl) {
+            console.error("gateway live canvas skipped: missing_orchestrator_url", {
+                applicationId: held.applicationId,
+            });
+            return undefined;
+        }
+        if (!this.options.uiBaseUrl) {
+            console.error("gateway live canvas skipped: missing_ui_base_url", {
+                applicationId: held.applicationId,
+            });
+            return undefined;
+        }
+        if (!held.sessionToken) {
+            console.error("gateway live canvas skipped: missing_session_token", {
+                applicationId: held.applicationId,
+            });
+            return undefined;
+        }
+        return buildBrowserContext({
+            ...(held.apiKey ? { apiKey: held.apiKey } : {}),
+            applicationId: held.applicationId,
+            liveEditUrl: held.liveEdit.url,
+            orchestratorUrl: held.orchestratorUrl,
+            organizationId: held.organizationId,
+            peerId: held.peerId,
+            profileKey: held.profileKey,
+            profiles: held.profiles,
+            sessionToken: held.sessionToken,
+            uiBaseUrl: this.options.uiBaseUrl,
+            userId: held.userId,
+        });
+    }
+    /**
+     * Resolves a real org profile key once per held session. Sending the legacy
+     * placeholder `default` makes the orchestrator fail every integration query
+     * with "Invalid profile specified" / HTTP 500.
+     */
+    async resolveHeldProfileKey(held) {
+        if (held.profileKey || !held.apiKey || !held.organizationId) {
+            return;
+        }
+        if (!this.options.server) {
+            held.profileKey = pickEditorProfileKey(this.options.profileKey, []);
+            return;
+        }
+        try {
+            const profiles = await this.options.server.getOrganizationProfiles({
+                apiKey: held.apiKey,
+                organizationId: held.organizationId,
+            });
+            held.profiles = profiles;
+            held.profileKey = pickEditorProfileKey(this.options.profileKey, profiles);
+            console.error("gateway resolved integration profile", {
+                applicationId: held.applicationId,
+                organizationId: held.organizationId,
+                profileKey: held.profileKey,
+                preferred: this.options.profileKey,
+            });
+        }
+        catch (error) {
+            held.profileKey = pickEditorProfileKey(this.options.profileKey, []);
+            console.warn("gateway failed to list org profiles; using fallback", {
+                applicationId: held.applicationId,
+                message: error instanceof Error ? error.message : String(error),
+                profileKey: held.profileKey,
+            });
+        }
+    }
+    /**
+     * Discovers the orchestrator / agent base URL the way the browser does:
+     * Server `/users/me` agents filtered by org agentType, Active status, and
+     * profile tags. Operators never set this URL.
+     */
+    async resolveHeldOrchestrator(held) {
+        if (held.orchestrator || held.orchestratorUrl) {
+            return;
+        }
+        if (this.options.orchestrator || this.options.orchestratorUrl) {
+            held.orchestrator = this.options.orchestrator;
+            held.orchestratorUrl = this.options.orchestratorUrl;
+            return;
+        }
+        if (!held.apiKey || !held.organizationId || !this.options.server) {
+            return;
+        }
+        const profileKey = held.profileKey ?? pickEditorProfileKey(this.options.profileKey, []);
+        try {
+            const inventory = await this.options.server.getAgentInventory({
+                apiKey: held.apiKey,
+                organizationId: held.organizationId,
+            });
+            const orchestratorUrl = pickOrchestratorBaseUrl({
+                agentType: inventory.agentType,
+                agents: inventory.agents,
+                profileKey,
+            });
+            held.orchestratorUrl = orchestratorUrl;
+            held.orchestrator = new HttpOrchestratorClient(orchestratorUrl);
+            console.error("gateway resolved orchestrator url", {
+                applicationId: held.applicationId,
+                organizationId: held.organizationId,
+                orchestratorUrl,
+                profileKey,
+            });
+        }
+        catch (error) {
+            console.warn("gateway failed to discover orchestrator url", {
+                applicationId: held.applicationId,
+                message: error instanceof Error ? error.message : String(error),
+                organizationId: held.organizationId,
+                profileKey,
+            });
+        }
+    }
+}
+//# sourceMappingURL=websocket-session-peer.js.map