@superblocksteam/gateway 2.0.161 → 2.0.162-next.1

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

@@ -1,37 +1,23 @@
 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 { canonicalizeOrchestratorBaseUrl, pickOrchestratorBaseUrl, } from "../agents/resolve-orchestrator-url.js";
+import { gatewayDebug } from "../debug.js";
 import { pickEditorProfileKey } from "../integrations/profile-key.js";
 import { HttpOrchestratorClient, } from "../orchestrator/client.js";
+import { recordCheckpointOutcome } from "../telemetry/metrics.js";
+import { sanitizeAgentFacingText } from "./agent-facing-text.js";
+import { AppState } from "./app-state.js";
 import { buildBrowserContext } from "./browser-context.js";
 import { createEditorClientMethods, loadIntegrationsForPrompt, } from "./editor-client-methods.js";
+import { EditorSocket } from "./editor-socket.js";
 import { appendRecentToolRun, buildRecentToolRun } from "./recent-tool-runs.js";
+import { PromptNotSentError, } from "./session-peer.js";
 import { DEFAULT_SETTLE_MS, TurnCollector } from "./turn-collector.js";
-/**
- * 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 RELEASE_TURN_LOCK_METHOD = "editor.releaseTurnLock";
-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";
+function editorStructureScopeKey(applicationId, branch) {
+    return `${applicationId}\u0000${branch?.trim() ?? ""}`;
+}
 /**
  * Whole budget for connecting and getting the prompt acknowledged, so a
  * session that accepts the socket but never answers cannot strand the MCP call
@@ -42,6 +28,8 @@ const PING_METHOD = "editor.ping";
  * was failing on a tighter budget only to succeed on the retry.
  */
 const DEFAULT_TIMEOUT_MS = 120_000;
+/** Playwright capture (45s + 2.5s settle) plus one held-socket RPC budget. */
+const DEFAULT_CHECKPOINT_SCREENSHOT_TIMEOUT_MS = 180_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
@@ -58,10 +46,36 @@ const CONNECT_RETRY_DELAY_MS = 500;
  * 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.
+ * that succeeds clears it.
  */
 const DEFAULT_BEAT_LOST_GRACE_MS = 60_000;
