@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/socket-manager.js

@@ -1,65 +1,578 @@
-import EventEmitter from "node:events";
-import { createISocketClient, ISocket } from "@superblocksteam/shared";
+import { randomUUID } from "node:crypto";
+import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { WebSocketServer } from "ws";
+import { createISocketClient, DEFAULT_NON_GIT_BRANCH, MAX_SOCKET_PAYLOAD_BYTES, SocketErrorException, SUPERBLOCKS_LIVE_GIT_BRANCH, TracedEventEmitter, TracedSocket, } from "@superblocksteam/shared";
+import { uploadContextToBucketeer } from "./ai-service/context-upload.js";
+import { createSocketRecordingMiddleware } from "./ai-service/recording/recorders/socket-recorder.js";
+import { parseJwt } from "./ai-service/util/parse-jwt.js";
+import { PeerLiveness, } from "./ai-service/util/peer-liveness.js";
+import { clearGitAuthFailed, isGitAuthFailed, markGitAuthFailed, } from "./git-auth-state.js";
+import { GIT_LOG_FORMAT, parseGitLog } from "./git-log.js";
+import { GIT_OPERATION_BUSY_MESSAGE, } from "./git-operation-lock.js";
+import { assertIncomingLiveLayout } from "./git-service/app-layout-guard.js";
+import { GitConflictError } from "./git-service/index.js";
+import { doesRemoteLiveBranchExist, ensureLiveBranchCheckedOut, pushLiveBranchWithAutoRecreate, rollbackLastCommit, } from "./git-service/live-branch.js";
+import { ensureProviderWorkflowFiles } from "./git-service/provider-workflow-files.js";
+import { getSyncCountsAgainstDefaultBranch } from "./git-service/status-sync.js";
 import { getErrorMeta, getLogger } from "./util/logger.js";
