@superblocksteam/gateway 2.0.155-next.0

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

@@ -0,0 +1,2487 @@
+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 { NormalizedTurnCollector } from "../events/normalized-collector.js";
+import { pickEditorProfileKey } from "../integrations/profile-key.js";
+import { HttpOrchestratorClient, } from "../orchestrator/client.js";
+import { buildBrowserContext } from "./browser-context.js";
+import { createEditorClientMethods, loadIntegrationsForPrompt, } from "./editor-client-methods.js";
+import { appendRecentToolRun, buildRecentToolRun } from "./recent-tool-runs.js";
+import { DEFAULT_SETTLE_MS, TurnCollector } from "./turn-collector.js";
+/**
+ * A prompt reaches Clark over the dev server's socket, not over HTTP: the
+ * sandbox exposes no HTTP route that starts a generation. This is the same
+ * call the editor makes when a user submits a prompt in the browser.
+ */
+const GENERATE_METHOD = "editor.aiGenerateWithQueue";
+/**
+ * Commits the files Clark wrote as a draft and creates the checkpoint. The
+ * browser editor fires this automatically once files are in sync; a headless
+ * peer that skips it leaves the app uncommitted, so the build only finishes
+ * when a human finally opens the edit URL.
+ */
+const ACCEPT_DRAFT_METHOD = "editor.aiAcceptDraft";
+const RELOAD_CHAT_METHOD = "editor.aiChatGetMessages";
+const RESPOND_TOOL_PERMISSION_METHOD = "editor.aiRespondToToolPermission";
+/**
+ * The cheapest authorized call there is, used as the gateway's liveness beat.
+ *
+ * Deliberately sent without `isUserActive`: the sandbox counts that as a person
+ * at a keyboard, and a headless peer is not one.
+ */
+const PING_METHOD = "editor.ping";
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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,
+    };
+}
+/**
+ * How long a dead start stays worth reporting. Past this the caller it was
+ * recorded for is not coming back for it, and the record is only holding
+ * memory.
+ */
+const DEFAULT_FAILED_START_TTL_MS = 30 * 60 * 1000;
+/**
+ * Bound on distinct apps holding a dead start at once, so a pathological caller
+ * cannot grow this without limit.
+ */
+const MAX_FAILED_STARTS = 256;
+/**
+ * Dead starts, scoped to the caller whose prompt died and bounded in both age
+ * and count.
+ *
+ * Scoped because a connect failure is not a fact about the application:
+ * `connectLiveEdit` is where Superblocks authorizes the caller, and Superblocks
+ * authorizes per application, so a caller with no rights to this one still
+ * reaches the failure path. Keyed any wider, its record is what everyone who
+ * *does* have rights reads as the app's status - by application alone that was
+ * every organization, and by organization it was every colleague. The record
+ * exists so the caller who just failed gets an honest answer and can retry, and
+ * that caller is who it is keyed to.
+ *
+ * Bounded because nothing else evicts: an app whose start failed and that is
+ * never retried would otherwise hold its entry for the life of the process.
+ */
+class FailedStarts {
+    entries = new Map();
+    ttlMs;
+    maxEntries;
+    constructor(ttlMs, maxEntries) {
+        this.ttlMs = ttlMs ?? DEFAULT_FAILED_START_TTL_MS;
+        this.maxEntries = maxEntries ?? MAX_FAILED_STARTS;
+    }
+    set(scope, turn) {
+        const key = this.keyOf(scope);
+        // Re-inserted rather than updated in place, so this key becomes the newest
+        // and the eviction below stays in insertion order.
+        this.entries.delete(key);
+        this.entries.set(key, { at: Date.now(), turn });
+        for (const oldest of this.entries.keys()) {
+            if (this.entries.size <= this.maxEntries) {
+                break;
+            }
+            this.entries.delete(oldest);
+        }
+    }
+    get(scope) {
+        const key = this.keyOf(scope);
+        const entry = this.entries.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (Date.now() - entry.at >= this.ttlMs) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.turn;
+    }
+    /**
+     * Forget every caller's record for this application. The reads are scoped,
+     * but acceptance is not: a prompt Superblocks took means the app has a live
+     * turn, and nobody's dead start outranks that.
+     */
+    clear(applicationId) {
+        for (const key of [...this.entries.keys()]) {
+            if (key.endsWith(`\u0000${applicationId}`)) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    /**
+     * Separated by NUL because no id can contain one. Any printable separator is
+     * a character an id could carry, and an id that carried it would key two
+     * different callers to the same entry.
+     */
+    keyOf(scope) {
+        return `${scope.organizationId}\u0000${scope.userId}\u0000${scope.applicationId}`;
+    }
+}
+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 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);
+    }
+}
+/**
+ * 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.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.refusals > 0) {
+        const beats = heartbeat.refusals === 1 ? "beat" : "beats";
+        const cause = heartbeat.lastError ? ` (${heartbeat.lastError})` : "";
+        // A refusal is an answer, so the connection worked and the peer named its
+        // own reason for the turn dying. Reported before a lapse because a refusal
+        // does not clear one: an earlier excused silence would otherwise outlive
+        // the beat that explained itself, and describing the socket as merely
+        // quiet throws away the only account the caller can act on.
+        return ` ${heartbeat.refusals} liveness ${beats} came back refused${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 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}` : ""}`);
+}
+export class WebSocketSessionPeer {
+    options;
+    held = 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();
+    /**
+     * Last plan Clark proposed per application, so approve/refine can re-send
+     * planContext without the MCP client echoing the full markdown.
+     */
+    pendingPlans = new Map();
+    /**
+     * Last needs_decision payload (plan or multi_choice) per application, so
+     * approve/refine via edit_app can reuse the pending plan after
+     * check_app_progress drained the finished turn.
+     */
+    pendingDecisions = new Map();
+    /**
+     * Applications that have dispatched at least one BUILD turn. Survives
+     * clearing the pending plan, which happens as soon as an approved build
+     * starts — the point of the latch is the turns that come after it.
+     */
+    buildModeApplications = new Set();
+    /**
+     * Turns that died before Superblocks ever saw them, so no {@link ActiveTurn}
+     * was ever created to hold the outcome. Read by
+     * {@link WebSocketSessionPeer.turnState} and
+     * {@link WebSocketSessionPeer.awaitTurn} after the live map, and cleared when
+     * a prompt for the app is accepted.
+     */
+    failedStarts;
+    constructor(options = {}) {
+        this.options = options;
+        // Built here rather than as a field initializer: those run before the
+        // constructor's parameter properties are assigned, so `this.options` would
+        // still be undefined.
+        this.failedStarts = new FailedStarts(options.failedStartTtlMs, options.maxFailedStarts);
+    }
+    /**
+     * Plan waiting on human approve/refine for this application, if any.
+     */
+    pendingPlan(applicationId) {
+        return this.pendingPlans.get(applicationId);
+    }
+    /**
+     * Full needs_decision payload waiting on a human for this application.
+     */
+    pendingDecision(applicationId) {
+        return this.pendingDecisions.get(applicationId);
+    }
+    /**
+     * Remember a turn that never reached Superblocks. See
+     * {@link SessionPeer.recordFailedStart}.
+     */
+    recordFailedStart(input) {
+        const running = this.turns.get(input.applicationId);
+        if (running && !running.finished) {
+            // A turn is already running for this app, and a second prompt that could
+            // not open its own session did not end it. Recording anyway is what makes
+            // the precedence in `turnState` unreadable: the same pair of facts - one
+            // finished turn, one record - would mean "the record came later" when the
+            // turn had already ended and "the turn came later" when it ended after,
+            // with nothing left in memory to say which. Skipping keeps every stored
+            // record older than any finished turn it can be read beside.
+            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.failedStarts.set(input, {
+            generationStatus: "live_edit_terminated",
+            reply: input.reason,
+            // 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",
+        });
+    }
+    /**
+     * Where this application's turn stands for this caller, read without draining
+     * the activity an {@link WebSocketSessionPeer.awaitTurn} poll is owed.
+     *
+     * Order matters, and it is recency. A turn still *running* is live work and
+     * outranks everything - a second prompt failing to open its own session does
+     * not end it. Failing that, this caller's own dead start outranks a turn that
+     * already finished: `turns` keeps finished turns, so without this a follow-up
+     * whose connect failed would be answered by the previous turn's outcome and
+     * its reply, reporting an edit as landed that never ran. And it is read rather
+     * than superseded by deleting from `turns`, because that map is keyed by
+     * application while a dead start belongs to one caller - deleting would erase
+     * a colleague's outcome to answer this caller's question.
+     *
+     * Reading recency out of the order rather than out of a clock holds because
+     * of the two rules either side of this one: accepting a prompt clears every
+     * caller's record for the app, and no record is made while a turn is running.
+     * Together they leave every stored record newer than any finished turn it can
+     * be read beside, so "the record wins" is not a guess about which came first.
+     */
+    turnState(input) {
+        const turn = this.turns.get(input.applicationId);
+        if (turn && !turn.finished) {
+            return { phase: "running" };
+        }
+        const failed = this.failedStarts.get(input);
+        if (failed) {
+            return { generationStatus: failed.generationStatus, phase: "finished" };
+        }
+        if (!turn?.finished) {
+            return undefined;
+        }
+        return {
+            ...(turn.finished.checkpointCommitId
+                ? { checkpointCommitId: turn.finished.checkpointCommitId }
+                : {}),
+            generationStatus: turn.finished.generationStatus,
+            phase: "finished",
+        };
+    }
+    clearPendingPlan(applicationId) {
+        this.pendingPlans.delete(applicationId);
+        this.pendingDecisions.delete(applicationId);
+    }
+    clearPendingDecision(applicationId) {
+        this.pendingPlans.delete(applicationId);
+        this.pendingDecisions.delete(applicationId);
+    }
+    markBuildMode(applicationId) {
+        this.buildModeApplications.add(applicationId);
+    }
+    buildMode(applicationId) {
+        return this.buildModeApplications.has(applicationId);
+    }
+    isHeld(applicationId) {
+        const entry = this.held.get(applicationId);
+        return Boolean(entry && isSocketOpen(entry.ws));
+    }
+    libraryBrowserContext(applicationId) {
+        const held = this.held.get(applicationId);
+        if (!held) {
+            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 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);
+        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) {
+        this.buildModeApplications.delete(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,
+                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");
+            }
+        }
+    }
+    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 Error(`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 Error("Prompt forward failed: userId is required to identify who the turn is running for");
+        }
+        const userId = input.userId;
+        // Connecting and waiting for the acknowledgement share one budget. Giving
+        // each the full timeout let a slow sandbox spend twice it, and the caller
+        // that is waiting on the tool call gives up long before that.
+        const deadline = Date.now() + timeoutMs;
+        const held = await this.ensureHeld({
+            applicationId: input.applicationId,
+            branchName: input.branch,
+            keepalive: input.keepalive,
+            liveEdit: liveEditOf(input),
+            ...(input.resolveLiveEdit
+                ? { resolveLiveEdit: input.resolveLiveEdit }
+                : {}),
+            userId,
+        }, deadline);
+        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);
+        // A turn already running for this app is over as far as callers are
+        // concerned: its outcome belongs to the prompt being replaced.
+        this.supersedeTurn(input.applicationId);
+        this.clearPendingDecision(input.applicationId);
+        const turn = {
+            abort: new AbortController(),
+            activity: [],
+            collector: undefined,
+            delivered: 0,
+            heardAtLastReconnect: 0,
+            held,
+            listener: () => undefined,
+            normalized: undefined,
+            recentRuns: [],
+            reconnects: 0,
+            startedAt: Date.now(),
+            turnId: randomUUID(),
+            unsubscribe: () => undefined,
+            waiters: new Set(),
+        };
+        const report = (message) => {
+            this.note(turn, message);
+            input.onProgress?.(message);
+        };
+        const collector = new TurnCollector(report, { settleMs });
+        turn.collector = collector;
+        const normalized = new NormalizedTurnCollector({
+            collector,
+            onAuthRequired: (reason) => report(`Superblocks needs an interactive authorization (${reason})`),
+            onSessionStatus: (status) => {
+                if (status === "terminated") {
+                    this.abandonTurnOnSessionTerminated(input.applicationId, turn);
+                }
+            },
+            turnId: turn.turnId,
+        });
+        turn.normalized = normalized;
+        // Both transports go through the normalized collector rather than into
+        // the collector directly: during the transition Clark's activity arrives
+        // on the socket and relayed through SABS, and the turn must not count the
+        // same message twice because it heard it twice.
+        const listener = (event) => normalized.fromSocket(event);
+        turn.listener = listener;
+        held.listeners.add(listener);
+        // The session the socket actually landed on, which is not the one the
+        // prompt named if the live edit had moved. The held record is the only
+        // authority: it was seeded from this prompt's pair and has since been
+        // replaced by anything the connect learned, so falling back to the
+        // prompt's id could only reinstate one the socket moved away from.
+        turn.unsubscribe = this.subscribeToPushes(held.liveEdit.id, normalized);
+        try {
+            return await this.sendPrompt({ held, input, listener, turn });
+        }
+        catch (error) {
+            // Every failure between here and the turn being handed to runTurn ends
+            // the turn where it stands, and the push subscription has to go with it.
+            turn.unsubscribe();
+            throw error;
+        }
+    }
+    /**
+     * 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, listener, turn } = args;
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        let integrations = [];
+        const editorContext = this.editorContextFor(held);
+        if (editorContext) {
+            try {
+                integrations = await loadIntegrationsForPrompt(editorContext);
+            }
+            catch (error) {
+                console.warn("gateway failed to prefill prompt integrations", {
+                    applicationId: input.applicationId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        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 held.client.requestWithTracing(GENERATE_METHOD, {
+                ...(browserContext ? { browserContext } : {}),
+                jwt: input.sessionToken,
+                llmConfig: {
+                    coreModel: this.options.coreModel ?? DEFAULT_LLM.coreModel,
+                    // 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: [],
+                    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 }
+                    : {}),
+                ...(input.importSource ? { importSource: input.importSource } : {}),
+                queueMode: "interrupt",
+                requestId: turn.turnId,
+                userPreferences: { suggestNextSteps: false },
+            }, {}, `Bearer ${input.sessionToken}`);
+        }
+        catch (error) {
+            held.listeners.delete(listener);
+            const rejection = error;
+            if (isAuthRejection(rejection)) {
+                turn.unsubscribe();
+                this.armIdle(held);
+                this.armKeepalive(held);
+                return {
+                    message: "Interactive auth required for datasource access",
+                    status: "auth_required",
+                };
+            }
+            if (isTimeout(rejection)) {
+                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"}`);
+        }
+        this.assertHeadlessTurnBound({
+            acknowledgment,
+            held,
+            listener,
+            turn,
+        });
+        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 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.failedStarts.clear(input.applicationId);
+        this.turns.set(input.applicationId, turn);
+        // 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",
+        };
+    }
+    async awaitTurn(input) {
+        const turn = this.turns.get(input.applicationId);
+        // The same recency order as turnState: a turn still running outranks
+        // everything, and this caller's own dead start outranks a turn that already
+        // finished. A finished turn with no dead start against it is reported as
+        // itself, below. A poll that cannot say who it is for reads no record at
+        // all - the records belong to callers, not to the application.
+        const failed = (!turn || turn.finished) && input.organizationId && input.userId
+            ? this.failedStarts.get({
+                applicationId: input.applicationId,
+                organizationId: input.organizationId,
+                userId: input.userId,
+            })
+            : 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) {
+            return { activity: [], elapsedMs: 0, status: "unknown" };
+        }
+        if (turn.delivered >= turn.activity.length && !turn.finished) {
+            await new Promise((resolve) => {
+                const settle = () => {
+                    clearTimeout(timer);
+                    turn.waiters.delete(settle);
+                    input.signal?.removeEventListener("abort", settle);
+                    resolve();
+                };
+                const timer = setTimeout(settle, Math.max(0, input.waitMs));
+                turn.waiters.add(settle);
+                input.signal?.addEventListener("abort", settle, { once: true });
+            });
+        }
+        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,
+                elapsedMs,
+                status: "finished",
+                ...turn.finished,
+                ...(recentRuns ? { recentRuns } : {}),
+            };
+        }
+        return {
+            activity,
+            elapsedMs,
+            status: "running",
+            ...(recentRuns ? { recentRuns } : {}),
+        };
+    }
+    /**
+     * 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 checkpointCommitId;
+        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") {
+                // 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.
+                checkpointCommitId = await this.checkpoint({
+                    collector,
+                    held: turn.held,
+                    onProgress: report,
+                    readyWaitMs,
+                    sessionToken: input.sessionToken,
+                    turnId: turn.turnId,
+                });
+                this.clearPendingDecision(input.applicationId);
+            }
+            if (turn.finished) {
+                return;
+            }
+            const decision = collector.decision();
+            if (generationStatus === "needs_decision" && decision) {
+                const reply = collector.reply();
+                this.pendingDecisions.set(input.applicationId, {
+                    decision,
+                    ...(turn.recentRuns.length > 0
+                        ? { recentRuns: [...turn.recentRuns] }
+                        : {}),
+                    reply,
+                });
+                if (decision.kind === "plan") {
+                    this.pendingPlans.set(input.applicationId, {
+                        ...(decision.messageId ? { messageId: decision.messageId } : {}),
+                        plan: decision.plan,
+                        ...(decision.title ? { title: decision.title } : {}),
+                    });
+                }
+                else {
+                    this.pendingPlans.delete(input.applicationId);
+                }
+            }
+            // Disconnect / supersede already wrote the authoritative outcome; never
+            // overwrite that with a later collector timeout or terminal status.
+            turn.finished ??= {
+                ...(checkpointCommitId ? { checkpointCommitId } : {}),
+                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);
+            // The turn is over on both transports before the collector is disposed:
+            // a push arriving afterwards would otherwise be handed to it.
+            turn.unsubscribe();
+            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;
+            if (stillMapped) {
+                // Held a little longer than the turn so the sandbox startup watchdog and
+                // idle reaper still see an attached peer while the build lands, then let
+                // go: nothing headless is waiting on it after that, and the sandbox
+                // should be free to go idle on the user's own terms.
+                //
+                // A turn that ended on a question is the exception. The human answer is
+                // the next thing that will happen to this app, and the sandbox reaps
+                // itself once no socket is attached — letting go here means the answer,
+                // minutes later, lands on a dev server that has already exited. Hold the
+                // session on the ordinary idle timer instead.
+                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;
+    }
+    /**
+     * Attaches a turn to the events SABS relays for its live edit, returning the
+     * idempotent detach the turn calls when it ends.
+     *
+     * A turn with no live edit id, or a deployment with no push channel, gets a
+     * detach that does nothing: the socket remains its only source, which is the
+     * behavior from before the channel existed.
+     */
+    subscribeToPushes(_liveEditId, _normalized) {
+        // Stdio Gateway has no SABS HTTP push ingress (ENG-5797). The held
+        // socket is the only event source; the detach is a no-op so turn
+        // teardown stays the same shape as the parent branch.
+        return () => undefined;
+    }
+    /**
+     * 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;
+        }
+        input.held.listeners.delete(input.listener);
+        this.release(input.held.applicationId);
+        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; restart the sandbox to pick up the current one.`);
+    }
+    /**
+     * 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.listeners.add(turn.listener);
+        previous.listeners.delete(turn.listener);
+        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) {
+            fresh.listeners.delete(turn.listener);
+            this.drop(fresh);
+            return { kind: "stale" };
+        }
+        if (claim === "unreachable") {
+            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") {
+            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.held.set(previous.applicationId, previous);
+            }
+            this.drop(fresh);
+            return { kind: "refused" };
+        }
+        turn.held = fresh;
+        this.drop(previous);
+        // A reconnect that followed the session to another host is still listening
+        // to SABS under the id the turn started with, which is not the one the
+        // moved session relays under. Left alone the turn hears nothing from the
+        // transport that outlives its socket - the same trap the prompt path names
+        // when it subscribes under the id its connect landed on.
+        if (fresh.liveEdit.id && fresh.liveEdit.id !== previous.liveEdit.id) {
+            turn.unsubscribe();
+            turn.unsubscribe = this.subscribeToPushes(fresh.liveEdit.id, turn.normalized);
+        }
+        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;
+    }
+    /**
+     * 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 input.held.client.requestWithTracing(RELOAD_CHAT_METHOD, { force: false, ...this.turnCorrelator(input.turnId) }, {}, `Bearer ${input.sessionToken}`);
+            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) {
+        const connect = 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);
+        // Published so a prompt arriving mid-reattach waits for this socket instead
+        // of opening a third one.
+        this.connecting.set(previous.applicationId, connect);
+        try {
+            return await connect;
+        }
+        finally {
+            this.connecting.delete(previous.applicationId);
+        }
+    }
+    /** 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");
+            return undefined;
+        }
+        input.onProgress?.("Saving a checkpoint");
+        try {
+            const result = await input.held.client.requestWithTracing(ACCEPT_DRAFT_METHOD, {
+                screenshotDataUrl: null,
+                silently: true,
+                ...this.turnCorrelator(input.turnId),
+            }, {}, `Bearer ${input.sessionToken}`);
+            input.collector.markCheckpointed();
+            const commitId = result?.commitId?.trim() ? result.commitId : 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 input.held.client.requestWithTracing(RELOAD_CHAT_METHOD, { force: true, ...this.turnCorrelator(input.turnId) }, {}, `Bearer ${input.sessionToken}`);
+                }
+                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?.(commitId ? "Checkpoint saved" : "App already up to date");
+            return commitId;
+        }
+        catch (error) {
+            console.warn("gateway clark checkpoint failed", {
+                applicationId: input.held.applicationId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            input.onProgress?.("Could not save a checkpoint for Superblocks' changes");
+            return undefined;
+        }
+    }
+    async ensureHeld(input, deadline) {
+        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;
+                // 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);
+        }
+        if (existing) {
+            this.drop(existing);
+        }
+        const connect = this.connect(input, deadline);
+        this.connecting.set(input.applicationId, connect);
+        try {
+            return await connect;
+        }
+        finally {
+            this.connecting.delete(input.applicationId);
+        }
+    }
+    async connect(input, deadline) {
+        // 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 listeners = heldRef.current?.listeners;
+            if (!listeners || listeners.size === 0) {
+                return undefined;
+            }
+            return (event) => {
+                for (const listener of [...listeners]) {
+                    listener(event);
+                }
+            };
+        }, (method) => {
+            this.inboundMethods.add(method);
+        }, {
+            getContext: () => this.editorContextFor(heldRef.current),
+            onToolRun: (run) => {
+                const current = heldRef.current;
+                if (!current) {
+                    return;
+                }
+                const turn = this.turns.get(current.applicationId);
+                if (!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;
+                }
+                try {
+                    await current.client.requestWithTracing(RESPOND_TOOL_PERMISSION_METHOD, {
+                        approved: payload.approved,
+                        ...this.turnCorrelator(this.turns.get(current.applicationId)?.turnId),
+                        messageId: payload.messageId,
+                        requestId: payload.requestId ?? payload.messageId,
+                    }, {}, current.sessionToken
+                        ? `Bearer ${current.sessionToken}`
+                        : undefined);
+                }
+                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;
+                // Its own closes - a reattach swapping sockets, a release - leave the
+                // turn either running elsewhere or already settled.
+                if (held?.dropping) {
+                    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,
+            socket,
+            userId: input.userId,
+            ws,
+        };
+        heldRef.current = held;
+        this.held.set(input.applicationId, 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.
+        heartbeat.start();
+        return held;
+    }
+    /**
+     * 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 held.client.requestWithTracing(PING_METHOD, this.turnCorrelator(this.turns.get(held.applicationId)?.turnId), {}, `Bearer ${held.sessionToken}`);
+            },
+            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;
+                }
+                // 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.beatLostAt = 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.beatLostAt ??= Date.now();
+                }
+                if (held.beatLostAt === undefined) {
+                    return;
+                }
+                const graceMs = this.options.beatLostGraceMs ?? DEFAULT_BEAT_LOST_GRACE_MS;
+                if (Date.now() - held.beatLostAt >= graceMs) {
+                    this.abandonTurnOnBeatLost(held.applicationId, account);
+                }
+            },
+            // 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,
+        });
+    }
+    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.
+     *
+     * Two gates, because they 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.
+     *
+     * 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(applicationId, heartbeat) {
+        const turn = this.turns.get(applicationId);
+        // 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 || turn.finished || turn.collector.status()) {
+            return;
+        }
+        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()));
+    }
+    /**
+     * 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;
+        }
+        prior.finished ??= {
+            reply: "This turn was replaced by a newer prompt on the same app, so its work was cancelled.",
+            generationStatus: "cancelled",
+            viewStatus: prior.collector.viewableStatus(),
+        };
+        const held = this.held.get(applicationId);
+        held?.listeners.delete(prior.listener);
+        prior.unsubscribe();
+        prior.collector.dispose();
+        prior.abort.abort();
+        this.wake(prior);
+    }
+    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.
+     */
+    clearTimers(held) {
+        if (held.idleTimer) {
+            clearTimeout(held.idleTimer);
+            held.idleTimer = undefined;
+        }
+        if (held.keepaliveTimer) {
+            clearInterval(held.keepaliveTimer);
+            held.keepaliveTimer = undefined;
+        }
+    }
+    drop(held) {
+        console.error("gateway held session released", {
+            applicationId: held.applicationId,
+        });
+        held.dropping = true;
+        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