+const DEFAULT_BEAT_HEALTH_TIMEOUT_MS = 3_000;
+async function liveEditIsHealthy(input) {
+    if (!input.sessionToken) {
+        return false;
+    }
+    try {
+        const response = await fetch(new URL("/_sb_health", input.liveEditUrl).toString(), {
+            headers: {
+                Authorization: `Bearer ${input.sessionToken}`,
+            },
+            signal: AbortSignal.timeout(DEFAULT_BEAT_HEALTH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const body = await response.json();
+        return (typeof body === "object" &&
+            body !== null &&
+            "applicationId" in body &&
+            body.applicationId === input.applicationId &&
+            "status" in body &&
+            body.status === "healthy");
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Consecutive upgrade rejections from one host before asking where the live
  * edit went. More than one, so an ingress route that briefly answers for a pod
@@ -125,18 +139,21 @@ const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15 * 1000;
  * 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.";
+function tagRetryableLiveEditDeath(turn, outcome) {
+    if (outcome.generationStatus !== "live_edit_terminated") {
+        return;
+    }
+    if (outcome.retryable === false || outcome.recoveryAction) {
+        return;
+    }
+    turn.retryAction ??= "retry_build";
+}
 /**
  * How long a turn waits for Clark's first push before suspecting the sandbox is
  * not reporting into this socket.
@@ -164,8 +181,7 @@ 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.
+ * on, so reconnect attempts are capped independently.
  */
 const DEFAULT_RECONNECT_ATTEMPTS = 3;
 /**
@@ -173,6 +189,7 @@ const DEFAULT_RECONNECT_ATTEMPTS = 3;
  * Clark's files before giving up on checkpointing them.
  */
 const DEFAULT_READY_WAIT_MS = 30_000;
+const PENDING_START_POLL_INTERVAL_MS = 250;
 /**
  * The role the dev server classifies this connection as. A gateway peer gets
  * Clark's pushes for the turns it starts and its own sandbox-liveness signal,
@@ -202,86 +219,11 @@ function liveEditOf(source) {
         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}`;
-    }
+function isBrowserObserverEvent(event) {
+    return ((event.kind === "message" &&
+        event.message.gatewayObserverSource === "browser") ||
+        (event.kind === "generation_state" &&
+            event.gatewayObserverSource === "browser"));
 }
 export function buildSessionUrl(input) {
     // liveEditUrl is server-sourced (connectLiveEdit), not caller-supplied, so a
@@ -333,6 +275,15 @@ function isHostRejection(error) {
 function isTimeout(error) {
     return /timed out|timeout/i.test(error.message ?? "");
 }
+function isRemoteRejection(error) {
+    // ISocket reserves 7-10 for timeout, connection close, abort, and a request
+    // made after close. Every other numbered code arrived in a response.
+    return (error.code !== undefined &&
+        error.code !== 7 &&
+        error.code !== 8 &&
+        error.code !== 9 &&
+        error.code !== 10);
+}
 function isSocketOpen(ws) {
     return ws.readyState === WebSocket.OPEN;
 }
@@ -362,6 +313,54 @@ function describeSocketError(error) {
         return String(error);
     }
 }
+function checkpointFailure(error) {
+    const detail = typeof error === "object" && error !== null
+        ? error
+        : undefined;
+    const rawMessage = error instanceof Error
+        ? error.message
+        : typeof detail?.message === "string" && detail.message.length > 0
+            ? detail.message
+            : describeSocketError(error);
+    const message = sanitizeAgentFacingText(rawMessage).slice(0, 500);
+    const code = typeof detail?.code === "number" ? detail.code : undefined;
+    const status = typeof detail?.status === "number" ? detail.status : undefined;
+    const category = status === 408 || status === 504 || /timed out|timeout/i.test(message)
+        ? "timeout"
+        : status === 401 ||
+            status === 403 ||
+            code === 401 ||
+            code === 403 ||
+            /\b(?:401|403)\b|unauthoriz|forbidden/i.test(message)
+            ? "authentication"
+            : status === 409 || code === 409 || /\b409\b|conflict/i.test(message)
+                ? "conflict"
+                : "downstream";
+    return {
+        category,
+        ...(code === undefined ? {} : { code }),
+        message,
+        ...(status === undefined ? {} : { status }),
+    };
+}
+function normalizeCheckpointWarning(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const warning = value;
+    if (warning.code !== "draft_state_cleanup_failed" ||
+        typeof warning.message !== "string") {
+        return undefined;
+    }
+    const message = sanitizeAgentFacingText(warning.message).trim().slice(0, 500);
+    if (!message) {
+        return undefined;
+    }
+    return {
+        code: "draft_state_cleanup_failed",
+        message,
+    };
+}
 /**
  * What the socket said on its way out, appended to the disconnect reply.
  *
@@ -442,21 +441,30 @@ function describeOutstandingBeat(heartbeat, at) {
     return ` A beat sent ${seconds}s earlier had still not been answered.`;
 }
 function describeSettledBeats(heartbeat, at) {
+    if (heartbeat.refusals > 0) {
+        const beats = heartbeat.refusals === 1 ? "beat" : "beats";
+        // The refusal's own reason rather than `lastError`: an unanswered beat
+        // after the refusal overwrites that with its own cause while leaving
+        // `refusals` standing, so reading it here would put a timeout's message in
+        // the peer's mouth.
+        const stated = heartbeat.lastRefusalError ?? heartbeat.lastError;
+        const cause = stated ? ` (${stated})` : "";
+        // Reported ahead of the silence counts, and alongside them rather than
+        // instead of them. A refusal is an answer: the connection worked and the
+        // peer named its own reason for the turn dying, which no inferred silence
+        // outranks. But a refusal clears nothing, so "refused, then went quiet" is
+        // a different death from "refusing right up to the close" and the caller
+        // needs both halves to tell them apart.
+        const silence = heartbeat.failures > 0
+            ? ` ${heartbeat.failures} later ${heartbeat.failures === 1 ? "beat" : "beats"} went unanswered.`
+            : "";
+        return ` ${heartbeat.refusals} liveness ${beats} came back refused${cause}.${silence}`;
+    }
     if (heartbeat.failures > 0) {
         const beats = heartbeat.failures === 1 ? "beat" : "beats";
         const cause = heartbeat.lastError ? ` (${heartbeat.lastError})` : "";
         return ` ${heartbeat.failures} liveness ${beats} failed before it${cause}.`;
     }
-    if (heartbeat.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
@@ -534,6 +542,41 @@ async function withinDeadline(lookup, deadline) {
         }
     }
 }
+async function beforePromptDeadline(work, deadline, signal) {
+    if (signal?.aborted) {
+        throw new PromptNotSentError("Prompt forward cancelled before the live-edit request was sent", signal.reason);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        throw new PromptNotSentError("Prompt forward timed out before the live-edit request was sent");
+    }
+    let timer;
+    let onAbort;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new PromptNotSentError("Prompt forward timed out before the live-edit request was sent")), remaining);
+            }),
+            ...(signal
+                ? [
+                    new Promise((_resolve, reject) => {
+                        onAbort = () => reject(new PromptNotSentError("Prompt forward cancelled before the live-edit request was sent", signal.reason));
+                        signal.addEventListener("abort", onAbort, { once: true });
+                    }),
+                ]
+                : []),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        if (onAbort) {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
 async function open(url, attemptTimeoutMs, deadline, onSocketError, 
 /**
  * Where the live edit is now, asked for only once and only when the host in
@@ -589,9 +632,20 @@ nextHost) {
     }
     throw new Error(`Prompt forward timed out: ${current.host} did not accept a live-edit socket (${lastError instanceof Error ? lastError.message : String(lastError)})${current.host !== url.host ? ` after moving from ${url.host}` : ""}`);
 }
+/**
+ * The typed `editor.*` surface for a held session.
+ *
+ * Built per call rather than held on the session because the edit-scoped token
+ * travels with the request, not with the socket: a session outlives the token
+ * a given turn was authorized with.
+ */
+function editorSocket(held, sessionToken) {
+    return new EditorSocket(held.client, () => sessionToken ? `Bearer ${sessionToken}` : undefined);
+}
 export class WebSocketSessionPeer {
     options;
     held = new Map();
+    promptStarts = new Map();
     /**
      * Every server -> editor method the dev server has called on this peer.
      * Diagnostic only: it answers "did that push ever arrive" without guessing
@@ -609,64 +663,98 @@ export class WebSocketSessionPeer {
      * 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;
+    /** Browser-owned turns observed over an authenticated held session. */
+    observedTurns = new Map();
+    editorStructureByScope = new Map();
+    /** Facts about an application that outlive any one turn. */
+    appState;
     constructor(options = {}) {
         this.options = options;
-        // 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);
+        this.appState =
+            options.appState ??
+                new AppState({
+                    ...(options.failedStartTtlMs === undefined
+                        ? {}
+                        : { failedStartTtlMs: options.failedStartTtlMs }),
+                    ...(options.maxFailedStarts === undefined
+                        ? {}
+                        : { maxFailedStarts: options.maxFailedStarts }),
+                    ...(options.pendingStartTtlMs === undefined
+                        ? {}
+                        : { pendingStartTtlMs: options.pendingStartTtlMs }),
+                });
+    }
+    /** The per-application facts this peer writes, for the capability layer. */
+    state() {
+        return this.appState;
+    }
+    recordPendingStart(input) {
+        return this.appState.recordPendingStart(input, {
+            ...(input.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: input.idempotencyKey }),
+            ...(input.retryAction ? { retryAction: input.retryAction } : {}),
+        });
+    }
+    clearPendingStart(input) {
+        this.appState.clearPendingStart(input, input.idempotencyKey, undefined, input.pendingStartToken);
+    }
+    async waitForPendingTurn(input) {
+        for (;;) {
+            const turn = this.turns.get(input.applicationId);
+            if (turn &&
+                turn.revision > input.afterRevision &&
+                (input.idempotencyKey === undefined ||
+                    turn.idempotencyKey === input.idempotencyKey) &&
+                (input.pendingStartToken === undefined ||
+                    turn.pendingStartToken === input.pendingStartToken) &&
+                (input.scope.branch === undefined || input.scope.branch === turn.branch)) {
+                return turn;
+            }
+            if (input.signal?.aborted ||
+                !this.appState.pendingStart(input.scope) ||
+                Date.now() >= input.deadlineAtMs) {
+                return undefined;
+            }
+            await new Promise((resolve) => {
+                const settle = () => {
+                    clearTimeout(timer);
+                    input.signal?.removeEventListener("abort", settle);
+                    resolve();
+                };
+                const timer = setTimeout(settle, Math.min(PENDING_START_POLL_INTERVAL_MS, Math.max(0, input.deadlineAtMs - Date.now())));
+                input.signal?.addEventListener("abort", settle, { once: true });
+            });
+        }
     }
     /**
      * Plan waiting on human approve/refine for this application, if any.
      */
-    pendingPlan(applicationId) {
-        return this.pendingPlans.get(applicationId);
+    pendingPlan(applicationId, requestedBranch) {
+        return this.appState.pendingPlan(applicationId, requestedBranch);
     }
     /**
      * Full needs_decision payload waiting on a human for this application.
      */
-    pendingDecision(applicationId) {
-        return this.pendingDecisions.get(applicationId);
+    pendingDecision(applicationId, requestedBranch) {
+        return this.appState.pendingDecision(applicationId, requestedBranch);
     }
     /**
      * Remember a turn that never reached Superblocks. See
      * {@link SessionPeer.recordFailedStart}.
      */
     recordFailedStart(input) {
+        const pendingCleared = this.appState.clearPendingStart(input, input.idempotencyKey, undefined, input.pendingStartToken);
+        if (input.pendingStartRequired && !pendingCleared) {
+            return;
+        }
         const running = this.turns.get(input.applicationId);
-        if (running && !running.finished) {
-            // 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.
+        if (running &&
+            !running.finished &&
+            input.branch === running.branch &&
+            !(input.pendingStartRequired && pendingCleared)) {
+            // This failed prompt did not end the turn already running on its branch.
+            // Keeping its newer revision would hide that turn's eventual outcome.
             console.warn("gateway clark turn never started, but one is running", {
                 applicationId: input.applicationId,
                 organizationId: input.organizationId,
@@ -681,81 +769,99 @@ export class WebSocketSessionPeer {
             reason: input.reason,
             userId: input.userId,
         });
-        this.failedStarts.set(input, {
-            generationStatus: "live_edit_terminated",
+        this.appState.recordFailedStart(input, {
+            ...(input.decision ? { decision: input.decision } : {}),
+            generationStatus: input.generationStatus ?? "live_edit_terminated",
             reply: input.reason,
+            ...(input.recoveryAction
+                ? { recoveryAction: input.recoveryAction }
+                : {}),
             ...(input.retryAction ? { retryAction: input.retryAction } : {}),
+            ...(input.retryable === false ? { retryable: false } : {}),
             // Nothing ran, so nothing is viewable. Reporting "ready" here is how a
             // caller comes to show the untouched starter template as the app.
             viewStatus: "unknown",
-        });
+        }, input.revision);
     }
     /**
      * Where this application's turn stands for this caller, read without draining
      * the activity an {@link WebSocketSessionPeer.awaitTurn} poll is owed.
      *
-     * 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.
+     * A running turn is current. Once it finishes, the newer of that turn and an
+     * unscoped failed start wins; explicit branch reads filter before comparing.
+     * Revisions preserve that ordering even when both events share a clock tick.
      */
     turnState(input) {
-        const turn = this.turns.get(input.applicationId);
-        if (turn && !turn.finished) {
+        const storedTurn = this.latestTurn(input.applicationId);
+        const turn = storedTurn &&
+            input.branch !== undefined &&
+            input.branch !== storedTurn.branch
+            ? undefined
+            : storedTurn;
+        if (this.appState.pendingStart(input)) {
             return { phase: "running" };
         }
-        const failed = this.failedStarts.get(input);
+        const failed = this.appState.failedStart(input, turn?.revision);
         if (failed) {
             return {
+                ...(failed.branch === undefined ? {} : { branch: failed.branch }),
                 generationStatus: failed.generationStatus,
                 phase: "finished",
+                ...(failed.recoveryAction
+                    ? { recoveryAction: failed.recoveryAction }
+                    : {}),
+                ...(failed.retryable === false ? { reply: failed.reply } : {}),
                 ...(failed.retryAction ? { retryAction: failed.retryAction } : {}),
+                ...(failed.retryable === false ? { retryable: false } : {}),
+            };
+        }
+        if (turn && !turn.finished) {
+            return {
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                phase: "running",
             };
         }
         if (!turn?.finished) {
             return undefined;
         }
         return {
+            ...(turn.branch === undefined ? {} : { branch: turn.branch }),
             ...(turn.finished.checkpointCommitId
                 ? { checkpointCommitId: turn.finished.checkpointCommitId }
                 : {}),
+            ...(turn.finished.checkpointFailure
+                ? { checkpointFailure: turn.finished.checkpointFailure }
+                : {}),
+            ...(turn.finished.checkpointWarning
+                ? { checkpointWarning: turn.finished.checkpointWarning }
+                : {}),
             generationStatus: turn.finished.generationStatus,
             phase: "finished",
             ...(turn.retryAction ? { retryAction: turn.retryAction } : {}),
+            ...(turn.finished.retryable === false
+                ? { retryable: false }
+                : {}),
         };
     }
     clearPendingPlan(applicationId) {
-        this.pendingPlans.delete(applicationId);
-        this.pendingDecisions.delete(applicationId);
+        this.appState.clearPending(applicationId);
     }
     clearPendingDecision(applicationId) {
-        this.pendingPlans.delete(applicationId);
-        this.pendingDecisions.delete(applicationId);
-    }
-    markBuildMode(applicationId) {
-        this.buildModeApplications.add(applicationId);
-    }
-    buildMode(applicationId) {
-        return this.buildModeApplications.has(applicationId);
+        this.appState.clearPending(applicationId);
     }
     isHeld(applicationId) {
         const entry = this.held.get(applicationId);
         return Boolean(entry && isSocketOpen(entry.ws));
     }
-    libraryBrowserContext(applicationId) {
+    heldContext(applicationId) {
+        const entry = this.held.get(applicationId);
+        return entry && isSocketOpen(entry.ws)
+            ? { ...(entry.branchName ? { branch: entry.branchName } : {}) }
+            : undefined;
+    }
+    libraryBrowserContext(applicationId, requestedBranch) {
         const held = this.held.get(applicationId);
-        if (!held) {
+        if (!held || requestedBranch !== held.branchName) {
             return undefined;
         }
         return this.buildHeldBrowserContext(held);
@@ -768,15 +874,18 @@ export class WebSocketSessionPeer {
         if (!input.userId.trim()) {
             throw new Error("Live-edit hold failed: userId is required to identify who the session is held for");
         }
+        const expectedTurn = this.turns.get(input.applicationId);
+        this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
         const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const deadline = Date.now() + timeoutMs;
         const held = await this.ensureHeld({
             applicationId: input.applicationId,
             branchName: input.branch,
+            getLiveEditStatus: input.getLiveEditStatus,
             keepalive: input.keepalive,
             liveEdit: liveEditOf(input),
             userId: input.userId,
-        }, deadline);
+        }, deadline, expectedTurn);
         if (input.apiKey) {
             held.apiKey = input.apiKey;
         }
@@ -788,14 +897,25 @@ export class WebSocketSessionPeer {
         await this.resolveHeldOrchestrator(held);
     }
     release(applicationId) {
-        this.buildModeApplications.delete(applicationId);
         const entry = this.held.get(applicationId);
         if (!entry) {
             return;
         }
+        const turn = this.turns.get(applicationId);
+        if (turn?.held === entry && !turn.finished) {
+            this.cancelTurn(turn, "This turn was cancelled because its live-edit session was released.");
+        }
         this.drop(entry);
     }
     closeAll() {
+        for (const turn of this.turns.values()) {
+            if (!turn.finished) {
+                this.cancelTurn(turn, "This turn was cancelled because the gateway shut down.");
+            }
+        }
+        for (const applicationId of [...this.observedTurns.keys()]) {
+            this.forgetObservedTurn(applicationId);
+        }
         for (const applicationId of [...this.held.keys()]) {
             this.release(applicationId);
         }
@@ -812,17 +932,19 @@ export class WebSocketSessionPeer {
         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 (;;) {
+            if (input.signal?.aborted) {
+                throw new Error("Superblocks turn wait aborted");
+            }
             const update = await this.awaitTurn({
                 applicationId: input.applicationId,
+                branch: input.branch,
                 signal: input.signal,
-                waitMs: Math.max(0, deadline - Date.now()),
+                waitMs: this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
             });
+            if (input.signal?.aborted) {
+                throw new Error("Superblocks turn wait aborted");
+            }
             if (update.status === "finished") {
                 const { activity: _activity, elapsedMs: _elapsedMs, status: _status, ...finished } = update;
                 return {
@@ -833,11 +955,26 @@ export class WebSocketSessionPeer {
                     status: "accepted",
                 };
             }
-            if (update.status === "unknown" || Date.now() >= deadline) {
+            if (update.status === "unknown") {
                 throw new Error("Prompt forward failed: the turn ended without reporting an outcome");
             }
         }
     }
+    claimPromptLane(applicationId) {
+        const ready = this.promptStarts.get(applicationId) ?? Promise.resolve();
+        let release;
+        const hold = new Promise((resolve) => {
+            release = resolve;
+        });
+        const current = ready.then(() => hold);
+        this.promptStarts.set(applicationId, current);
+        void current.then(() => {
+            if (this.promptStarts.get(applicationId) === current) {
+                this.promptStarts.delete(applicationId);
+            }
+        });
+        return { ready, release: () => void ready.then(release) };
+    }
     async startPrompt(input) {
         const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const settleMs = this.options.settleMs ?? DEFAULT_SETTLE_MS;
@@ -846,119 +983,188 @@ export class WebSocketSessionPeer {
         // 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`);
+            throw new PromptNotSentError(`Prompt forward failed: the live-edit credential is not a JWT (${segments} segment(s)); the session will reject it`);
         }
         if (!input.userId?.trim()) {
-            throw new Error("Prompt forward failed: userId is required to identify who the turn is running for");
+            throw new PromptNotSentError("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,
-            ...(input.attachments?.length ? { retryAction: "retry_import" } : {}),
-            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, {
-            initialSyncStatus: held.syncStatus,
-            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);
+        const revision = input.revision ?? this.appState.markTurnStarted();
+        const lane = this.claimPromptLane(input.applicationId);
+        let held;
         try {
-            return await this.sendPrompt({ held, input, listener, turn });
+            await beforePromptDeadline(lane.ready, deadline, input.signal);
+            try {
+                const requestedLiveEdit = liveEditOf(input);
+                const current = this.held.get(input.applicationId);
+                const liveEdit = current?.userId === userId &&
+                    current.movedFrom === requestedLiveEdit.url &&
+                    isSocketOpen(current.ws)
+                    ? current.liveEdit
+                    : requestedLiveEdit;
+                const heldInput = {
+                    applicationId: input.applicationId,
+                    branchName: input.branch,
+                    getLiveEditStatus: input.getLiveEditStatus,
+                    keepalive: input.keepalive,
+                    liveEdit,
+                    ...(input.resolveLiveEdit
+                        ? { resolveLiveEdit: input.resolveLiveEdit }
+                        : {}),
+                    userId,
+                };
+                const opening = this.connect(heldInput, deadline, false);
+                try {
+                    held = await beforePromptDeadline(opening, deadline, input.signal);
+                    if (liveEdit !== requestedLiveEdit) {
+                        held.movedFrom = requestedLiveEdit.url;
+                    }
+                    if (current?.userId === userId &&
+                        current.liveEdit.url === held.liveEdit.url) {
+                        held.syncStatus = current.syncStatus;
+                    }
+                }
+                catch (error) {
+                    void opening.then((stale) => {
+                        if (stale.provisional && !stale.dropping) {
+                            this.drop(stale);
+                        }
+                    }, () => undefined);
+                    throw error;
+                }
+                if (input.apiKey) {
+                    held.apiKey = input.apiKey;
+                }
+                if (input.organizationId) {
+                    held.organizationId = input.organizationId;
+                }
+                held.sessionToken = input.sessionToken;
+                await beforePromptDeadline(this.resolveHeldProfileKey(held), deadline, input.signal);
+                await beforePromptDeadline(this.resolveHeldOrchestrator(held), deadline, input.signal);
+            }
+            catch (error) {
+                throw error instanceof PromptNotSentError
+                    ? error
+                    : new PromptNotSentError(describeSocketError(error), error);
+            }
+            let integrations = [];
+            const editorContext = this.editorContextFor(held);
+            if (editorContext) {
+                try {
+                    integrations = await beforePromptDeadline(loadIntegrationsForPrompt(editorContext), deadline, input.signal);
+                }
+                catch (error) {
+                    if (error instanceof PromptNotSentError) {
+                        throw error;
+                    }
+                    console.warn("gateway failed to prefill prompt integrations", {
+                        applicationId: input.applicationId,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            await beforePromptDeadline(Promise.resolve(), deadline, input.signal);
+            if (input.pendingStartRequired &&
+                (input.organizationId === undefined ||
+                    input.idempotencyKey === undefined ||
+                    input.pendingStartToken === undefined ||
+                    !this.appState.pendingStart({
+                        applicationId: input.applicationId,
+                        ...(input.branch === undefined ? {} : { branch: input.branch }),
+                        organizationId: input.organizationId,
+                        userId,
+                    }, input.idempotencyKey, input.pendingStartToken))) {
+                throw new PromptNotSentError("A newer start attempt replaced this one before its prompt was sent");
+            }
+            const turn = {
+                abort: new AbortController(),
+                activity: [],
+                ...(held.branchName === undefined ? {} : { branch: held.branchName }),
+                collector: undefined,
+                delivered: 0,
+                heardAtLastReconnect: 0,
+                held,
+                ...(input.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: input.idempotencyKey }),
+                listener: () => undefined,
+                ...(input.pendingStartToken === undefined
+                    ? {}
+                    : { pendingStartToken: input.pendingStartToken }),
+                recentRuns: [],
+                reconnects: 0,
+                revision,
+                ...(input.attachments?.length ? { retryAction: "retry_build" } : {}),
+                startedAt: Date.now(),
+                turnId: randomUUID(),
+                waiters: new Set(),
+            };
+            const report = (message) => {
+                this.note(turn, message);
+                input.onProgress?.(message);
+            };
+            const collector = new TurnCollector(report, {
+                initialSyncStatus: held.syncStatus,
+                settleMs,
+            });
+            const hasDefaultStructure = this.editorStructureByScope.get(editorStructureScopeKey(input.applicationId, held.branchName));
+            if (hasDefaultStructure) {
+                collector.handle({
+                    hasDefaultStructure,
+                    kind: "editor_structure",
+                });
+            }
+            turn.collector = collector;
+            const bufferedEvents = [];
+            let accepted = false;
+            const listener = (event) => {
+                if (accepted) {
+                    collector.handle(event);
+                }
+                else {
+                    bufferedEvents.push(event);
+                }
+            };
+            turn.listener = listener;
+            held.pendingTurn = turn;
+            held.listeners.add(listener);
+            if (held.provisional) {
+                held.heartbeat.start();
+            }
+            return await this.sendPrompt({
+                acceptBufferedEvents: (generationId) => {
+                    collector.nameGeneration(generationId);
+                    accepted = true;
+                    for (const event of bufferedEvents) {
+                        collector.handle(event);
+                    }
+                    bufferedEvents.length = 0;
+                },
+                held,
+                input,
+                integrations,
+                provisional: Boolean(held.provisional),
+                turn,
+            });
         }
         catch (error) {
-            // 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();
+            if (held?.provisional && !held.dropping) {
+                this.drop(held);
+            }
             throw error;
         }
+        finally {
+            lane.release();
+        }
     }
     /**
      * Sends the prompt on a session already holding a subscribed turn, and hands
      * the turn to {@link runTurn} once the session confirms it took it on.
      */
     async sendPrompt(args) {
-        const { held, input, listener, turn } = args;
+        const { held, input, integrations, provisional, 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 {
@@ -966,7 +1172,7 @@ export class WebSocketSessionPeer {
             // 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, {
+            acknowledgment = await editorSocket(held, input.sessionToken).aiGenerateWithQueue({
                 ...(browserContext ? { browserContext } : {}),
                 jwt: input.sessionToken,
                 llmConfig: {
@@ -981,12 +1187,17 @@ export class WebSocketSessionPeer {
                     thinkingEnabled: false,
                     unifiedProviderEnabled: true,
                 },
-                mode: input.mode ?? "PLAN",
+                mode: (input.mode ?? "PLAN"),
                 prompt: input.prompt,
                 promptContext: {
                     attachments: input.attachments ?? [],
                     entities: [],
-                    integrations,
+                    // Sent without `metadata` on purpose: it is the expensive
+                    // per-integration detail, and Clark asks for it per integration
+                    // through `aiGetIntegration`. The shared request type does not
+                    // model that yet, so the narrowing is stated here rather than
+                    // widening every field of the payload.
+                    integrations: integrations,
                 },
                 ...(input.planContext
                     ? {
@@ -1006,24 +1217,48 @@ export class WebSocketSessionPeer {
                 ...(input.responseMetadata
                     ? { responseMetadata: input.responseMetadata }
                     : {}),
-                ...(input.importSource ? { importSource: input.importSource } : {}),
                 queueMode: "interrupt",
                 requestId: turn.turnId,
                 userPreferences: { suggestNextSteps: false },
-            }, {}, `Bearer ${input.sessionToken}`);
+            });
+            this.assertHeadlessTurnBound({ acknowledgment, turn });
         }
         catch (error) {
-            held.listeners.delete(listener);
+            this.discardUnstartedTurn(turn);
             const rejection = error;
             if (isAuthRejection(rejection)) {
-                turn.unsubscribe();
-                this.armIdle(held);
-                this.armKeepalive(held);
+                if (provisional) {
+                    this.drop(held);
+                }
+                else {
+                    this.armIdle(held);
+                    this.armKeepalive(held);
+                }
                 return {
                     message: "Interactive auth required for datasource access",
                     status: "auth_required",
                 };
             }
+            if (isRemoteRejection(rejection)) {
+                if (provisional) {
+                    this.drop(held);
+                }
+                else {
+                    this.armIdle(held);
+                    this.armKeepalive(held);
+                }
+                throw new PromptNotSentError(`Prompt forward failed: ${rejection.message ?? "unknown socket error"}`, error);
+            }
+            else {
+                const priorHeld = this.held.get(input.applicationId);
+                this.supersedeTurn(input.applicationId);
+                if (priorHeld) {
+                    this.drop(priorHeld);
+                }
+                if (held !== priorHeld) {
+                    this.drop(held);
+                }
+            }
             if (isTimeout(rejection)) {
                 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.`);
             }
@@ -1031,21 +1266,37 @@ export class WebSocketSessionPeer {
                 ? error
                 : new Error(`Prompt forward failed: ${rejection.message ?? "unknown socket error"}`);
         }
-        this.assertHeadlessTurnBound({
-            acknowledgment,
-            held,
-            listener,
-            turn,
-        });
+        turn.revision = this.appState.markTurnStarted();
+        args.acceptBufferedEvents(acknowledgment?.generationId);
         input.onProgress?.("Superblocks accepted the prompt");
         // Only now, with the prompt accepted and a live turn about to go in the
-        // map, is a recorded dead start 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);
+        // map, is a recorded dead start for this branch out of date. Clearing it
+        // when the slot was claimed instead dropped it before Superblocks had taken
+        // anything, so a retry that came back needing interactive auth - a return,
+        // not a throw, so nothing re-recorded it - left the app with no turn at all
+        // and `get_app` went back to previewing the starter template.
+        this.appState.clearFailedStarts(input.applicationId, turn.branch, turn.revision);
+        this.appState.clearPendingStartsThrough(input.applicationId, turn.revision);
+        // The pending decision goes for the same reason and at the same moment.
+        // Clearing it when the slot was claimed spent the plan on a prompt
+        // Superblocks had not taken: an approve that came back needing interactive
+        // auth left neither a pending plan nor the BUILD latch - which is only set
+        // once a start is accepted - so the retry proposed a plan again instead of
+        // building the one the user had already approved.
+        this.clearPendingDecision(input.applicationId);
+        this.forgetObservedTurn(input.applicationId);
+        const priorHeld = this.held.get(input.applicationId);
+        this.supersedeTurn(input.applicationId);
         this.turns.set(input.applicationId, turn);
+        delete held.pendingTurn;
+        if (provisional) {
+            delete held.provisional;
+            this.setHeld(held);
+            held.heartbeat.start();
+            if (priorHeld && priorHeld !== held) {
+                this.drop(priorHeld);
+            }
+        }
         // Deliberately not awaited: the turn outlives the call that started it so a
         // client with no progress channel can follow it through awaitTurn.
         void this.runTurn({
@@ -1063,19 +1314,265 @@ export class WebSocketSessionPeer {
             status: "accepted",
         };
     }
+    latestTurn(applicationId) {
+        return (this.observedTurns.get(applicationId) ?? this.turns.get(applicationId));
+    }
+    observeEditorEvent(held, event) {
+        if (held.dropping || this.held.get(held.applicationId) !== held) {
+            return;
+        }
+        let observed = this.observedTurns.get(held.applicationId);
+        const message = event.kind === "message" ? event.message : undefined;
+        const userContent = message?.role === "user" &&
+            typeof message.content === "string" &&
+            message.content.trim()
+            ? message.content.trim()
+            : undefined;
+        const userMessageId = userContent && typeof message?.id === "string" ? message.id : undefined;
+        if (userMessageId && observed?.userMessageIds.has(userMessageId)) {
+            return;
+        }
+        const activeGeneration = event.kind === "generation_state" &&
+            (event.state === "debugging" ||
+                event.state === "generating" ||
+                event.state === "summarizing");
+        if (userContent || activeGeneration) {
+            this.clearPendingDecision(held.applicationId);
+        }
+        const owned = this.turns.get(held.applicationId);
+        if (owned) {
+            if (!owned.finished && !userContent && !activeGeneration) {
+                return;
+            }
+            this.supersedeTurn(held.applicationId);
+        }
+        const distinctGeneration = activeGeneration &&
+            event.kind === "generation_state" &&
+            Boolean(event.generationId &&
+                observed?.generationId &&
+                event.generationId !== observed.generationId);
+        if (observed &&
+            (observed.held !== held ||
+                distinctGeneration ||
+                (userContent && observed.finished))) {
+            this.forgetObservedTurn(held.applicationId);
+            observed = undefined;
+            this.clearPendingDecision(held.applicationId);
+        }
+        if (observed?.finished) {
+            if (!activeGeneration) {
+                return;
+            }
+            if (event.kind === "generation_state" &&
+                event.generationId &&
+                event.generationId === observed.generationId &&
+                observed.finished.generationStatus !== "needs_decision") {
+                return;
+            }
+            observed = undefined;
+            this.clearPendingDecision(held.applicationId);
+        }
+        if (!observed) {
+            held.beatLoss = undefined;
+            this.clearIdleTimer(held);
+            const activity = [];
+            const next = {
+                abort: new AbortController(),
+                activity,
+                ...(held.branchName === undefined ? {} : { branch: held.branchName }),
+                collector: new TurnCollector((message) => this.note(next, message), {
+                    ...(event.kind === "generation_state" && event.generationId
+                        ? { generationId: event.generationId }
+                        : {}),
+                    settleMs: this.options.settleMs ?? DEFAULT_SETTLE_MS,
+                }),
+                delivered: 0,
+                ...(event.kind === "generation_state" && event.generationId
+                    ? { generationId: event.generationId }
+                    : {}),
+                held,
+                recentRuns: [],
+                revision: this.appState.markTurnStarted(),
+                startedAt: Date.now(),
+                userMessageIds: new Set(),
+                waiters: new Set(),
+            };
+            observed = next;
+            this.observedTurns.set(held.applicationId, observed);
+            void this.finishObservedTurn(held.applicationId, observed);
+        }
+        if (userMessageId) {
+            observed.userMessageIds.add(userMessageId);
+        }
+        if (event.kind === "generation_state" &&
+            event.generationId &&
+            !observed.generationId) {
+            observed.generationId = event.generationId;
+            observed.collector.nameGeneration(event.generationId);
+        }
+        if (userContent) {
+            this.note(observed, `User in editor: ${userContent}`);
+        }
+        observed.collector.handle(event);
+    }
+    forgetObservedTurn(applicationId) {
+        const observed = this.observedTurns.get(applicationId);
+        if (!observed) {
+            return;
+        }
+        this.observedTurns.delete(applicationId);
+        this.settleObservedTurn(observed, "cancelled");
+    }
+    async finishObservedTurn(applicationId, turn) {
+        let generationStatus;
+        try {
+            generationStatus = await turn.collector.waitUntilTerminal({
+                signal: turn.abort.signal,
+            });
+        }
+        catch {
+            return;
+        }
+        if (this.observedTurns.get(applicationId) !== turn || turn.finished) {
+            return;
+        }
+        const decision = turn.collector.decision();
+        if (decision &&
+            (generationStatus === "needs_decision" ||
+                decision.kind === "missing_integrations")) {
+            const reply = turn.collector.reply();
+            this.appState.setPendingDecision(applicationId, {
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                decision,
+                reply,
+            });
+            if (decision.kind === "plan") {
+                this.appState.setPendingPlan(applicationId, {
+                    ...(turn.branch === undefined ? {} : { branch: turn.branch }),
+                    ...(decision.messageId ? { messageId: decision.messageId } : {}),
+                    plan: decision.plan,
+                    ...(decision.title ? { title: decision.title } : {}),
+                });
+            }
+            else {
+                this.appState.clearPendingPlan(applicationId);
+            }
+        }
+        turn.finished = {
+            reply: turn.collector.reply(),
+            generationStatus,
+            viewStatus: turn.collector.viewableStatus(),
+            ...decisionFields(decision),
+        };
+        turn.collector.dispose();
+        this.wake(turn);
+        this.armObservedTurnRelease(applicationId, turn);
+    }
+    settleObservedTurn(turn, generationStatus, reply = turn.collector.reply()) {
+        if (turn.finished) {
+            return;
+        }
+        tagRetryableLiveEditDeath(turn, { generationStatus });
+        turn.finished = {
+            reply,
+            generationStatus,
+            viewStatus: turn.collector.viewableStatus(),
+            ...decisionFields(turn.collector.decision()),
+        };
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    armObservedTurnRelease(applicationId, turn) {
+        if (this.observedTurns.get(applicationId) !== turn ||
+            this.held.get(applicationId) !== turn.held ||
+            !turn.finished) {
+            return;
+        }
+        if (turn.finished.generationStatus === "needs_decision") {
+            this.armIdle(turn.held);
+        }
+        else {
+            this.armObservedPostTurnRelease(turn);
+        }
+        this.armKeepalive(turn.held);
+    }
+    armObservedPostTurnRelease(turn) {
+        const held = turn.held;
+        this.clearTimers(held);
+        const delayMs = this.options.releaseAfterTurnMs ?? DEFAULT_RELEASE_AFTER_TURN_MS;
+        held.idleTimer = setTimeout(() => {
+            if (this.observedTurns.get(held.applicationId) === turn &&
+                this.held.get(held.applicationId) === held) {
+                this.drop(held, { preserveFinishedObserved: true });
+            }
+        }, delayMs);
+        held.idleTimer.unref?.();
+    }
     async awaitTurn(input) {
-        const 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({
+        const pollStartedAtMs = Date.now();
+        // The deadline is the end of the poll. Answers with activity or nothing.
+        const deadlineAtMs = pollStartedAtMs + Math.max(0, input.waitMs);
+        // The floor is the minimum time the poll will wait to collect activity for before it answers.
+        // If the turn is finished (ex: needs a user decision), it will answer immediately.
+        const floorAtMs = pollStartedAtMs +
+            Math.min(Math.max(0, input.floorMs ?? 0), Math.max(0, input.waitMs));
+        const storedTurn = this.latestTurn(input.applicationId);
+        // Filter out turns that are not for the requested branch.
+        let turn = storedTurn &&
+            input.branch !== undefined &&
+            input.branch !== storedTurn.branch
+            ? undefined
+            : storedTurn;
+        // check if there is a pending turn for the requested branch.
+        const pendingScope = input.organizationId && input.userId
+            ? {
+                applicationId: input.applicationId,
+                ...(input.branch === undefined ? {} : { branch: input.branch }),
+                organizationId: input.organizationId,
+                userId: input.userId,
+            }
+            : undefined;
+        const pending = pendingScope
+            ? this.appState.pendingStart(pendingScope)
+            : undefined;
+        if (pendingScope && pending) {
+            const started = await this.waitForPendingTurn({
+                afterRevision: turn?.revision ?? 0,
+                applicationId: input.applicationId,
+                ...(pending.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: pending.idempotencyKey }),
+                pendingStartToken: pending.token,
+                scope: pendingScope,
+                signal: input.signal,
+                deadlineAtMs,
+            });
+            if (started) {
+                turn = started;
+            }
+            else if (this.appState.pendingStart(pendingScope)) {
+                return { activity: [], elapsedMs: 0, status: "running" };
+            }
+            else {
+                const currentTurn = this.latestTurn(input.applicationId);
+                turn =
+                    currentTurn &&
+                        input.branch !== undefined &&
+                        input.branch !== currentTurn.branch
+                        ? undefined
+                        : currentTurn;
+            }
+        }
+        // The same recency order as turnState. A poll that cannot say who it is for
+        // reads no failed-start record at all; those records belong to callers.
+        const failed = input.organizationId && input.userId
+            ? this.appState.failedStart({
                 applicationId: input.applicationId,
+                ...(input.branch === undefined ? {} : { branch: input.branch }),
                 organizationId: input.organizationId,
                 userId: input.userId,
-            })
+            }, turn?.revision)
             : undefined;
         // A turn that never started took no time, and there is no activity to
         // relay. Reporting it as finished is what stops the caller polling a session
@@ -1084,39 +1581,74 @@ export class WebSocketSessionPeer {
             return { activity: [], elapsedMs: 0, status: "finished", ...failed };
         }
         if (!turn) {
+            if (pendingScope && this.appState.pendingStart(pendingScope)) {
+                return { activity: [], elapsedMs: 0, status: "running" };
+            }
             return { activity: [], elapsedMs: 0, status: "unknown" };
         }
-        if (turn.delivered >= turn.activity.length && !turn.finished) {
+        const remainingWaitMs = Math.max(0, deadlineAtMs - Date.now());
+        if (
+        // If the turn is finished answer immediately.
+        !turn.finished &&
+            !input.signal?.aborted &&
+            (remainingWaitMs > 0 || input.waitMs === 0) &&
+            // Even if there is activity, we will wait until the floor is closed to answer.
+            (turn.delivered >= turn.activity.length || Date.now() < floorAtMs)) {
             await new Promise((resolve) => {
+                // Ends the wait and hands the caller whatever the turn has by now.
                 const settle = () => {
-                    clearTimeout(timer);
-                    turn.waiters.delete(settle);
+                    clearTimeout(deadlineTimer);
+                    clearTimeout(floorTimer);
+                    turn.waiters.delete(onWake);
                     input.signal?.removeEventListener("abort", settle);
                     resolve();
                 };
-                const timer = setTimeout(settle, Math.max(0, input.waitMs));
-                turn.waiters.add(settle);
+                // Called on every wake (any activity)
+                const onWake = () => {
+                    // Settle if the turn is finished or the floor is reached.
+                    if (turn.finished || Date.now() >= floorAtMs) {
+                        settle();
+                    }
+                };
+                // Settle if there is activity.
+                // Called when the floor timer expires.
+                const onFloor = () => {
+                    if (turn.delivered < turn.activity.length) {
+                        settle();
+                    }
+                };
+                const deadlineTimer = setTimeout(settle, remainingWaitMs);
+                const floorTimer = setTimeout(onFloor, Math.max(0, floorAtMs - Date.now()));
+                turn.waiters.add(onWake);
                 input.signal?.addEventListener("abort", settle, { once: true });
+                if (input.signal?.aborted) {
+                    settle();
+                }
             });
         }
-        const activity = this.drain(turn);
+        // Now drain the turn and return the activity.
+        const activity = input.signal?.aborted ? [] : this.drain(turn);
         const elapsedMs = Date.now() - turn.startedAt;
         const recentRuns = turn.recentRuns.length > 0 ? [...turn.recentRuns] : undefined;
         if (turn.finished) {
             return {
                 activity,
+                ...(turn.branch === undefined ? {} : { branch: turn.branch }),
                 elapsedMs,
                 status: "finished",
                 ...turn.finished,
+                viewStatus: this.currentViewStatus(input.applicationId, turn.branch, turn.finished.viewStatus),
                 ...(turn.retryAction ? { retryAction: turn.retryAction } : {}),
                 ...(recentRuns ? { recentRuns } : {}),
             };
         }
         return {
             activity,
+            ...(turn.branch === undefined ? {} : { branch: turn.branch }),
             elapsedMs,
             status: "running",
             ...(recentRuns ? { recentRuns } : {}),
+            viewStatus: this.currentViewStatus(input.applicationId, turn.branch, turn.collector.viewableStatus()),
         };
     }
     /**
@@ -1128,7 +1660,6 @@ export class WebSocketSessionPeer {
     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);
@@ -1137,7 +1668,7 @@ export class WebSocketSessionPeer {
         // 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;
+        let checkpointOutcome;
         try {
             if (turn.finished) {
                 return;
@@ -1178,12 +1709,11 @@ export class WebSocketSessionPeer {
             }
             const generationStatus = await collector.waitUntilTerminal({
                 signal: turn.abort.signal,
-                timeoutMs: turnTimeoutMs,
             });
             if (turn.finished) {
                 return;
             }
-            console.info("gateway clark turn states", {
+            gatewayDebug("gateway clark turn states", {
                 applicationId: input.applicationId,
                 draftPending: collector.needsDraftAccept(),
                 generationStatus,
@@ -1199,26 +1729,41 @@ export class WebSocketSessionPeer {
             // 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);
+                const lane = this.claimPromptLane(input.applicationId);
+                await lane.ready;
+                try {
+                    if (turn.finished || this.turns.get(input.applicationId) !== turn) {
+                        return;
+                    }
+                    // TODO(ENG-5922): `turn.held` is a dead session when the turn was kept
+                    // alive on the relay, so this accept cannot land and the caller gets a
+                    // finished turn with no commit.
+                    checkpointOutcome = await this.checkpoint({
+                        collector,
+                        held: turn.held,
+                        onProgress: report,
+                        readyWaitMs,
+                        sessionToken: input.sessionToken,
+                        turnId: turn.turnId,
+                    });
+                }
+                finally {
+                    lane.release();
+                }
             }
-            if (turn.finished) {
+            if (turn.finished || this.turns.get(input.applicationId) !== turn) {
                 return;
             }
+            if (generationStatus === "completed") {
+                this.clearPendingDecision(input.applicationId);
+            }
             const decision = collector.decision();
-            if (generationStatus === "needs_decision" && decision) {
+            if (decision &&
+                (generationStatus === "needs_decision" ||
+                    decision.kind === "missing_integrations")) {
                 const reply = collector.reply();
-                this.pendingDecisions.set(input.applicationId, {
+                this.appState.setPendingDecision(input.applicationId, {
+                    ...(turn.branch === undefined ? {} : { branch: turn.branch }),
                     decision,
                     ...(turn.recentRuns.length > 0
                         ? { recentRuns: [...turn.recentRuns] }
@@ -1226,20 +1771,29 @@ export class WebSocketSessionPeer {
                     reply,
                 });
                 if (decision.kind === "plan") {
-                    this.pendingPlans.set(input.applicationId, {
+                    this.appState.setPendingPlan(input.applicationId, {
+                        ...(turn.branch === undefined ? {} : { branch: turn.branch }),
                         ...(decision.messageId ? { messageId: decision.messageId } : {}),
                         plan: decision.plan,
                         ...(decision.title ? { title: decision.title } : {}),
                     });
                 }
                 else {
-                    this.pendingPlans.delete(input.applicationId);
+                    this.appState.clearPendingPlan(input.applicationId);
                 }
             }
             // Disconnect / supersede already wrote the authoritative outcome; never
-            // overwrite that with a later collector timeout or terminal status.
+            // overwrite that with a later collector terminal status.
             turn.finished ??= {
-                ...(checkpointCommitId ? { checkpointCommitId } : {}),
+                ...(checkpointOutcome?.status === "saved" && checkpointOutcome.commitId
+                    ? { checkpointCommitId: checkpointOutcome.commitId }
+                    : {}),
+                ...(checkpointOutcome?.status === "failed"
+                    ? { checkpointFailure: checkpointOutcome.failure }
+                    : {}),
+                ...(checkpointOutcome?.status === "saved" && checkpointOutcome.warning
+                    ? { checkpointWarning: checkpointOutcome.warning }
+                    : {}),
                 reply: collector.reply(),
                 generationStatus,
                 ...(turn.recentRuns.length > 0
@@ -1268,14 +1822,21 @@ export class WebSocketSessionPeer {
         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) {
+            // Nor may a turn that outlived its socket. `recoverTurn` keeps a turn
+            // running on the SABS relay after the close took its session out of the
+            // held map, and `turn.held` still points at that dead object. Arming a
+            // keepalive on it leaves an interval nothing can ever clear - the release
+            // timer no-ops precisely because the session is not current - so it goes
+            // on calling connectLiveEdit for the life of the process.
+            const sessionStillHeld = this.held.get(input.applicationId) === turn.held;
+            if (!sessionStillHeld) {
+                this.clearTimers(turn.held);
+            }
+            else if (stillMapped) {
                 try {
                     await turn.held.client.requestWithTracing(RELEASE_TURN_LOCK_METHOD, this.turnCorrelator(turn.turnId), {}, `Bearer ${input.sessionToken}`);
                 }
@@ -1300,20 +1861,6 @@ export class WebSocketSessionPeer {
     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.
@@ -1321,8 +1868,8 @@ export class WebSocketSessionPeer {
      * 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
+     * instead. The turn would stay 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.
      */
@@ -1330,9 +1877,7 @@ export class WebSocketSessionPeer {
         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.`);
+        throw new Error(`Prompt forward failed: the live-edit session acknowledged the prompt but did not bind it to this ${GATEWAY_PROTOCOL} peer, so nothing about the turn would report back. The sandbox is running a dev server from before the ${GATEWAY_PROTOCOL} role. Keep the MCP connection running and retry this app action shortly.`);
     }
     /**
      * The field the session reads to decide which turn a call belongs to. Sent on
@@ -1446,8 +1991,10 @@ export class WebSocketSessionPeer {
             };
         }
         this.carryOver(fresh, previous);
+        fresh.pendingTurn = turn;
         fresh.listeners.add(turn.listener);
         previous.listeners.delete(turn.listener);
+        fresh.heartbeat.start();
         const claim = fresh.sessionToken === undefined
             ? "refused"
             : await this.proveIdentity({
@@ -1456,18 +2003,23 @@ export class WebSocketSessionPeer {
                 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
+        // a relayed terminal event, the turn being cancelled, or a newer prompt
         // taking the app. runTurn arms the post-turn timers once, against the
         // session the turn held when it ended, so a replacement committed after
         // that is a socket nothing will ever close. Nothing has been committed at
         // this point but the listener, so there is nothing to undo beyond letting
         // the replacement go.
         if (turn.finished || turn.held !== previous) {
+            delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
-            this.drop(fresh);
+            if (fresh.listeners.size === 0 &&
+                this.turns.get(fresh.applicationId)?.held !== fresh) {
+                this.drop(fresh);
+            }
             return { kind: "stale" };
         }
         if (claim === "unreachable") {
+            delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
             this.drop(fresh);
             return {
@@ -1476,6 +2028,7 @@ export class WebSocketSessionPeer {
             };
         }
         if (claim === "refused") {
+            delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
             // Go back to the socket the turn was on, but only while it is still
             // there: a live edit that would not hand the turn over is still pushing
@@ -1484,22 +2037,17 @@ export class WebSocketSessionPeer {
             // 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.setHeld(previous);
             }
             this.drop(fresh);
             return { kind: "refused" };
         }
+        delete fresh.pendingTurn;
+        delete fresh.provisional;
         turn.held = fresh;
+        this.setHeld(fresh);
+        fresh.heartbeat.start();
         this.drop(previous);
-        // 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" };
     }
     /**
@@ -1537,7 +2085,10 @@ export class WebSocketSessionPeer {
      */
     async proveIdentity(input) {
         try {
-            await input.held.client.requestWithTracing(RELOAD_CHAT_METHOD, { force: false, ...this.turnCorrelator(input.turnId) }, {}, `Bearer ${input.sessionToken}`);
+            await editorSocket(input.held, input.sessionToken).aiChatGetMessages({
+                force: false,
+                ...this.turnCorrelator(input.turnId),
+            });
             return "claimed";
         }
         catch (error) {
@@ -1553,9 +2104,10 @@ export class WebSocketSessionPeer {
         }
     }
     async reconnect(previous, deadline) {
-        const connect = this.connect({
+        return await this.connect({
             applicationId: previous.applicationId,
             branchName: previous.branchName,
+            getLiveEditStatus: previous.getLiveEditStatus,
             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.
@@ -1568,16 +2120,30 @@ export class WebSocketSessionPeer {
                 ? { 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;
+        }, deadline, false);
+    }
+    setHeld(held) {
+        this.held.set(held.applicationId, held);
+        this.publishEditorStructure(held);
+    }
+    recordEditorStructure(held, hasDefaultStructure) {
+        held.editorHasDefaultStructure = hasDefaultStructure;
+        this.publishEditorStructure(held);
+    }
+    publishEditorStructure(held) {
+        if (held.dropping ||
+            this.held.get(held.applicationId) !== held ||
+            !held.editorHasDefaultStructure) {
+            return;
         }
-        finally {
-            this.connecting.delete(previous.applicationId);
+        this.editorStructureByScope.set(editorStructureScopeKey(held.applicationId, held.branchName), held.editorHasDefaultStructure);
+    }
+    currentViewStatus(applicationId, branch, fallback) {
+        const hasDefaultStructure = this.editorStructureByScope.get(editorStructureScopeKey(applicationId, branch));
+        if (!hasDefaultStructure) {
+            return fallback;
         }
+        return hasDefaultStructure === "no" ? "ready" : "unknown";
     }
     /** Lines this caller has not been handed yet. */
     drain(turn) {
@@ -1597,7 +2163,7 @@ export class WebSocketSessionPeer {
     }
     /**
      * 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
+     * waits so runTurn cannot overwrite it with a later terminal status. The
      * first outcome written wins: it is the one callers have already been shown.
      */
     settleTurn(turn, finished) {
@@ -1614,30 +2180,88 @@ export class WebSocketSessionPeer {
         const inSync = await input.collector.waitUntilInSync({
             timeoutMs: input.readyWaitMs,
         });
-        console.info("gateway clark checkpoint sync wait", {
+        gatewayDebug("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?.("Superblocks' files are still saving; the app will finish in the editor");
+            recordCheckpointOutcome("sync_timeout");
+            return {
+                failure: {
+                    category: "timeout",
+                    message: "Superblocks' files did not finish saving before the checkpoint deadline",
+                },
+                status: "failed",
+            };
         }
         input.onProgress?.("Saving a checkpoint");
         try {
-            const result = await input.held.client.requestWithTracing(ACCEPT_DRAFT_METHOD, {
-                screenshotDataUrl: null,
+            const result = await editorSocket(input.held, input.sessionToken).aiAcceptDraft({
                 silently: true,
                 ...this.turnCorrelator(input.turnId),
-            }, {}, `Bearer ${input.sessionToken}`);
+            });
             input.collector.markCheckpointed();
             const commitId = result?.commitId?.trim() ? result.commitId : undefined;
+            const warning = commitId
+                ? normalizeCheckpointWarning(result?.warning)
+                : undefined;
+            const captureCheckpointScreenshot = this.options.captureCheckpointScreenshot;
+            if (commitId && captureCheckpointScreenshot) {
+                const screenshotTask = (async () => {
+                    const budgetMs = this.options.checkpointScreenshotTimeoutMs ??
+                        DEFAULT_CHECKPOINT_SCREENSHOT_TIMEOUT_MS;
+                    let timer;
+                    try {
+                        await Promise.race([
+                            (async () => {
+                                const screenshotDataUrl = await captureCheckpointScreenshot({
+                                    applicationId: input.held.applicationId,
+                                    commitId,
+                                    sessionToken: input.sessionToken,
+                                });
+                                if (screenshotDataUrl) {
+                                    await editorSocket(input.held, input.sessionToken).aiUploadCheckpointScreenshot({
+                                        commitId,
+                                        screenshotDataUrl,
+                                        ...this.turnCorrelator(input.turnId),
+                                    });
+                                }
+                            })(),
+                            new Promise((_, reject) => {
+                                timer = setTimeout(() => reject(new Error("checkpoint screenshot timed out")), budgetMs);
+                                timer.unref?.();
+                            }),
+                        ]);
+                    }
+                    catch (error) {
+                        console.warn("gateway checkpoint screenshot failed", {
+                            applicationId: input.held.applicationId,
+                            commitId,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    finally {
+                        if (timer)
+                            clearTimeout(timer);
+                    }
+                })();
+                input.held.pendingCheckpointScreenshots.add(screenshotTask);
+                void screenshotTask.finally(() => {
+                    input.held.pendingCheckpointScreenshots.delete(screenshotTask);
+                    this.releasePostTurnIfReady(input.held);
+                });
+            }
             // 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}`);
+                    await editorSocket(input.held, input.sessionToken).aiChatGetMessages({
+                        force: true,
+                        ...this.turnCorrelator(input.turnId),
+                    });
                 }
                 catch (error) {
                     console.warn("gateway clark chat reload after checkpoint failed", {
@@ -1646,23 +2270,32 @@ export class WebSocketSessionPeer {
                     });
                 }
             }
-            console.info("gateway clark checkpoint saved", {
+            gatewayDebug("gateway clark checkpoint saved", {
                 applicationId: input.held.applicationId,
                 commitId: commitId ?? "none",
             });
-            input.onProgress?.(commitId ? "Checkpoint saved" : "App already up to date");
-            return commitId;
+            input.onProgress?.(warning?.message ??
+                (commitId ? "Checkpoint saved" : "App already up to date"));
+            recordCheckpointOutcome(warning ? "cleanup_warning" : commitId ? "saved" : "unchanged");
+            return {
+                ...(commitId ? { commitId } : {}),
+                status: "saved",
+                ...(warning ? { warning } : {}),
+            };
         }
         catch (error) {
+            const failure = checkpointFailure(error);
+            recordCheckpointOutcome(`${failure.category}_failure`);
             console.warn("gateway clark checkpoint failed", {
                 applicationId: input.held.applicationId,
-                message: error instanceof Error ? error.message : String(error),
+                message: `${failure.message}${failure.code === undefined ? "" : ` (code ${failure.code})`}`,
             });
             input.onProgress?.("Could not save a checkpoint for Superblocks' changes");
-            return undefined;
+            return { failure, status: "failed" };
         }
     }
-    async ensureHeld(input, deadline) {
+    async ensureHeld(input, deadline, expectedTurn) {
+        this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
         const existing = this.held.get(input.applicationId);
         // A connect that followed a moved session left this record pointing
         // somewhere the prompt's own resolve never saw. Overlapping forwards are
@@ -1681,6 +2314,10 @@ export class WebSocketSessionPeer {
             }
             else {
                 existing.branchName = input.branchName;
+                // A new prompt is a new turn, and the beat-lost clock measures one
+                // turn's silence. Carrying a running clock across would judge this
+                // prompt on how quiet the socket was before it was sent.
+                existing.beatLoss = undefined;
                 // The caller resolved the live edit for this prompt, so its id is at
                 // least as fresh as whatever an earlier prompt left here - but only
                 // when it named the host this socket is on. A prompt reusing through
@@ -1696,6 +2333,9 @@ export class WebSocketSessionPeer {
                 if (input.keepalive) {
                     existing.keepalive = input.keepalive;
                 }
+                if (input.getLiveEditStatus) {
+                    existing.getLiveEditStatus = input.getLiveEditStatus;
+                }
                 if (input.resolveLiveEdit) {
                     existing.resolveLiveEdit = input.resolveLiveEdit;
                 }
@@ -1707,12 +2347,12 @@ export class WebSocketSessionPeer {
             // 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);
+            return await this.ensureHeld(input, deadline, expectedTurn);
         }
         if (existing) {
             this.drop(existing);
         }
-        const connect = this.connect(input, deadline);
+        const connect = this.connect(input, deadline, true, expectedTurn);
         this.connecting.set(input.applicationId, connect);
         try {
             return await connect;
@@ -1721,7 +2361,7 @@ export class WebSocketSessionPeer {
             this.connecting.delete(input.applicationId);
         }
     }
-    async connect(input, deadline) {
+    async connect(input, deadline, publish = true, expectedTurn) {
         // Unique per connection. The dev server ignores the disconnect of a peerId
         // that is no longer the bound one, so a reattach that closes its
         // predecessor afterwards keeps the binding it just took; reusing one id
@@ -1806,8 +2446,18 @@ export class WebSocketSessionPeer {
                 if (event.kind === "sync_status" && event.status) {
                     held.syncStatus = event.status;
                 }
-                for (const listener of [...held.listeners]) {
-                    listener(event);
+                if (event.kind === "editor_structure") {
+                    this.recordEditorStructure(held, event.hasDefaultStructure);
+                }
+                if (isBrowserObserverEvent(event)) {
+                    this.observeEditorEvent(held, event);
+                    return;
+                }
+                if (held.listeners.size > 0) {
+                    for (const listener of [...held.listeners]) {
+                        listener(event);
+                    }
+                    return;
                 }
             };
         }, (method) => {
@@ -1819,8 +2469,10 @@ export class WebSocketSessionPeer {
                 if (!current) {
                     return;
                 }
-                const turn = this.turns.get(current.applicationId);
-                if (!turn) {
+                const turn = current.pendingTurn ?? this.turns.get(current.applicationId);
+                if (!turn ||
+                    turn.finished ||
+                    (turn.held !== current && current.pendingTurn !== turn)) {
                     return;
                 }
                 turn.recentRuns = appendRecentToolRun(turn.recentRuns, buildRecentToolRun(run));
@@ -1834,15 +2486,19 @@ export class WebSocketSessionPeer {
                 if (!current) {
                     return;
                 }
+                const turn = current.pendingTurn ?? this.turns.get(current.applicationId);
+                if (!turn ||
+                    turn.finished ||
+                    (turn.held !== current && current.pendingTurn !== turn)) {
+                    return;
+                }
                 try {
-                    await current.client.requestWithTracing(RESPOND_TOOL_PERMISSION_METHOD, {
+                    await editorSocket(current, current.sessionToken).aiRespondToToolPermission({
                         approved: payload.approved,
-                        ...this.turnCorrelator(this.turns.get(current.applicationId)?.turnId),
+                        ...this.turnCorrelator(turn.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", {
@@ -1864,11 +2520,24 @@ export class WebSocketSessionPeer {
                     this.held.delete(input.applicationId);
                 }
                 const held = heldRef.current;
+                if (held?.provisional === true || (!held && !publish)) {
+                    return;
+                }
                 // Its own closes - a reattach swapping sockets, a release - leave the
                 // turn either running elsewhere or already settled.
                 if (held?.dropping) {
                     return;
                 }
+                const observed = held
+                    ? this.observedTurns.get(held.applicationId)
+                    : undefined;
+                if (held && observed?.held === held && !observed.finished) {
+                    const applicationEnded = isApplicationClose(close);
+                    this.settleObservedTurn(observed, applicationEnded ? "live_edit_terminated" : "detached", applicationEnded
+                        ? LIVE_EDIT_TERMINATED_REPLY + describeClose(close)
+                        : observed.collector.reply());
+                    return;
+                }
                 // An application code is the live edit stating its own end, so there
                 // is nothing left to get back onto. Any other close is the
                 // transport's, and a turn is not over because the socket carrying it
@@ -1894,10 +2563,12 @@ export class WebSocketSessionPeer {
             client,
             heartbeat,
             idleTimer: undefined,
+            getLiveEditStatus: input.getLiveEditStatus,
             keepalive: input.keepalive,
             keepaliveTimer: undefined,
             listeners: new Set(),
             liveEdit,
+            pendingCheckpointScreenshots: new Set(),
             ...(input.resolveLiveEdit
                 ? { resolveLiveEdit: input.resolveLiveEdit }
                 : {}),
@@ -1905,12 +2576,22 @@ export class WebSocketSessionPeer {
                 ? {}
                 : { movedFrom: input.liveEdit.url }),
             peerId,
+            ...(!publish ? { provisional: true } : {}),
             socket,
             userId: input.userId,
             ws,
         };
         heldRef.current = held;
-        this.held.set(input.applicationId, held);
+        if (publish) {
+            try {
+                this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
+            }
+            catch (error) {
+                this.drop(held);
+                throw error;
+            }
+            this.setHeld(held);
+        }
         // Inbound frames are what separates a dead connection from a request
         // channel that stopped answering on a live one.
         ws.on("message", () => {
@@ -1919,9 +2600,19 @@ export class WebSocketSessionPeer {
         // 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();
+        if (publish) {
+            heartbeat.start();
+        }
         return held;
     }
+    assertReadOnlyHoldCurrent(applicationId, expectedTurn) {
+        const current = this.turns.get(applicationId);
+        const ownsPublishedSession = current && this.held.get(applicationId) === current.held;
+        if (current !== expectedTurn ||
+            (current && (!current.finished || ownsPublishedSession))) {
+            throw new Error("Live-edit hold skipped because the application has an active turn or completed a turn while the session opened");
+        }
+    }
     /**
      * The liveness beat for one held socket.
      *
@@ -1939,7 +2630,7 @@ export class WebSocketSessionPeer {
                     // 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}`);
+                await editorSocket(held, held.sessionToken).ping(this.turnCorrelator((held.pendingTurn ?? this.turns.get(held.applicationId))?.turnId));
             },
             describeError: describeSocketError,
             intervalMs: this.options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
@@ -1971,6 +2662,9 @@ export class WebSocketSessionPeer {
                 if (!held) {
                     return;
                 }
+                if (held.provisional) {
+                    return;
+                }
                 // The clock measures silence, so anything that is not silence ends it.
                 // A success and a refusal both prove the peer answered this beat - and
                 // a refusal must never cost a turn, since it is an application-level
@@ -1978,7 +2672,7 @@ export class WebSocketSessionPeer {
                 // 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;
+                    held.beatLoss = undefined;
                     return;
                 }
                 // Started here rather than from `onLost`, which fires only on the edge
@@ -1989,14 +2683,20 @@ export class WebSocketSessionPeer {
                 // 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();
+                    held.beatLoss ??= {
+                        at: Date.now(),
+                        baseline: this.livenessTurnSnapshot(held),
+                    };
                 }
-                if (held.beatLostAt === undefined) {
+                const beatLoss = held.beatLoss;
+                if (!beatLoss) {
                     return;
                 }
                 const graceMs = this.options.beatLostGraceMs ?? DEFAULT_BEAT_LOST_GRACE_MS;
-                if (Date.now() - held.beatLostAt >= graceMs) {
-                    this.abandonTurnOnBeatLost(held.applicationId, account);
+                const confirmationWindowStartedAt = beatLoss.failedHealthCheck?.at ?? beatLoss.at;
+                if (Date.now() - confirmationWindowStartedAt >= graceMs &&
+                    !beatLoss.healthCheck) {
+                    beatLoss.healthCheck = this.confirmBeatLostSession(held, account, beatLoss);
                 }
             },
             // The sandbox grants liveness on proof of authorization, so a beat sent
@@ -2012,10 +2712,100 @@ export class WebSocketSessionPeer {
             timeoutMs: this.options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS,
         });
     }
+    livenessTurnSnapshot(held) {
+        const turn = this.turns.get(held.applicationId);
+        const activeTurn = turn?.held === held &&
+            !turn.finished &&
+            !turn.collector.status() &&
+            !turn.collector.isSettling()
+            ? turn
+            : undefined;
+        const observed = this.observedTurns.get(held.applicationId);
+        const activeObserved = observed?.held === held &&
+            !observed.finished &&
+            !observed.collector.status() &&
+            !observed.collector.isSettling()
+            ? observed
+            : undefined;
+        return {
+            observed: activeObserved,
+            observedLastEventAt: activeObserved?.collector.lastEventAt(),
+            turn: activeTurn,
+            turnActivityLength: activeTurn?.activity.length,
+            turnLastEventAt: activeTurn?.collector.lastEventAt(),
+        };
+    }
+    sameLivenessTurnSnapshot(left, right) {
+        return (left.observed === right.observed &&
+            left.observedLastEventAt === right.observedLastEventAt &&
+            left.turn === right.turn &&
+            left.turnActivityLength === right.turnActivityLength &&
+            left.turnLastEventAt === right.turnLastEventAt);
+    }
+    async confirmBeatLostSession(held, heartbeat, beatLoss) {
+        const applicationId = held.applicationId;
+        const snapshot = this.livenessTurnSnapshot(held);
+        const activeObserved = snapshot.observed;
+        const activeTurn = snapshot.turn;
+        if (!activeTurn && !activeObserved) {
+            if (held.beatLoss === beatLoss) {
+                held.beatLoss = undefined;
+            }
+            return;
+        }
+        const priorSnapshot = beatLoss.failedHealthCheck?.snapshot ?? beatLoss.baseline;
+        const activitySincePriorCheck = !this.sameLivenessTurnSnapshot(priorSnapshot, snapshot);
+        if (activitySincePriorCheck) {
+            held.beatLoss = undefined;
+            return;
+        }
+        const healthy = await liveEditIsHealthy({
+            applicationId,
+            liveEditUrl: held.liveEdit.url,
+            sessionToken: held.sessionToken,
+        });
+        let liveEditStatus;
+        if (!healthy && held.liveEdit.id && held.getLiveEditStatus) {
+            try {
+                liveEditStatus = await held.getLiveEditStatus({
+                    liveEditId: held.liveEdit.id,
+                    signal: AbortSignal.timeout(DEFAULT_BEAT_HEALTH_TIMEOUT_MS),
+                });
+            }
+            catch {
+                // An unavailable control plane is not evidence that the sandbox died.
+            }
+        }
+        if (held.dropping ||
+            this.held.get(applicationId) !== held ||
+            held.beatLoss !== beatLoss) {
+            return;
+        }
+        if (healthy ||
+            !this.sameLivenessTurnSnapshot(snapshot, this.livenessTurnSnapshot(held))) {
+            held.beatLoss = undefined;
+            return;
+        }
+        if (liveEditStatus !== "terminated" &&
+            liveEditStatus !== "terminating" &&
+            beatLoss.failedHealthCheck === undefined) {
+            beatLoss.failedHealthCheck = {
+                at: Date.now(),
+                snapshot,
+            };
+            delete beatLoss.healthCheck;
+            return;
+        }
+        held.beatLoss = undefined;
+        this.abandonTurnOnBeatLost(held, heartbeat, activeTurn, activeObserved, liveEditStatus);
+    }
     armIdle(held) {
         if (held.idleTimer) {
             clearTimeout(held.idleTimer);
         }
+        // This session is now held for an answer, so a screenshot settling later
+        // must not release it on the finished turn's behalf.
+        held.postTurnReleaseTurn = undefined;
         const idleMs = this.options.idleMs ?? DEFAULT_IDLE_MS;
         held.idleTimer = setTimeout(() => {
             this.release(held.applicationId);
@@ -2026,8 +2816,8 @@ export class WebSocketSessionPeer {
      * 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.
+     * on the way out. A turn left waiting on that socket would otherwise never
+     * report an outcome to the caller.
      *
      * 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,
@@ -2101,17 +2891,20 @@ export class WebSocketSessionPeer {
     /**
      * Ends a turn whose socket has stopped answering.
      *
-     * Two gates, because they answer different questions. `SocketHeartbeat`
+     * Three gates answer different questions. `SocketHeartbeat`
      * declares the beat lost after consecutive genuine misses, having already
      * excused a run of unanswered beats and every silence that inbound traffic
      * explained - the right threshold for a diagnostic, and too eager for this: a
      * sandbox that misses two beats and answers the next was recovering, and its
      * turn has to survive that. So the loss also has to outlast
      * {@link DEFAULT_BEAT_LOST_GRACE_MS}, and any beat that succeeds clears it.
+     * Finally, the exact live edit must either be terminal in the control plane,
+     * or its direct HTTP health check must fail again after another grace
+     * window. One timeout, 5xx, or inconclusive control-plane result is still
+     * recoverable.
      *
      * 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.
+     * socket that never closed, with a turn waiting on it indefinitely.
      *
      * 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
@@ -2123,24 +2916,47 @@ export class WebSocketSessionPeer {
      * 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);
+    abandonTurnOnBeatLost(held, heartbeat, turn, observed, liveEditStatus) {
+        const applicationId = held.applicationId;
+        if (held.dropping || this.held.get(applicationId) !== held) {
+            return;
+        }
         // The same rule the disconnect and SABS paths use: settle only a turn that
         // has not settled itself. A finished turn's socket keeps beating through
         // the post-turn grace, so a sandbox reaped in that window must not
         // overwrite the outcome the caller already has.
-        if (!turn || turn.finished || turn.collector.status()) {
+        if (turn &&
+            this.turns.get(applicationId) === turn &&
+            turn.held === held &&
+            !turn.finished &&
+            !turn.collector.status()) {
+            console.warn("gateway clark turn abandoned", {
+                applicationId,
+                beatFailures: heartbeat.failures,
+                beatLapses: heartbeat.lapses,
+                beatsSent: heartbeat.sent,
+                lastBeatError: heartbeat.lastError,
+                liveEditStatus,
+                reason: "the live-edit socket stopped answering",
+            });
+            let confirmation = "The direct live-edit health check failed twice while no conclusive Superblocks control-plane status was available.";
+            if (liveEditStatus === "active" || liveEditStatus === "starting") {
+                confirmation = `The direct live-edit health check failed twice while the Superblocks control plane last reported the exact session ${liveEditStatus}.`;
+            }
+            else if (liveEditStatus === "terminated" ||
+                liveEditStatus === "terminating") {
+                confirmation = `The Superblocks control plane reported the exact live-edit session ${liveEditStatus}.`;
+            }
+            this.settleAsLiveEditTerminated(turn, `${describeHeartbeat(heartbeat, Date.now())} ${confirmation}`);
             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()));
+        if (observed &&
+            this.observedTurns.get(applicationId) === observed &&
+            observed.held === held &&
+            !observed.finished) {
+            this.settleObservedTurn(observed, "detached");
+            this.armObservedTurnRelease(applicationId, observed);
+        }
     }
     /**
      * Records a dead live edit as the turn's outcome and ends every wait on it.
@@ -2148,6 +2964,12 @@ export class WebSocketSessionPeer {
      * cause that reaches the caller.
      */
     settleAsLiveEditTerminated(turn, evidence) {
+        if (turn.finished) {
+            return;
+        }
+        tagRetryableLiveEditDeath(turn, {
+            generationStatus: "live_edit_terminated",
+        });
         this.settleTurn(turn, {
             reply: LIVE_EDIT_TERMINATED_REPLY + evidence,
             generationStatus: "live_edit_terminated",
@@ -2253,32 +3075,55 @@ export class WebSocketSessionPeer {
         if (!prior) {
             return;
         }
-        prior.finished ??= {
-            reply: "This turn was replaced by a newer prompt on the same app, so its work was cancelled.",
+        this.cancelTurn(prior);
+    }
+    cancelTurn(turn, reply = "This turn was replaced by a newer prompt on the same app, so its work was cancelled.") {
+        turn.finished ??= {
+            reply,
             generationStatus: "cancelled",
-            viewStatus: prior.collector.viewableStatus(),
+            viewStatus: turn.collector.viewableStatus(),
         };
-        const held = this.held.get(applicationId);
-        held?.listeners.delete(prior.listener);
-        prior.unsubscribe();
-        prior.collector.dispose();
-        prior.abort.abort();
-        this.wake(prior);
+        turn.held.listeners.delete(turn.listener);
+        this.held.get(turn.held.applicationId)?.listeners.delete(turn.listener);
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
+    }
+    discardUnstartedTurn(turn) {
+        if (turn.held.pendingTurn === turn) {
+            delete turn.held.pendingTurn;
+        }
+        turn.held.listeners.delete(turn.listener);
+        turn.collector.dispose();
+        turn.abort.abort();
+        this.wake(turn);
     }
     armPostTurnRelease(held, turn) {
         this.clearTimers(held);
         const delayMs = this.options.releaseAfterTurnMs ?? DEFAULT_RELEASE_AFTER_TURN_MS;
+        held.postTurnReleaseAt = Date.now() + delayMs;
+        held.postTurnReleaseTurn = turn;
         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);
-            }
+            held.postTurnReleaseAt = 0;
+            this.releasePostTurnIfReady(held);
         }, delayMs);
         held.idleTimer.unref?.();
     }
+    releasePostTurnIfReady(held) {
+        const turn = held.postTurnReleaseTurn;
+        if (!turn ||
+            Date.now() < (held.postTurnReleaseAt ?? 0) ||
+            held.pendingCheckpointScreenshots.size > 0) {
+            return;
+        }
+        const active = this.turns.get(held.applicationId);
+        if (active && active !== turn && !active.finished) {
+            return;
+        }
+        if (this.held.get(held.applicationId) === held) {
+            this.drop(held);
+        }
+    }
     armKeepalive(held) {
         if (held.keepaliveTimer) {
             clearInterval(held.keepaliveTimer);
@@ -2301,21 +3146,30 @@ export class WebSocketSessionPeer {
      * belongs to the socket and outlives these, which the post-turn grace period
      * resets.
      */
-    clearTimers(held) {
+    clearIdleTimer(held) {
+        held.postTurnReleaseTurn = undefined;
         if (held.idleTimer) {
             clearTimeout(held.idleTimer);
             held.idleTimer = undefined;
         }
+    }
+    clearTimers(held) {
+        this.clearIdleTimer(held);
         if (held.keepaliveTimer) {
             clearInterval(held.keepaliveTimer);
             held.keepaliveTimer = undefined;
         }
     }
-    drop(held) {
+    drop(held, options = {}) {
         console.error("gateway held session released", {
             applicationId: held.applicationId,
         });
         held.dropping = true;
+        const observed = this.observedTurns.get(held.applicationId);
+        if (observed?.held === held &&
+            !(options.preserveFinishedObserved && observed.finished)) {
+            this.forgetObservedTurn(held.applicationId);
+        }
         this.clearTimers(held);
         held.heartbeat.stop();
         // Only if it is still the current session: a reattach registers its
@@ -2465,7 +3319,9 @@ export class WebSocketSessionPeer {
         }
         if (this.options.orchestrator || this.options.orchestratorUrl) {
             held.orchestrator = this.options.orchestrator;
-            held.orchestratorUrl = this.options.orchestratorUrl;
+            held.orchestratorUrl = this.options.orchestratorUrl
+                ? canonicalizeOrchestratorBaseUrl(this.options.orchestratorUrl)
+                : this.options.orchestratorUrl;
             return;
         }
         if (!held.apiKey || !held.organizationId || !this.options.server) {