-import { withMethodTracing } from "./util/tracing.js";
-export class SocketManager extends EventEmitter {
+import { OperationQueue } from "./util/operation-queue.js";
+const SB_WORKTREE_SNAPSHOTS_DIR = join(tmpdir(), "sb-worktree-snapshots");
+/**
+ * Pulls the JWT-derived `userId` out of an `Authorization: Bearer <jwt>`
+ * header value. Returns `undefined` for missing / malformed headers or
+ * JWTs without a `user_id` claim — callers treat undefined the same way
+ * the LLM-facing tools do (cannot access user-owned tasks, but legacy
+ * unowned tasks remain visible). Centralized so the auth middleware and
+ * the `aiCancelBackgroundTask` handler use exactly the same extraction
+ * — divergence would re-introduce the cross-user cancel bypass Matt
+ * and the security agent flagged on PR #19718.
+ */
+function extractCallerUserId(peerAuthorization) {
+    if (!peerAuthorization)
+        return undefined;
+    const jwt = peerAuthorization.replace("Bearer ", "");
+    if (!jwt)
+        return undefined;
+    return parseJwt(jwt).userId;
+}
+const EDITOR_PROTOCOL = "editor";
+const GATEWAY_PROTOCOL = "gateway";
+/**
+ * Subprotocols the dev server answers with. The library runtime offers none at
+ * all and connects on that basis; there is no `library` protocol to negotiate.
+ * A peer that does offer something must offer one of these — an unrecognized
+ * offer fails negotiation rather than being demoted to a library socket that
+ * would never carry the traffic the peer connected for.
+ */
+const NEGOTIABLE_PROTOCOLS = [
+    EDITOR_PROTOCOL,
+    GATEWAY_PROTOCOL,
+];
+function selectProtocol(offered) {
+    for (const protocol of offered) {
+        if (NEGOTIABLE_PROTOCOLS.includes(protocol)) {
+            return protocol;
+        }
+    }
+    return false;
+}
+/**
+ * Classifies a peer from the subprotocols it offered on the upgrade request.
+ * The header is a comma-separated list, so an offer of `gateway, editor` is
+ * resolved by the same precedence the handshake answers with.
+ */
+export function classifyConnectionKind(offeredProtocols) {
+    const offered = (offeredProtocols ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (offered.length === 0) {
+        return "library";
+    }
+    const selected = selectProtocol(offered);
+    if (selected === GATEWAY_PROTOCOL) {
+        return "gateway";
+    }
+    if (selected === EDITOR_PROTOCOL) {
+        return "editor";
+    }
+    return "unsupported";
+}
+/**
+ * Identifies the peer behind an upgrade request.
+ *
+ * A refusal that reports only the subprotocol says what went wrong and nothing
+ * about who did it, which is no help at all when one repeats on a timer: every
+ * client that can reach this socket has to be ruled out by hand. The user agent
+ * earns its place next to the ids because it separates a browser editor from a
+ * headless peer immediately, and those are the two the ids alone cannot tell
+ * apart.
+ */
+function describeUpgradePeer(url, req) {
+    const peerId = url.searchParams.get("peerId") ?? "unknown";
+    const applicationId = url.searchParams.get("applicationId") ?? "unknown";
+    const userAgent = req.headers["user-agent"] ?? "unknown";
+    return `peerId=${peerId}, applicationId=${applicationId}, userAgent=${userAgent}`;
+}
+/**
+ * The turn a gateway peer says its call belongs to.
+ *
+ * Carried in the RPC payload rather than on the connection: the correlator is
+ * minted with the prompt, and the calls that matter for ownership — the prompt
+ * itself and the reattach's first authenticated read — already carry a payload.
+ */
+function readHeadlessTurnId(params) {
+    if (!params || typeof params !== "object") {
+        return undefined;
+    }
+    const candidate = params.headlessTurnId;
+    return typeof candidate === "string" ? candidate : undefined;
+}
+let _socketManager;
+// Global flag for Clark log forwarding to browser console.
+// Defaults to enabled for internal dev (SUPERBLOCKS_CLI_ENV=local), can be toggled via ?clark_logs=true query param.
+let _clarkVerboseLogsEnabled = process.env.SUPERBLOCKS_CLI_ENV === "local";
+export function isClarkVerboseLogsEnabled() {
+    return _clarkVerboseLogsEnabled;
+}
+function setClarkVerboseLogsEnabled(enabled) {
+    _clarkVerboseLogsEnabled = enabled;
+}
+export function createSocketManager(tracer) {
+    _socketManager?.dispose();
+    _socketManager = new SocketManager(tracer);
+    return _socketManager;
+}
+export function disposeSocketManager() {
+    _socketManager?.dispose();
+    _socketManager = undefined;
+}
+class SocketManager extends TracedEventEmitter {
+    peerLiveness = new PeerLiveness();
+    socketLiveness = new WeakMap();
+    /**
+     * Survives `editorSockets.delete` so a just-closed socket can still tell
+     * {@link getSurvivingEditorClient} which peerId to prefer among leftovers.
+     */
+    editorPeerIdsBySocket = new WeakMap();
+    authenticatedEditorSockets = new WeakSet();
+    authenticatedGatewaySockets = new WeakSet();
+    editorStructureReport;
+    editorStructureReportByGateway = new WeakMap();
     peerIds = new Map();
-    editorSockets = new Set();
+    /**
+     * Editor peers whose presence is registered with the lock service, and the
+     * user each was registered for.
+     *
+     * Presence is per *peer*, not per socket: one tab reconnecting produces a new
+     * socket under the same peer id. Remembering "did I register?" on the socket
+     * therefore breaks the pair, because the socket that takes presence down need
+     * not be the one that put it up — a replacement that never makes an
+     * authorized call would close without removing anything, leaving the lock
+     * claimed for a peer that is gone.
+     */
+    editorPresenceUserIdByPeerId = new Map();
+    /** Editor peers that have already triggered post-auth git activation. */
+    gitActivatedPeerIds = new Set();
+    /** Attached editor sockets, each mapped to the peer that opened it. */
+    editorSockets = new Map();
+    /**
+     * Attached headless gateway sockets, each mapped to the peer that opened it.
+     * Kept apart from {@link editorSockets} so gateway peers are never handed the
+     * browser editor binding, never counted as editor presence, and never picked
+     * as a surviving editor.
+     */
+    gatewaySockets = new Map();
     librarySockets = new Set();
-    connectedUserPeerIdsMap = new Map();
-    constructor() {
-        super();
+    _disposer = () => { };
+    constructor(tracer) {
+        super(tracer);
     }
     socketServer;
-    startSocketServer({ server, fileSyncManager, syncService, lockService, aiService, path, tracer, }) {
+    startSocketServer({ server, fileSyncManager, syncService, lockService, aiService, gitService, gitBootstrapAuthFailed, gitBootstrapFailed, activateGitService, refreshGitCredentials, checkAuthorization, path, tracer, gitOperationLock, superblocksBaseUrl, maxPayloadBytes = MAX_SOCKET_PAYLOAD_BYTES, }) {
         if (this.socketServer) {
-            return;
+            throw new Error("Socket server already started");
         }
-        const wss = new WebSocketServer({ path, noServer: true });
+        const wss = new WebSocketServer({
+            path,
+            noServer: true,
+            maxPayload: maxPayloadBytes,
+            // Echo back the role the peer asked for so a gateway client can tell it
+            // was accepted as a gateway rather than silently demoted to a library
+            // peer. `ws` only consults this when the client offered a subprotocol.
+            handleProtocols: (protocols) => selectProtocol(protocols),
+        });
         this.socketServer = wss;
-        server.on("upgrade", (req, socket, head) => {
+        let activeGitService = gitService;
+        const headlessLockOwners = [];
+        const headlessLockHandbackQueue = new OperationQueue();
+        const headlessLockOperationQueue = new OperationQueue();
+        /**
+         * Drop every turn this peer owned, and hand the lock back if that was the
+         * last of them.
+         *
+         * Dropping the rows alone leaves the lock stranded. The lock service only
+         * hands back when *no* gateway is left, so with a replacement socket
+         * already attached that never fires — and once the owner row is gone, a
+         * later `editor.releaseTurnLock` finds nothing to release and does
+         * nothing. The AppBranchLock would then stay held for the rest of that
+         * socket's life, with no turn behind it.
+         *
+         * Owner decisions and handbacks use separate queues so generation waits
+         * serialize releases without keeping later headless prompts from starting.
+         */
+        const dropHeadlessLockOwnersNow = async (peerId) => {
+            const ownedTurns = await headlessLockOperationQueue.enqueue(async () => {
+                const owned = headlessLockOwners.filter((owner) => owner.peerId === peerId);
+                if (headlessLockOwners.some((owner) => !owner.handbackFailed && !owned.includes(owner))) {
+                    for (let index = headlessLockOwners.length - 1; index >= 0; index--) {
+                        const owner = headlessLockOwners[index];
+                        if (owner && owned.includes(owner)) {
+                            headlessLockOwners.splice(index, 1);
+                        }
+                    }
+                    return [];
+                }
+                return owned;
+            });
+            if (ownedTurns.length === 0) {
+                return;
+            }
+            try {
+                await lockService?.relinquishLockForTurn(() => headlessLockOwners.some((owner) => !owner.handbackFailed &&
+                    (!ownedTurns.includes(owner) || owner.peerId !== peerId)));
+            }
+            finally {
+                await headlessLockOperationQueue.enqueue(async () => {
+                    for (let index = headlessLockOwners.length - 1; index >= 0; index--) {
+                        const owner = headlessLockOwners[index];
+                        if (owner &&
+                            owner.peerId === peerId &&
+                            ownedTurns.includes(owner)) {
+                            headlessLockOwners.splice(index, 1);
+                        }
+                    }
+                });
+            }
+        };
+        const dropHeadlessLockOwners = (peerId) => headlessLockHandbackQueue.enqueue(() => dropHeadlessLockOwnersNow(peerId));
+        const dropHeadlessLockOwnersInBackground = (peerId, occasion) => {
+            void dropHeadlessLockOwners(peerId).catch((err) => {
+                getLogger().warn(`[socket-manager] failed to hand the turn lock back after ${occasion}: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+        lockService?.setOnGatewayLivenessLapsed?.((peerId) => {
+            dropHeadlessLockOwnersInBackground(peerId, "a gateway's liveness lapsed");
+            aiService?.endHeadlessTurn(peerId);
+        });
+        const releaseHeadlessLockNow = async (peerId, turnId) => {
+            const ownedTurn = await headlessLockOperationQueue.enqueue(async () => {
+                const ownerIndex = headlessLockOwners.findIndex((owner) => owner.peerId === peerId &&
+                    (turnId ? owner.turnId === turnId : owner.turnId === undefined));
+                if (ownerIndex === -1) {
+                    return undefined;
+                }
+                const owner = headlessLockOwners[ownerIndex];
+                if (!owner) {
+                    return undefined;
+                }
+                if (headlessLockOwners.some((candidate) => candidate !== owner && !candidate.handbackFailed)) {
+                    headlessLockOwners.splice(ownerIndex, 1);
+                    return true;
+                }
+                owner.handbackFailed = false;
+                return owner;
+            });
+            if (!ownedTurn) {
+                return false;
+            }
+            if (ownedTurn === true) {
+                return true;
+            }
+            try {
+                await lockService?.relinquishLockForTurn(() => headlessLockOwners.some((owner) => !owner.handbackFailed &&
+                    (owner !== ownedTurn || owner.peerId !== peerId)));
+            }
+            catch (error) {
+                await headlessLockOperationQueue.enqueue(async () => {
+                    if (headlessLockOwners.includes(ownedTurn)) {
+                        ownedTurn.handbackFailed = true;
+                    }
+                });
+                throw error;
+            }
+            return await headlessLockOperationQueue.enqueue(async () => {
+                const ownerIndex = headlessLockOwners.findIndex((owner) => owner === ownedTurn && owner.peerId === peerId);
+                if (ownerIndex === -1) {
+                    return false;
+                }
+                headlessLockOwners.splice(ownerIndex, 1);
+                return true;
+            });
+        };
+        const releaseHeadlessLock = (peerId, turnId) => headlessLockHandbackQueue.enqueue(() => releaseHeadlessLockNow(peerId, turnId));
+        // Provide sync context (branchName, lastCommitId) to the AI service
+        // for remote context restore fallback from Bucketeer on fresh pods.
+        if (aiService && syncService) {
+            aiService.setSyncContextProvider({
+                getBranchName: () => syncService.branchName,
+                getLastCommitId: () => syncService.lastCommitId,
+            });
+        }
+        aiService?.setAuthenticatedEditorPeersProvider?.(() => this.getAuthenticatedEditorPeers());
+        aiService?.setAuthenticatedGatewayPeersProvider?.(() => this.getAuthenticatedGatewayPeers());
+        // Sticky guard. Set to true by `gitDisconnect` and deliberately NOT
+        // cleared when it finishes: any callers of `getActiveGitService()` that
+        // started before disconnect but resolve after it completes must still
+        // return `undefined` so they can't resurrect a git service (and re-assert
+        // `superblocks/live`) by assigning the activated value and running
+        // `ensureLiveBranchCheckedOut`. The only legitimate path that flips this
+        // back to false is the `gitActivate` RPC, which represents an explicit
+        // user-driven reconnect; automatic paths (editor-reconnect's
+        // fire-and-forget `void activateGitService()`) must not override a manual
+        // disconnect.
+        let disconnectInProgress = false;
+        // The auth flag behind `remoteAuthFailed` lives outside this handler set
+        // because the dev server's own auto-commit pushes to the same remote with
+        // the same credential and has to be able to report a rejection too.
+        clearGitAuthFailed();
+        const getActiveGitService = async () => {
+            if (disconnectInProgress) {
+                return undefined;
+            }
+            if (activeGitService) {
+                await ensureLiveBranchCheckedOut(activeGitService);
+                if (disconnectInProgress) {
+                    return undefined;
+                }
+                aiService?.setRuntimeGitServices(activeGitService, syncService, gitOperationLock);
+                return activeGitService;
+            }
+            if (!activateGitService) {
+                return undefined;
+            }
+            // Post-connect git activation may race with server-side persistence.
+            // Retry briefly so users don't need a manual dev server restart.
+            const maxAttempts = 5;
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                if (disconnectInProgress) {
+                    return undefined;
+                }
+                try {
+                    const activated = await activateGitService();
+                    if (disconnectInProgress) {
+                        return undefined;
+                    }
+                    activeGitService = activated;
+                    if (activeGitService) {
+                        clearGitAuthFailed();
+                        await ensureLiveBranchCheckedOut(activeGitService);
+                        if (disconnectInProgress) {
+                            return undefined;
+                        }
+                        aiService?.setRuntimeGitServices(activeGitService, syncService, gitOperationLock);
+                        return activeGitService;
+                    }
+                }
+                catch (error) {
+                    getLogger().warn("[git] activation attempt failed", {
+                        gitCategory: "setup",
+                        gitOperation: "activate",
+                        gitOutcome: "failed",
+                        gitAttempt: attempt,
+                        gitMaxAttempts: maxAttempts,
+                        ...getErrorMeta(error),
+                    });
+                    if (attempt === maxAttempts) {
+                        getLogger().error(`[git] activation attempts exhausted (${attempt}/${maxAttempts})`, getErrorMeta(error));
+                        throw error;
+                    }
+                }
+                if (attempt < maxAttempts) {
+                    await new Promise((resolve) => {
+                        setTimeout(resolve, 750);
+                    });
+                }
+            }
+            return undefined;
+        };
+        async function runWithGitLock(fn) {
+            if (!gitOperationLock) {
+                return fn();
+            }
+            const result = gitOperationLock.tryAcquire();
+            if (!result.acquired) {
+                throw new Error(GIT_OPERATION_BUSY_MESSAGE);
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                result.release();
+            }
+        }
+        const handleUpgrade = (req, socket, head) => {
             if (!req.url) {
                 return;
             }
             const url = new URL(req.url, "http://localhost");
             // TODO: some sort of authorization? this socket shouldnt be open outside of superblocks
             if (url.pathname === path) {
-                let isEditor = false;
-                if (req.headers["sec-websocket-protocol"] === "editor") {
-                    isEditor = true;
-                }
+                // Read once, before `handleUpgrade` takes the request over, so the
+                // refusal below reports what was actually classified.
+                const offeredProtocols = req.headers["sec-websocket-protocol"];
+                const kind = classifyConnectionKind(offeredProtocols);
+                let isUpgraded = false;
                 wss.handleUpgrade(req, socket, head, (ws) => {
+                    if (isUpgraded) {
+                        return;
+                    }
+                    isUpgraded = true;
+                    // Without an error listener, a ws receiver error (e.g. an inbound
+                    // frame over maxPayload) is rethrown by the EventEmitter and kills
+                    // the process via uncaughtException. ws already closes the
+                    // offending socket itself (1009 Message Too Big for oversized
+                    // frames), so containment only requires observing the error.
+                    //
+                    // Attached before any branch below closes the socket: a refused
+                    // connection can still have frames on it, and one that raises while
+                    // being closed would otherwise be the crash this guards against.
+                    ws.on("error", (error) => {
+                        getLogger().error(`[socket-manager] websocket error (${describeUpgradePeer(url, req)})`, getErrorMeta(error));
+                    });
+                    if (kind === "unsupported") {
+                        // `ws` answers without a `Sec-WebSocket-Protocol` header when no
+                        // offer matched, which a compliant client already treats as a
+                        // failed handshake. Closing here covers a lenient one, so a peer
+                        // that asked for a role never ends up on a connection that would
+                        // silently ignore it.
+                        getLogger().error(`[socket-manager] refusing upgrade offering unsupported subprotocol(s): ${offeredProtocols ?? "none"} (${describeUpgradePeer(url, req)})`);
+                        ws.close(1002, "Unsupported subprotocol");
+                        return;
+                    }
                     const peerId = url.searchParams.get("peerId");
                     if (!peerId) {
                         getLogger().error("No peerId in upgrade request");
                         ws.close(1008, "No peerId found");
                         return;
                     }
-                    wss.emit("connection", ws, isEditor, url.searchParams.get("peerId"), url.searchParams.get("userId"));
+                    if (url.searchParams.get("applicationId") !== syncService?.applicationId) {
+                        getLogger().error("Application ID mismatch", {
+                            error: {
+                                kind: "ValidationError",
+                                message: `Expected application ID ${syncService?.applicationId}, received ${url.searchParams.get("applicationId")}`,
+                            },
+                        });
+                        ws.close(1008, "Application ID mismatch");
+                        return;
+                    }
+                    wss.emit("connection", ws, kind, url.searchParams.get("peerId"), url.searchParams.get("userId"));
                 });
             }
-        });
-        wss.on("connection", (ws, isEditor, peerId, userId) => {
-            const socket = createISocketClient(new ISocket(ws, withMethodTracing(tracer, {
+            else {
+                // Noop
+            }
+        };
+        server.on("upgrade", handleUpgrade);
+        this._disposer = () => {
+            server.removeListener("upgrade", handleUpgrade);
+            wss.close();
+        };
+        wss.on("connection", (ws, kind, peerId, userId) => {
+            const isEditor = kind === "editor";
+            const connectionLiveness = kind === "library" ? undefined : this.peerLiveness.bindConnection();
+            if (connectionLiveness) {
+                ws.on("message", () => connectionLiveness.markInbound());
+            }
+            /**
+             * When an editor authenticates after git was enabled, the lock may
+             * still be on 'main'. This calls
+             * `ensureRuntimeDbfsBranchConsistency` -> `lockService.switchBranch`
+             * to move it to superblocks/live.
+             */
+            const activateGitForAuthedEditor = () => {
+                if (!activateGitService) {
+                    return;
+                }
+                void activateGitService().catch((err) => {
+                    getLogger().warn(`[socket-manager] post-auth git activation failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            };
+            const authMiddleware = async (params, ctx, _peer, next) => {
+                const result = await checkAuthorization(ctx.peerAuthorization);
+                if (!result.success) {
+                    throw new SocketErrorException(result.status, result.error);
+                }
+                if (isEditor && this.editorSockets.has(socket)) {
+                    this.authenticatedEditorSockets.add(socket);
+                }
+                if (kind === "gateway" && this.gatewaySockets.has(socket)) {
+                    this.authenticatedGatewaySockets.add(socket);
+                    this.sendEditorStructureReport(socket);
+                }
+                if (isEditor &&
+                    userId &&
+                    !this.editorPresenceUserIdByPeerId.has(peerId) &&
+                    // The authorization above is awaited, so the socket that asked for
+                    // it can be gone by now. `peerIds` loses the peer when its last
+                    // socket closes, so this is what keeps a late answer from
+                    // registering presence nothing is left to remove.
+                    this.peerIds.has(peerId)) {
+                    this.editorPresenceUserIdByPeerId.set(peerId, userId);
+                    lockService?.addConnectedPeerIdToUser(userId, peerId);
+                }
+                // After presence, and only for a peer that has proved itself.
+                //
+                // Git activation moves the DBFS branch, which asks the lock service
+                // whether this pod holds the lock. Presence registration is what
+                // starts the attach-time acquisition, so running this first — as it
+                // did from the connect handler — asks that question before there is
+                // an acquisition to observe: `isLockedWhenSettled()` settles what is
+                // in flight, and nothing is. The switch then answers "no lock",
+                // releases the one that lands moments later, and does not take it
+                // back. Ordering them here is what keeps the two consistent.
+                if (isEditor && !this.gitActivatedPeerIds.has(peerId)) {
+                    this.gitActivatedPeerIds.add(peerId);
+                    activateGitForAuthedEditor();
+                }
+                // Notify AiService that this peer has just produced a
+                // proof-of-auth. AiService deduplicates internally and uses
+                // this signal to drain state pushes that were deferred at
+                // socket-connect time (which has no auth proof yet — only
+                // the upgrade path's `applicationId` check). PR #19718.
+                //
+                // We additionally thread the JWT-derived userId so the resync
+                // only pushes task summaries the caller owns. Without this,
+                // user B reconnecting to an AiService running user A's task
+                // would receive A's `taskId` and could then cancel it via
+                // the UI path. See peer-push.ts:resyncActiveTaskStatusesToPeer.
+                if (aiService && isEditor) {
+                    try {
+                        const callerUserId = extractCallerUserId(ctx.peerAuthorization);
+                        aiService.notifyAuthenticatedRpc(peerId, callerUserId);
+                    }
+                    catch (err) {
+                        getLogger().warn("[socket-manager] notifyAuthenticatedRpc threw; continuing", getErrorMeta(err));
+                    }
+                }
+                // Everything a gateway peer is trusted with hangs off this proof.
+                // The `gateway` subprotocol is client-controlled and grants nothing
+                // on its own: the upgrade path only checks `applicationId`.
+                if (kind === "gateway") {
+                    // Liveness, refreshed by each authorized call. The lock service
+                    // decays it, so a gateway that stops talking stops protecting the
+                    // sandbox instead of pinning the lock forever.
+                    lockService?.markGatewayAttached(peerId);
+                    // A peer that names the turn in flight is that turn reattaching, so
+                    // it follows the peer rather than reporting into the socket it
+                    // lost. Naming it is required — otherwise any authorized gateway
+                    // session could take over another one's turn.
+                    const headlessTurnId = readHeadlessTurnId(params);
+                    if (ctx.method !== "editor.releaseTurnLock") {
+                        aiService?.claimHeadlessTurn(socket, peerId, headlessTurnId, connectionLiveness);
+                        if (headlessTurnId) {
+                            const owner = headlessLockOwners.find((candidate) => candidate.turnId === headlessTurnId);
+                            if (owner) {
+                                owner.peerId = peerId;
+                            }
+                        }
+                    }
+                }
+                return await next();
+            };
+            // Create recording middleware if AI service is available
+            const recordingMiddleware = aiService
+                ? createSocketRecordingMiddleware(aiService.getRecordingManager())
+                : undefined;
+            // Build middleware array: recording first (for debugging), then auth
+            const middlewares = [recordingMiddleware, authMiddleware].filter((m) => m != null);
+            const socket = createISocketClient(new TracedSocket(ws, {
                 editor: {
-                    // Update widgets
-                    setProperties: [fileSyncManager.handleSetProperties],
-                    deleteProperties: [fileSyncManager.handleDeleteProperties],
-                    moveComponent: [fileSyncManager.handleReparent],
-                    createComponent: [fileSyncManager.handleCreateComponent],
-                    deleteComponents: [fileSyncManager.handleDeleteComponents],
-                    setProperty: [fileSyncManager.handleSetProperty],
-                    batchUpdate: [fileSyncManager.handleBatchUpdate],
                     // Renames
                     renameElement: [fileSyncManager.handleRenameElement],
                     renameApi: [fileSyncManager.handleRenameApi],
-                    // Update entities (variables, timers, events)
-                    addEntity: [fileSyncManager.handleAddEntity],
-                    updateEntity: [fileSyncManager.handleUpdateEntity],
-                    deleteEntity: [fileSyncManager.handleDeleteEntity],
-                    // Update theme
-                    updateTheme: [fileSyncManager.handleUpdateTheme],
                     // Update APIs
                     apiUpdate: [fileSyncManager.handleUpdateApi],
                     apiDelete: [fileSyncManager.handleDeleteApi],
@@ -69,35 +582,978 @@ export class SocketManager extends EventEmitter {
                             if (!syncService) {
                                 throw new Error("Syncing is disabled, cannot ensure files are synced");
                             }
-                            return await syncService.uploadDirectoryNowIfNeeded();
+                            const result = await syncService.uploadDirectoryNowIfNeeded("requestedFilesSync");
+                            return result.directoryHash;
                         },
                     ],
                     // AI + draft handling
                     aiGenerate: [
-                        async (request, _context, peer) => {
-                            await aiService?.handleAiGenerate(request, peer);
+                        async (request) => {
+                            const inputSource = { kind, peerId };
+                            await aiService?.handleAiGenerate(request, inputSource);
+                        },
+                    ],
+                    aiGenerateWithQueue: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            // A headless turn's pushes and tool callbacks belong to the
+                            // gateway peer that asked for the work, not to whichever
+                            // socket connected most recently. The prompt's own
+                            // `requestId` is the correlator that same caller presents to
+                            // reacquire this turn after losing its socket. Legacy
+                            // callers that omit it receive a server-minted identity.
+                            const { queueMode, ...aiRequest } = request;
+                            const inputSource = { kind, peerId };
+                            if (kind !== "gateway") {
+                                return await aiService.handleAiGenerateWithQueue(aiRequest, queueMode, inputSource);
+                            }
+                            // Write access is taken per turn, not held for the whole
+                            // session, so the app is unlocked between prompts and a
+                            // person can open it. Before the turn is bound, and
+                            // awaited: a turn that cannot write must fail here carrying
+                            // the server's own reason — somebody is editing in the
+                            // browser — rather than bind routing and then unwind it.
+                            const requestedTurnId = typeof request.requestId === "string" &&
+                                request.requestId.length > 0
+                                ? request.requestId
+                                : randomUUID();
+                            const headlessRequest = {
+                                ...aiRequest,
+                                requestId: requestedTurnId,
+                            };
+                            const lockOwner = {
+                                handbackFailed: false,
+                                peerId,
+                                turnId: requestedTurnId,
+                            };
+                            const turnId = await headlessLockOperationQueue.enqueue(async () => {
+                                await lockService?.acquireLockForTurn();
+                                headlessLockOwners.push(lockOwner);
+                                return aiService.beginHeadlessTurn(socket, peerId, requestedTurnId, connectionLiveness);
+                            });
+                            let result;
+                            try {
+                                result = await aiService.handleAiGenerateWithQueue(headlessRequest, queueMode, inputSource);
+                                const ownerIndex = headlessLockOwners.indexOf(lockOwner);
+                                for (let index = ownerIndex - 1; index >= 0; index--) {
+                                    if (headlessLockOwners[index]?.peerId === peerId) {
+                                        headlessLockOwners.splice(index, 1);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                // The turn is bound before the prompt is handed over, so
+                                // a prompt that never starts has no generation to settle
+                                // it. Left bound, it would capture the next turn a user
+                                // starts in the browser.
+                                aiService.abandonHeadlessTurn(peerId, turnId);
+                                try {
+                                    await releaseHeadlessLock(peerId, turnId);
+                                }
+                                catch (releaseErr) {
+                                    getLogger().warn("[socket-manager] failed to release the lock for a rejected headless turn", getErrorMeta(releaseErr));
+                                }
+                                throw err;
+                            }
+                            // Answering with the turn handle tells the caller two
+                            // things it cannot otherwise know: that this server routed
+                            // the turn to it as a gateway peer at all, and which turn to
+                            // name on a reattach.
+                            return { ...result, headlessTurn: { turnId } };
+                        },
+                    ],
+                    releaseTurnLock: [
+                        async (request) => {
+                            if (kind !== "gateway") {
+                                throw new Error("Only gateway peers can release a headless turn lock");
+                            }
+                            if (await releaseHeadlessLock(peerId, request.headlessTurnId)) {
+                                aiService?.endHeadlessTurn(peerId, request.headlessTurnId);
+                            }
+                        },
+                    ],
+                    aiTriggerMigrationTurn: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            return await aiService.handleAiTriggerMigrationTurn(request);
                         },
                     ],
                     aiRejectDraft: [
-                        async (_request, _context, peer) => {
-                            await syncService?.discardLocalDraftChanges();
-                            await aiService?.handleUserRejectedDraft(peer);
+                        async (request) => {
+                            await syncService?.discardLocalDraftChanges("ai:reject");
+                            await aiService?.handleUserRejectedDraft(request.silently);
                         },
                     ],
                     aiAcceptDraft: [
-                        async (_request, _context, peer) => {
-                            await syncService?.commitLocalDraftChanges();
-                            await aiService?.handleUserAcceptedDraft(peer);
+                        async (request, _context) => {
+                            if (!syncService) {
+                                throw new Error("Sync service not available");
+                            }
+                            getLogger().info("[aiAcceptDraft] accept draft start", {
+                                applicationId: syncService.applicationId,
+                                branchName: syncService.branchName,
+                                silently: request.silently,
+                            });
+                            const result = await syncService.commitLocalDraftChanges("ai:accept");
+                            getLogger().info("[aiAcceptDraft] draft commit completed", {
+                                applicationId: syncService.applicationId,
+                                branchName: syncService.branchName,
+                                commitId: result?.commitId,
+                                hasCommitId: Boolean(result?.commitId),
+                            });
+                            const draftStateReport = syncService.waitForDraftStateReport(false);
+                            await aiService?.handleUserAcceptedDraft(request.silently);
+                            getLogger().info("[aiAcceptDraft] accepted draft chat state handled", {
+                                applicationId: syncService?.applicationId,
+                                branchName: syncService?.branchName,
+                                commitId: result?.commitId,
+                                silently: request.silently,
+                            });
+                            const handleCleanupError = (error) => {
+                                if (!result?.commitId) {
+                                    throw error;
+                                }
+                                return false;
+                            };
+                            let draftStateCleared = await draftStateReport.catch(handleCleanupError);
+                            if (draftStateCleared !== true) {
+                                draftStateCleared = await syncService
+                                    .reportDraftStateToServer(false)
+                                    .catch(handleCleanupError);
+                            }
+                            if (draftStateCleared !== true) {
+                                if (!result?.commitId) {
+                                    throw new Error("Failed to clear server draft state");
+                                }
+                                getLogger().warn("[aiAcceptDraft] checkpoint saved but draft-state cleanup failed", {
+                                    applicationId: syncService.applicationId,
+                                    branchName: syncService.branchName,
+                                    commitId: result.commitId,
+                                });
+                            }
+                            if (result?.commitId) {
+                                // Upload context file to bucketeer asynchronously (fire-and-forget)
+                                if (aiService && syncService) {
+                                    void (async () => {
+                                        try {
+                                            // Get contextId using the same pattern as other context operations
+                                            // This gets userId from clark.context.jwt
+                                            const contextId = aiService.getContextId();
+                                            if (!contextId) {
+                                                getLogger().warn("[aiAcceptDraft] No contextId available (JWT missing or no userId), skipping context upload");
+                                                return;
+                                            }
+                                            // Get JWT from clark context (same source as userId)
+                                            // We need to access it via a method or use peer authorization as fallback
+                                            const jwt = aiService.getClarkJwt() ||
+                                                _context.peerAuthorization?.replace("Bearer ", "");
+                                            if (!jwt) {
+                                                getLogger().warn("[aiAcceptDraft] No JWT found, skipping context upload");
+                                                return;
+                                            }
+                                            await uploadContextToBucketeer({
+                                                applicationId: syncService.applicationId,
+                                                commitId: result.commitId,
+                                                branchName: syncService.branchName,
+                                                appRootDirPath: aiService.appRootDirPath,
+                                                useServerUpload: aiService.isAiFileUploadEnabled,
+                                                superblocksBaseUrl: aiService.superblocksBaseUrl,
+                                                logger: getLogger(),
+                                                jwt,
+                                            });
+                                            getLogger().info("[aiAcceptDraft] context upload completed", {
+                                                applicationId: syncService.applicationId,
+                                                branchName: syncService.branchName,
+                                                commitId: result.commitId,
+                                                contextUserId: contextId.userId,
+                                            });
+                                        }
+                                        catch (error) {
+                                            getLogger().warn("[aiAcceptDraft] Failed to upload context to bucketeer (non-blocking)", getErrorMeta(error));
+                                            // Don't throw - this is fire-and-forget
+                                        }
+                                    })();
+                                }
+                                return draftStateCleared === true
+                                    ? { commitId: result.commitId }
+                                    : {
+                                        commitId: result.commitId,
+                                        warning: {
+                                            code: "draft_state_cleanup_failed",
+                                            message: "Checkpoint saved, but the server draft state could not be cleared",
+                                        },
+                                    };
+                            }
+                            getLogger().info("[aiAcceptDraft] No new checkpoint created for ai:accept (no hash changes from last checkpoint)");
+                            return { commitId: "" };
+                        },
+                    ],
+                    aiClearDraftState: [
+                        async () => {
+                            await syncService?.clearDraftsDirectory();
                         },
                     ],
                     aiCancel: [
                         async () => {
-                            await syncService?.discardLocalDraftChanges();
                             await aiService?.handleUserCanceled();
+                            await syncService?.reportDraftStateToServer(false);
+                        },
+                    ],
+                    aiNotifyIntegrationSetupClosed: [
+                        async () => {
+                            await aiService?.handleIntegrationSetupClosed();
+                        },
+                    ],
+                    aiInterpretPrompt: [
+                        async (request) => {
+                            await aiService?.handlePromptInterpretation(request);
+                        },
+                    ],
+                    aiSummarizeApiUsage: [
+                        async (request) => {
+                            await aiService?.handleAiSummarizeApiUsage(request);
+                        },
+                    ],
+                    aiSummarizeError: [
+                        async (request) => {
+                            await aiService?.handleAiSummarizeError(request);
+                        },
+                    ],
+                    aiSkipTestCase: [
+                        async (request) => {
+                            await aiService?.handleSkipTestCase(request.testRunId, request.testCaseId);
+                        },
+                    ],
+                    aiRespondToToolPermission: [
+                        async (request) => {
+                            await aiService?.handleAiRespondToToolPermission(request);
+                        },
+                    ],
+                    aiCancelBackgroundTask: [
+                        async (request, _context) => {
+                            if (!aiService) {
+                                return { cancelled: false };
+                            }
+                            // Thread the JWT-derived caller identity so
+                            // AiService can deny cross-owner cancellations
+                            // (opaque `{ cancelled: false }`, matching the
+                            // existing unknown / already-terminal shape). Without
+                            // this thread, an authenticated user holding another
+                            // user's `taskId` (e.g. seen on a stale reconnect)
+                            // could cancel work they don't own. PR #19718.
+                            const callerUserId = extractCallerUserId(_context?.peerAuthorization);
+                            return aiService.cancelBackgroundTask(request.taskId, callerUserId);
+                        },
+                    ],
+                    aiLabelAttachment: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            return await aiService.handleAiLabelAttachment(request);
+                        },
+                    ],
+                    aiChatGetMessages: [
+                        async (request) => {
+                            const messages = await aiService?.chatSessionStore.getMessages({
+                                force: request?.force,
+                            });
+                            return {
+                                messages: messages ?? [],
+                            };
+                        },
+                    ],
+                    aiNewChat: [
+                        async () => {
+                            return aiService?.handleNewChat();
+                        },
+                    ],
+                    aiGetAppFacts: [
+                        async () => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            const facts = await aiService.getAppFacts();
+                            return { facts };
+                        },
+                    ],
+                    aiDeleteAppFact: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            await aiService.deleteAppFact(request.path);
                         },
                     ],
+                    aiToggleAppFact: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            const fact = await aiService.toggleAppFact(request.path, request.isEnabled);
+                            return { fact };
+                        },
+                    ],
+                    aiMoveAppKnowledge: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            return await aiService.moveAppFact(request);
+                        },
+                    ],
+                    aiRestoreToCommit: [
+                        async (request, _context) => {
+                            // Update clark.context.jwt from socket if missing (for restore operations)
+                            if (aiService && _context.peerAuthorization) {
+                                const jwt = _context.peerAuthorization.replace("Bearer ", "");
+                                if (!aiService.getClarkJwt() && jwt) {
+                                    aiService.updateClarkJwt(jwt);
+                                }
+                            }
+                            await aiService?.handleRestoreToCommit(request.sinceTimestamp, request.commitId, request.applicationId, request.branchName);
+                        },
+                    ],
+                    handleRuntimeError: [
+                        async (request) => {
+                            aiService?.handleRuntimeError(request);
+                        },
+                    ],
+                    handleClearRuntimeError: [
+                        async (request) => {
+                            aiService?.handleClearRuntimeError(request.id);
+                        },
+                    ],
+                    handleClearRuntimeErrors: [
+                        async (request) => {
+                            aiService?.handleClearRuntimeErrors(request.before);
+                        },
+                    ],
+                    handleConsoleLog: [
+                        async (request) => {
+                            aiService?.handleConsoleLog(request);
+                        },
+                    ],
+                    handleApiRunRecord: [
+                        async (request) => {
+                            aiService?.handleApiRunRecord(request.apiId, request.run);
+                        },
+                    ],
+                    handleJudgeEvaluation: [
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("AI service not available");
+                            }
+                            return await aiService.handleJudgeEvaluation(request);
+                        },
+                    ],
+                    ping: [
+                        async (ping) => {
+                            if (ping?.isUserActive !== undefined) {
+                                if (ping.isUserActive) {
+                                    lockService?.markActivity(ping.isUserActive);
+                                    void lockService?.restartInactivityTimer();
+                                }
+                            }
+                        },
+                    ],
+                    setClarkLogsEnabled: [
+                        async (request) => {
+                            setClarkVerboseLogsEnabled(request.enabled);
+                            getLogger().info(`Clark log forwarding ${request.enabled ? "enabled" : "disabled"}`);
+                        },
+                    ],
+                    primeClarkInferenceJwt: [
+                        // Fail loudly. The browser is the only thing that can hand
+                        // over a working token, so it has to learn that this one
+                        // did not land.
+                        async (request) => {
+                            if (!aiService) {
+                                throw new Error("Cannot prime the Clark inference JWT: the AI service is not running");
+                            }
+                            if (!aiService.updateClarkJwt(request.jwt)) {
+                                throw new Error("The dev server rejected the Clark inference JWT");
+                            }
+                        },
+                    ],
+                    gitCommitLocal: [
+                        async (request) => runWithGitLock(async () => {
+                            try {
+                                const readyGitService = await getActiveGitService();
+                                if (!readyGitService) {
+                                    throw new Error("Git is not configured for this application");
+                                }
+                                await readyGitService
+                                    .fetch("origin", SUPERBLOCKS_LIVE_GIT_BRANCH)
+                                    .catch((fetchErr) => {
+                                    const msg = fetchErr instanceof Error
+                                        ? fetchErr.message
+                                        : String(fetchErr);
+                                    if (!msg.includes("couldn't find remote ref")) {
+                                        throw fetchErr;
+                                    }
+                                });
+                                const resolvedBaseUrl = superblocksBaseUrl || aiService?.superblocksBaseUrl;
+                                await ensureProviderWorkflowFiles(readyGitService, resolvedBaseUrl);
+                                await readyGitService.add(".");
+                                const result = await readyGitService.commit(request.message);
+                                return { sha: result.commit };
+                            }
+                            catch (error) {
+                                getLogger().error("[git] gitCommitLocal failed", getErrorMeta(error));
+                                markGitAuthFailed(error);
+                                throw error;
+                            }
+                        }),
+                    ],
+                    gitPushLiveBranch: [
+                        async () => runWithGitLock(async () => {
+                            try {
+                                const readyGitService = await getActiveGitService();
+                                if (!readyGitService) {
+                                    throw new Error("Git is not configured for this application");
+                                }
+                                await pushLiveBranchWithAutoRecreate(readyGitService);
+                                clearGitAuthFailed();
+                            }
+                            catch (error) {
+                                getLogger().error("[git] gitPushLiveBranch failed", getErrorMeta(error));
+                                markGitAuthFailed(error);
+                                throw error;
+                            }
+                        }),
+                    ],
+                    gitRollbackLastCommit: [
+                        async (request) => runWithGitLock(async () => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService) {
+                                throw new Error("Git is not configured for this application");
+                            }
+                            return rollbackLastCommit({
+                                gitService: readyGitService,
+                                expectedSha: request.expectedSha,
+                            });
+                        }),
+                    ],
+                    gitPull: [
+                        async (_request, _context) => runWithGitLock(async () => {
+                            try {
+                                const readyGitService = await getActiveGitService();
+                                if (!readyGitService) {
+                                    throw new Error("Git is not configured for this application");
+                                }
+                                await readyGitService.fetch();
+                                // APPS-4906: refuse to merge a project-root-shaped tree
+                                // that would delete the flat fullstack entrypoint and
+                                // brick the dev server. Runs before any stash/merge so the
+                                // working tree is left untouched on the last-good state.
+                                await assertIncomingLiveLayout(readyGitService);
+                                const status = await readyGitService.status();
+                                const hasLocalChanges = status.files.length > 0;
+                                if (hasLocalChanges) {
+                                    await readyGitService.add(".");
+                                    await readyGitService.stash();
+                                }
+                                let hasConflicts = false;
+                                let merged = false;
+                                try {
+                                    const mergeResult = await readyGitService.mergeRef(`origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`);
+                                    merged = !mergeResult.alreadyUpToDate;
+                                    if (merged) {
+                                        const unmerged = await readyGitService.getConflictedFiles();
+                                        if (unmerged.length > 0) {
+                                            hasConflicts = true;
+                                        }
+                                    }
+                                }
+                                catch (mergeError) {
+                                    if (!(mergeError instanceof GitConflictError)) {
+                                        getLogger().error("[git] gitPull: merge failed (non-conflict), aborting", getErrorMeta(mergeError));
+                                        try {
+                                            await readyGitService.raw(["merge", "--abort"]);
+                                        }
+                                        catch (abortErr) {
+                                            getLogger().warn(`[git] gitPull: merge --abort failed: ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
+                                        }
+                                        if (hasLocalChanges) {
+                                            try {
+                                                await readyGitService.stashPop();
+                                            }
+                                            catch (popErr) {
+                                                getLogger().warn(`[git] gitPull: stash pop after merge abort failed: ${popErr instanceof Error ? popErr.message : String(popErr)}`);
+                                            }
+                                        }
+                                        throw mergeError;
+                                    }
+                                    merged = true;
+                                    hasConflicts = true;
+                                }
+                                if (hasLocalChanges) {
+                                    try {
+                                        await readyGitService.stashPop();
+                                    }
+                                    catch (popError) {
+                                        if (popError instanceof GitConflictError) {
+                                            hasConflicts = true;
+                                        }
+                                        else {
+                                            getLogger().error("[git] gitPull: stash pop failed (non-conflict)", getErrorMeta(popError));
+                                            throw popError;
+                                        }
+                                    }
+                                    if (!hasConflicts) {
+                                        const unmerged = await readyGitService.getConflictedFiles();
+                                        if (unmerged.length > 0) {
+                                            hasConflicts = true;
+                                        }
+                                    }
+                                }
+                                if (hasConflicts) {
+                                    const conflictedFiles = await readyGitService.getConflictedFiles();
+                                    getLogger().warn("[git] pull conflict detected", {
+                                        gitCategory: "pull",
+                                        gitOperation: "pull",
+                                        gitOutcome: "conflict",
+                                        branch: SUPERBLOCKS_LIVE_GIT_BRANCH,
+                                        conflictedFileCount: conflictedFiles.length,
+                                        conflictedFiles,
+                                    });
+                                    clearGitAuthFailed();
+                                    return { merged: false, conflictedFiles };
+                                }
+                                clearGitAuthFailed();
+                                return { merged };
+                            }
+                            catch (error) {
+                                markGitAuthFailed(error);
+                                throw error;
+                            }
+                        }),
+                    ],
+                    gitSyncStatus: [
+                        async () => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService) {
+                                return gitBootstrapFailed
+                                    ? {
+                                        authFailed: gitBootstrapAuthFailed,
+                                        bootstrapFailed: true,
+                                    }
+                                    : null;
+                            }
+                            let hasUncommittedChanges = false;
+                            try {
+                                const status = await readyGitService.status();
+                                hasUncommittedChanges = status.files.length > 0;
+                            }
+                            catch (statusErr) {
+                                getLogger().warn("[git] gitSyncStatus status failed", {
+                                    gitCategory: "status",
+                                    gitOperation: "syncStatus",
+                                    gitOutcome: "failed",
+                                    gitErrorKind: "status_failed",
+                                    ...getErrorMeta(statusErr),
+                                });
+                                return null;
+                            }
+                            let ahead = 0;
+                            let behind = 0;
+                            try {
+                                let missingRemoteLiveBranch = false;
+                                await readyGitService
+                                    .fetch("origin", SUPERBLOCKS_LIVE_GIT_BRANCH)
+                                    .catch((fetchErr) => {
+                                    const msg = fetchErr instanceof Error
+                                        ? fetchErr.message
+                                        : String(fetchErr);
+                                    if (msg.includes("couldn't find remote ref")) {
+                                        missingRemoteLiveBranch = true;
+                                        return;
+                                    }
+                                    throw fetchErr;
+                                });
+                                if (!missingRemoteLiveBranch) {
+                                    const counts = await readyGitService.revList("HEAD", `origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`);
+                                    ahead = counts.ahead;
+                                    behind = counts.behind;
+                                }
+                                clearGitAuthFailed();
+                            }
+                            catch (fetchErr) {
+                                markGitAuthFailed(fetchErr);
+                                getLogger().warn("[git] gitSyncStatus fetch/revList failed", {
+                                    gitCategory: "status",
+                                    gitOperation: "syncStatus",
+                                    gitOutcome: "failed",
+                                    gitErrorKind: "fetch_or_rev_list_failed",
+                                    branch: SUPERBLOCKS_LIVE_GIT_BRANCH,
+                                    remote: "origin",
+                                    ...getErrorMeta(fetchErr),
+                                });
+                            }
+                            let aheadOfDefaultBranch = false;
+                            try {
+                                const defaultCounts = await getSyncCountsAgainstDefaultBranch({
+                                    gitService: readyGitService,
+                                    leftRef: "HEAD",
+                                });
+                                aheadOfDefaultBranch = defaultCounts.ahead > 0;
+                            }
+                            catch {
+                                // Optional: enable Open PR when branch has commits vs default.
+                            }
+                            const remoteLiveBranchExists = await doesRemoteLiveBranchExist(readyGitService);
+                            const isLiveBranchMissing = remoteLiveBranchExists === false;
+                            return {
+                                ahead,
+                                behind,
+                                hasUncommittedChanges,
+                                aheadOfDefaultBranch,
+                                isLiveBranchMissing,
+                                remoteAuthFailed: isGitAuthFailed(),
+                            };
+                        },
+                    ],
+                    gitChangedFiles: [
+                        async () => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService)
+                                return [];
+                            try {
+                                const status = await readyGitService.status();
+                                return status.files.map((f) => ({
+                                    path: f.path,
+                                    status: f.working_dir === "D" || f.index === "D"
+                                        ? "deleted"
+                                        : f.working_dir === "?" || f.index === "A"
+                                            ? "added"
+                                            : "modified",
+                                }));
+                            }
+                            catch (err) {
+                                getLogger().warn("[git] gitChangedFiles status failed", {
+                                    gitCategory: "status",
+                                    gitOperation: "changed-files",
+                                    gitOutcome: "failed",
+                                    gitErrorKind: "status_failed",
+                                    ...getErrorMeta(err),
+                                });
+                                return [];
+                            }
+                        },
+                    ],
+                    gitActivate: [
+                        async () => runWithGitLock(async () => {
+                            // `gitActivate` is fired on explicit user-driven
+                            // (re)connect; it is the sole path allowed to clear the
+                            // sticky `disconnectInProgress` flag set by
+                            // `gitDisconnect`. Without this reset, a user who
+                            // disconnects and then reconnects in the same process
+                            // would be stuck with git permanently disabled.
+                            disconnectInProgress = false;
+                            clearGitAuthFailed();
+                            const service = await getActiveGitService();
+                            return { activated: !!service };
+                        }),
+                    ],
+                    gitRefreshCredentials: [
+                        async () => runWithGitLock(async () => {
+                            if (!refreshGitCredentials) {
+                                return { refreshed: false };
+                            }
+                            const service = await refreshGitCredentials();
+                            if (!service) {
+                                return { refreshed: false };
+                            }
+                            activeGitService = service;
+                            clearGitAuthFailed();
+                            aiService?.setRuntimeGitServices(service, syncService, gitOperationLock);
+                            return { refreshed: true };
+                        }),
+                    ],
+                    gitDisconnect: [
+                        async () => runWithGitLock(async () => {
+                            // Atomically deactivate git BEFORE any teardown work so
+                            // that concurrent callers of getActiveGitService() can't
+                            // grab the old service and force `superblocks/live` back
+                            // via ensureLiveBranchCheckedOut() while we're switching
+                            // branches and removing `.git`.
+                            const serviceToDisconnect = activeGitService;
+                            activeGitService = undefined;
+                            disconnectInProgress = true;
+                            clearGitAuthFailed();
+                            // Keep file-sync / lock wiring; drop only the Git
+                            // service so the next Clark turn sees unconnected.
+                            aiService?.setRuntimeGitServices(undefined, syncService, gitOperationLock);
+                            // Ensure DBFS sync context is no longer tied to
+                            // `superblocks/live` immediately after native git disconnect.
+                            syncService?.setBranchName(DEFAULT_NON_GIT_BRANCH);
+                            // Native git disconnect should move runtime lock context back
+                            // to default branch before clients reconnect.
+                            if (lockService) {
+                                // Retain the pre-switch state for the explicit fallback
+                                // if an atomic branch transfer fails.
+                                const wasLockedBeforeDisconnect = await lockService.isLockedWhenSettled();
+                                try {
+                                    await lockService.switchBranch(DEFAULT_NON_GIT_BRANCH);
+                                }
+                                catch (err) {
+                                    getLogger().warn("[git] gitDisconnect failed to switch lock branch back to main", {
+                                        gitCategory: "setup",
+                                        gitOperation: "disconnect",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "switch_lock_branch_failed",
+                                        ...getErrorMeta(err),
+                                    });
+                                    try {
+                                        await lockService.switchBranch(DEFAULT_NON_GIT_BRANCH, {
+                                            reacquireLock: false,
+                                        });
+                                        if (wasLockedBeforeDisconnect) {
+                                            await lockService.acquireLock();
+                                        }
+                                    }
+                                    catch (fallbackErr) {
+                                        getLogger().warn("[git] gitDisconnect fallback lock reset to main failed", {
+                                            gitCategory: "setup",
+                                            gitOperation: "disconnect",
+                                            gitOutcome: "failed",
+                                            gitErrorKind: "fallback_lock_reset_failed",
+                                            ...getErrorMeta(fallbackErr),
+                                        });
+                                    }
+                                }
+                            }
+                            if (serviceToDisconnect) {
+                                const gitDir = join(serviceToDisconnect.workDir, ".git");
+                                // Never checkout: live-only files would be deleted
+                                // with no way back once .git is gone.
+                                try {
+                                    await rm(gitDir, { recursive: true, force: true });
+                                }
+                                catch (rmErr) {
+                                    getLogger().warn("[git] gitDisconnect failed to remove .git directory; manual cleanup may be required", {
+                                        gitCategory: "setup",
+                                        gitOperation: "disconnect",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "git_dir_removal_failed",
+                                        gitDir,
+                                        ...getErrorMeta(rmErr),
+                                    });
+                                }
+                            }
+                        }),
+                    ],
+                    gitDefaultBranch: [
+                        async () => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService)
+                                return null;
+                            try {
+                                return await readyGitService.getDefaultBranch();
+                            }
+                            catch (err) {
+                                getLogger().warn("[git] gitDefaultBranch failed", {
+                                    gitCategory: "branch",
+                                    gitOperation: "default-branch",
+                                    gitOutcome: "failed",
+                                    gitErrorKind: "default_branch_detection_failed",
+                                    ...getErrorMeta(err),
+                                });
+                                return null;
+                            }
+                        },
+                    ],
+                    gitBranchLog: [
+                        async (request) => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService)
+                                return [];
+                            const limit = (request && "limit" in request
+                                ? request.limit
+                                : undefined) ?? 50;
+                            const remote = request && "remote" in request
+                                ? (request.remote ?? true)
+                                : true;
+                            let branch;
+                            if (request && "branch" in request && request.branch) {
+                                branch = request.branch;
+                            }
+                            else {
+                                try {
+                                    branch = await readyGitService.getDefaultBranch();
+                                }
+                                catch (defaultBranchErr) {
+                                    getLogger().warn("[git] gitBranchLog default branch detection failed", {
+                                        gitCategory: "branch",
+                                        gitOperation: "branch-log",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "branch_log_default_branch_detection_failed",
+                                        remote: "origin",
+                                        ...getErrorMeta(defaultBranchErr),
+                                    });
+                                    const status = await readyGitService
+                                        .status()
+                                        .catch(() => null);
+                                    const fallbackBranch = status?.current?.trim();
+                                    if (!fallbackBranch) {
+                                        return [];
+                                    }
+                                    branch = fallbackBranch;
+                                }
+                            }
+                            const logRef = remote ? `origin/${branch}` : branch;
+                            if (remote) {
+                                try {
+                                    await readyGitService.fetch("origin", branch);
+                                }
+                                catch (fetchErr) {
+                                    getLogger().warn("[git] gitBranchLog fetch failed", {
+                                        gitCategory: "branch",
+                                        gitOperation: "branch-log",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "branch_log_fetch_failed",
+                                        branch,
+                                        remote: "origin",
+                                        ...getErrorMeta(fetchErr),
+                                    });
+                                }
+                            }
+                            const raw = await readyGitService.raw([
+                                "log",
+                                logRef,
+                                `--format=${GIT_LOG_FORMAT}`,
+                                `-n`,
+                                String(limit),
+                            ]);
+                            return parseGitLog(raw);
+                        },
+                    ],
+                    gitPrepareMainCommit: [
+                        async (request) => runWithGitLock(async () => {
+                            const readyGitService = await getActiveGitService();
+                            if (!readyGitService) {
+                                throw new Error("Git service is not available");
+                            }
+                            if (!syncService) {
+                                throw new Error("Sync service is not available");
+                            }
+                            const { sha } = request;
+                            if (!sha || !/^[0-9a-f]{5,40}$/i.test(sha)) {
+                                throw new Error("sha must be a valid git SHA");
+                            }
+                            let defaultBranch = null;
+                            try {
+                                defaultBranch =
+                                    await readyGitService.getDefaultBranch();
+                            }
+                            catch (defaultBranchErr) {
+                                getLogger().warn("[git] gitPrepareMainCommit default branch detection failed", {
+                                    gitCategory: "build",
+                                    gitOperation: "prepare-main-commit",
+                                    gitOutcome: "failed",
+                                    gitErrorKind: "prepare_main_commit_default_branch_detection_failed",
+                                    remote: "origin",
+                                    ...getErrorMeta(defaultBranchErr),
+                                });
+                            }
+                            if (defaultBranch) {
+                                try {
+                                    await readyGitService.fetch("origin", defaultBranch);
+                                }
+                                catch (fetchErr) {
+                                    getLogger().warn("[git] gitPrepareMainCommit fetch failed", {
+                                        gitCategory: "build",
+                                        gitOperation: "prepare-main-commit",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "prepare_main_commit_fetch_failed",
+                                        defaultBranch,
+                                        remote: "origin",
+                                        ...getErrorMeta(fetchErr),
+                                    });
+                                }
+                            }
+                            const worktreeBase = await mkdtemp(join(tmpdir(), "sb-main-deploy-"));
+                            const worktreePath = join(worktreeBase, "worktree");
+                            try {
+                                await readyGitService.raw([
+                                    "worktree",
+                                    "add",
+                                    "--detach",
+                                    worktreePath,
+                                    sha,
+                                ]);
+                                // Remove .git metadata from worktree so it doesn't affect the hash
+                                await rm(join(worktreePath, ".git"), {
+                                    force: true,
+                                    recursive: true,
+                                });
+                                const { directoryHash } = await syncService.uploadSnapshotToDbfs(worktreePath);
+                                // Persist the worktree snapshot so the SABS build can
+                                // use the commit-specific files instead of the live sandbox.
+                                const snapshotPath = join(SB_WORKTREE_SNAPSHOTS_DIR, encodeURIComponent(directoryHash));
+                                await mkdir(SB_WORKTREE_SNAPSHOTS_DIR, {
+                                    recursive: true,
+                                });
+                                await rm(snapshotPath, {
+                                    recursive: true,
+                                    force: true,
+                                });
+                                await cp(worktreePath, snapshotPath, {
+                                    recursive: true,
+                                });
+                                return { directoryHash, sha };
+                            }
+                            finally {
+                                try {
+                                    await readyGitService.raw([
+                                        "worktree",
+                                        "remove",
+                                        "--force",
+                                        worktreePath,
+                                    ]);
+                                }
+                                catch (cleanupErr) {
+                                    getLogger().warn("[git] gitPrepareMainCommit worktree cleanup failed", {
+                                        gitCategory: "build",
+                                        gitOperation: "prepare-main-commit",
+                                        gitOutcome: "failed",
+                                        gitErrorKind: "worktree_cleanup_failed",
+                                        worktreePath,
+                                        ...getErrorMeta(cleanupErr),
+                                    });
+                                }
+                                await rm(worktreeBase, {
+                                    recursive: true,
+                                    force: true,
+                                });
+                            }
+                        }),
+                    ],
+                },
+            }, middlewares, tracer, {
+                onClose: () => {
+                    getLogger().info("[socket-manager] TracedSocket connection closed");
                 },
-            }), [], undefined, undefined));
+                logger: {
+                    error: (message) => {
+                        getLogger().error(message ?? "");
+                    },
+                    info: (message) => {
+                        getLogger().info(message ?? "");
+                    },
+                    warn: (message) => {
+                        getLogger().warn(message ?? "");
+                    },
+                },
+            }));
+            if (connectionLiveness) {
+                this.socketLiveness.set(socket, connectionLiveness);
+            }
             // we are storing all of the sockets for a given peerId (editor+library pair of connections)
             // which lets us handle synchronization of operations between the two
             let existingSockets = this.peerIds.get(peerId);
@@ -105,68 +1561,250 @@ export class SocketManager extends EventEmitter {
                 existingSockets = new Set();
                 this.peerIds.set(peerId, existingSockets);
             }
-            if (isEditor) {
-                this.editorSockets.add(socket);
-                this.emit("connect:editor", socket);
-                if (userId) {
-                    lockService?.addConnectedPeerIdToUser(userId, peerId);
-                }
+            if (kind === "gateway") {
+                this.gatewaySockets.set(socket, peerId);
+                // Liveness is granted in the auth middleware, not here: the upgrade
+                // path only checks `applicationId`, and holding the sandbox open is
+                // not something an unproven socket gets to do.
+                this.emit("connect:gateway", socket, peerId, connectionLiveness);
+            }
+            else if (isEditor) {
+                this.editorSockets.set(socket, peerId);
+                this.editorPeerIdsBySocket.set(socket, peerId);
+                this.emit("connect:editor", socket, peerId, connectionLiveness);
+                // Git activation is deliberately NOT started here — it runs from the
+                // auth middleware, after presence. See `activateGitForAuthedEditor`.
             }
             else {
                 this.librarySockets.add(socket);
                 this.emit("connect:library", socket);
             }
             existingSockets.add(socket);
-            lockService?.stopShutdownTimerIfNeeded();
-            ws.on("err", (e) => {
-                getLogger().error("Socket error", getErrorMeta(e));
-            });
-            ws.on("close", async (code, reason) => {
-                this.peerIds.get(peerId)?.delete(socket);
-                getLogger().info(`Socket closed peerId: ${peerId} code: ${code} reason: ${reason}`);
-                if (isEditor) {
+            ws.on("close", (code, reason) => {
+                connectionLiveness?.close();
+                const peerSockets = this.peerIds.get(peerId);
+                peerSockets?.delete(socket);
+                if (peerSockets?.size === 0) {
+                    this.peerIds.delete(peerId);
+                    // The peer is gone, so a later reconnect under the same id is a
+                    // new arrival and activates git again.
+                    this.gitActivatedPeerIds.delete(peerId);
+                }
+                getLogger().info(`Socket from ${kind} closed code: ${code} reason: ${reason}`);
+                if (kind === "gateway") {
+                    this.gatewaySockets.delete(socket);
+                    lockService?.markGatewayDetached(peerId);
+                    // No blanket clear when the last socket goes: every peer's rows are
+                    // dropped by its own close, and the one that empties the list is
+                    // what hands the lock back.
+                    dropHeadlessLockOwnersInBackground(peerId, "a gateway socket closed");
+                    aiService?.endHeadlessTurn(peerId, connectionLiveness);
+                    this.emit("disconnect:gateway", peerId, connectionLiveness);
+                }
+                else if (isEditor) {
                     this.editorSockets.delete(socket);
-                    if (userId) {
-                        lockService?.removeConnectedPeerIdFromUser(userId, peerId);
+                    const hasOtherEditorSocket = Array.from(peerSockets ?? []).some((peerSocket) => this.editorSockets.has(peerSocket));
+                    if (!hasOtherEditorSocket) {
+                        // Keyed by peer, so whichever of the peer's sockets is last out
+                        // takes the presence down — including one that never authenticated
+                        // itself.
+                        const presenceUserId = this.editorPresenceUserIdByPeerId.get(peerId);
+                        if (presenceUserId) {
+                            this.editorPresenceUserIdByPeerId.delete(peerId);
+                            lockService?.removeConnectedPeerIdFromUser(presenceUserId, peerId);
+                            if (lockService?.connectedUsers.length === 0) {
+                                if (aiService?.isBusy()) {
+                                    getLogger().info("[socket-manager] All users disconnected but AI service is busy, deferring cache cleanup until generation completes");
+                                    let cleaned = false;
+                                    const deferredCleanup = () => {
+                                        if (cleaned)
+                                            return;
+                                        cleaned = true;
+                                        // Only clean up if no users have reconnected in the meantime
+                                        if (lockService?.connectedUsers.length === 0) {
+                                            getLogger().info("[socket-manager] Generation ended with no connected users, cleaning up AI service cache");
+                                            aiService
+                                                .removeIntegrationCache()
+                                                .catch((error) => {
+                                                getLogger().warn(`Error removing integration cache after deferred cleanup: ${error}`);
+                                            });
+                                        }
+                                        else {
+                                            getLogger().info("[socket-manager] Generation ended but users have reconnected, skipping cache cleanup");
+                                        }
+                                    };
+                                    aiService.once("generationCompleted", deferredCleanup);
+                                    aiService.once("generationFailed", deferredCleanup);
+                                }
+                                else {
+                                    getLogger().info("[socket-manager] All users disconnected, cleaning up AI service cache");
+                                    aiService
+                                        ?.removeIntegrationCache()
+                                        .catch((error) => {
+                                        getLogger().warn(`Error removing integration cache after disconnect: ${error}`);
+                                    });
+                                }
+                            }
+                        }
                     }
+                    this.emit("disconnect:editor", peerId, socket, connectionLiveness);
                 }
                 else {
                     this.librarySockets.delete(socket);
                 }
-                await this.checkSocketsRemainingAndShutdownIfNeeded(lockService);
             });
         });
     }
+    reportEditorHasDefaultStructure(hasDefaultStructure) {
+        if (hasDefaultStructure !== "yes" &&
+            hasDefaultStructure !== "no" &&
+            hasDefaultStructure !== "unknown") {
+            throw new Error("Invalid editor structure report");
+        }
+        this.editorStructureReport = { hasDefaultStructure };
+        for (const { peer } of this.getAuthenticatedGatewayPeers()) {
+            this.sendEditorStructureReport(peer);
+        }
+    }
+    sendEditorStructureReport(gateway) {
+        const report = this.editorStructureReport;
+        if (!report ||
+            this.editorStructureReportByGateway.get(gateway) ===
+                report.hasDefaultStructure) {
+            return;
+        }
+        this.editorStructureReportByGateway.set(gateway, report.hasDefaultStructure);
+        gateway.call.aiSetEditorHasDefaultStructure(report).catch((error) => {
+            if (this.editorStructureReportByGateway.get(gateway) ===
+                report.hasDefaultStructure) {
+                this.editorStructureReportByGateway.delete(gateway);
+            }
+            errorHandler(error);
+        });
+    }
+    callEditorClients(fn) {
+        for (const socket of this.editorSockets.keys()) {
+            fn(socket).catch(errorHandler);
+        }
+    }
     /**
-     * If we have no more socket connections, release the lock
-     * @param lockService
+     * Both registries, for the signals a headless turn needs as much as a browser
+     * tab does — file-sync status being the one that decides whether a checkpoint
+     * would capture work still on its way to the server.
+     *
+     * Deliberately not `callEditorClients`: a gateway peer stays out of
+     * `editorSockets`, so it is neither editor presence nor a candidate for the
+     * editor binding. Bounded by the same registries — one socket per browser tab
+     * and one per gateway session.
      */
-    async checkSocketsRemainingAndShutdownIfNeeded(lockService) {
-        const logger = getLogger();
-        if (this.editorSockets.size === 0 && this.librarySockets.size === 0) {
-            if (process.env.SUPERBLOCKS_IS_CSB === "true") {
-                // Only shutdown everything immediately if it's in the cloud editing mode
-                logger.info("[vite-plugin-file-sync] No more sockets remaining, shutting down immediately in cloud editing mode");
-                await lockService?.shutdownAndExit();
+    callEditorAndGatewayClients(fn) {
+        for (const socket of this.editorSockets.keys()) {
+            fn(socket).catch(errorHandler);
+        }
+        for (const socket of this.gatewaySockets.keys()) {
+            fn(socket).catch(errorHandler);
+        }
+    }
+    /**
+     * Any editor socket that does not belong to `exclude`.
+     *
+     * Used when a peer disconnects: Clark's RPCs are bound to a single editor,
+     * so a survivor is what keeps API execution alive for a user whose tab is
+     * still open after a headless build's socket closes.
+     *
+     * Same-id sockets are preferred when `exclude` is the departing socket: a
+     * tab that reconnected keeps the bound Clark context instead of handing it
+     * (and in-flight generation / tool-permission prompts) to whichever other
+     * editor happened to connect first. A string `exclude` still means "this
+     * peer is gone" and skips every socket with that id.
+     */
+    getSurvivingEditorClient(exclude) {
+        const excludedPeerId = typeof exclude === "string" ? exclude : undefined;
+        const preferredPeerId = typeof exclude === "string"
+            ? undefined
+            : this.editorPeerIdsBySocket.get(exclude);
+        const pick = (onlyPreferred) => {
+            for (const [peer, peerId] of this.editorSockets) {
+                const excluded = excludedPeerId !== undefined
+                    ? peerId === excludedPeerId
+                    : peer === exclude;
+                if (excluded) {
+                    continue;
+                }
+                if (onlyPreferred && peerId !== preferredPeerId) {
+                    continue;
+                }
+                const liveness = this.socketLiveness.get(peer);
+                if (liveness) {
+                    return { liveness, peer, peerId };
+                }
             }
-            else {
-                // If it's not in the cloud editing mode, we start a shutdown timer
-                // This will trigger a shutdown of the server after 5 minutes of inactivity
-                logger.info("[vite-plugin-file-sync] No more sockets remaining, starting shutdown timer in local editing mode");
-                await lockService?.startShutdownTimer();
+            return undefined;
+        };
+        if (preferredPeerId !== undefined) {
+            const sameId = pick(true);
+            if (sameId) {
+                return sameId;
             }
         }
+        return pick(false);
     }
-    callEditorClients(fn) {
-        for (const socket of this.editorSockets) {
+    callLibraryClients(fn) {
+        for (const socket of this.librarySockets) {
             fn(socket).catch(errorHandler);
         }
     }
-    callLibraryClients(fn) {
+    getAnyLibraryClient() {
+        return Array.from(this.librarySockets).at(0);
+    }
+    getEditorClients() {
+        return this.editorSockets.keys();
+    }
+    *getAuthenticatedEditorPeers() {
+        for (const [peer, peerId] of this.editorSockets) {
+            if (this.authenticatedEditorSockets.has(peer)) {
+                yield { peer, peerId };
+            }
+        }
+    }
+    *getAuthenticatedGatewayPeers() {
+        for (const [peer, peerId] of this.gatewaySockets) {
+            if (this.authenticatedGatewaySockets.has(peer)) {
+                yield { peer, peerId };
+            }
+        }
+    }
+    /**
+     * Attached headless gateway peers. Separate from {@link getEditorClients} so
+     * a broadcast meant for browser tabs never reaches a gateway, and the
+     * gateway's own lifecycle can be observed without editor semantics.
+     */
+    getGatewayClients() {
+        return this.gatewaySockets.keys();
+    }
+    /** The attached gateway peer with this peer id, if it is still connected. */
+    getGatewayClient(peerId) {
+        for (const [socket, candidate] of this.gatewaySockets) {
+            if (candidate === peerId) {
+                return socket;
+            }
+        }
+        return undefined;
+    }
+    closeAllClients() {
+        for (const socket of this.editorSockets.keys()) {
+            socket.close();
+        }
+        for (const socket of this.gatewaySockets.keys()) {
+            socket.close();
+        }
         for (const socket of this.librarySockets) {
-            fn(socket).catch(errorHandler);
+            socket.close();
         }
     }
+    dispose() {
+        this._disposer();
+    }
 }
 function errorHandler(err) {
     // ignore if a method is not callable or doesnt exist, just log it so we can debug and fix
@@ -174,8 +1812,18 @@ function errorHandler(err) {
     if (err != null &&
         typeof err === "object" &&
         "code" in err &&
-        (err.code === 2 || err.code === 3)) {
-        getLogger().error(`[socket] ${err.message}`, getErrorMeta(err));
+        // 2: unknown method
+        // 3: exception in message handler
+        // 8: connection closed by client while waiting for response
+        // see: https://github.com/superblocksteam/superblocks/blob/code-mode/packages/shared/src/socket/socket.ts
+        (err.code === 2 || err.code === 3 || err.code === 8 || err.code === 10)) {
+        // Connection closed (code 8) is expected when users close browser tabs - log as INFO
+        if (err.code === 8 || err.code === 10) {
+            getLogger().info(`[socket] Connection closed`, getErrorMeta(err));
+        }
+        else {
+            getLogger().error(`[socket] ${err.message}`, getErrorMeta(err));
+        }
     }
     else {
         throw err;