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

package/dist/lock-service/index.js

@@ -1,11 +1,24 @@
-import EventEmitter from "node:events";
-// TODO(David): Move the socket grpc library to a shared dir
-import { addTracingToMethods, ConflictError, NotFoundError, } from "@superblocksteam/shared";
+import { addTracingToMethods, ConflictError, NotFoundError, TracedEventEmitter, } from "@superblocksteam/shared";
+import { unwrapResponseDto } from "@superblocksteam/shared";
 import { applyErrorHandling, } from "../errors/error-handler.js";
-import { connectToISocketRPCServer, unwrapResponseDto, } from "../sync-service/server-rpc/client.js";
-import { getErrorMeta, getLogger } from "../util/logger.js";
+import { getErrorMeta } from "../util/logger.js";
+import { OperationQueue } from "../util/operation-queue.js";
+import { ActivityTracker } from "./activity-tracker.js";
 const LOCK_HEARTBEAT_INTERVAL_MS = 30 * 1000; // 30 seconds
-const SHUTDOWN_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const LOCK_BUFFER_MS = 30 * 1000; // 30 seconds
+/**
+ * How long a gateway peer's liveness signal counts for before it has to be
+ * renewed. A gateway refreshes it on every authorized call and, when it has
+ * nothing else to say, from its own heartbeat.
+ *
+ * A signal that only expired when the socket closed would be no signal at all
+ * for the case it exists to cover: a half-open connection that never closes
+ * would hold the exclusive per-app-branch lock indefinitely. Comfortably above
+ * the gateway's heartbeat interval so ordinary jitter is not mistaken for a
+ * dead peer, and far below the windows it defers (startup watchdog, idle
+ * reaper) so a genuinely dead one is noticed while they can still act.
+ */
+const GATEWAY_LIVENESS_TTL_MS = 90 * 1000; // 90 seconds
 export var LockServiceStatus;
 (function (LockServiceStatus) {
     /** The lock service is not currently active */
@@ -28,54 +41,145 @@ export var LockType;
     LockType["LOCAL"] = "local";
     LockType["CSB"] = "csb";
 })(LockType || (LockType = {}));
-export class LockService extends EventEmitter {
-    authToken;
-    superblocksBaseUrl;
+/**
+ * The methods {@link LockService} reports as spans.
+ *
+ * `addTracingToMethods` matches by string, so an entry naming a method that no
+ * longer exists is dropped at runtime rather than failing to compile — tracing
+ * disappears and nothing says so. Exported so a test can assert every name here
+ * still resolves to a method.
+ */
+export const TRACED_LOCK_SERVICE_METHODS = [
+    "acquireLock",
+    "releaseLock",
+    "relinquishLock",
+    "notifyClosedByServer",
+    "checkAndUpdateLockIfPossible",
+    "ensureLockForWrite",
+    "shutdownAndExit",
+    "restartInactivityTimer",
+    "switchBranch",
+];
+export class LockService extends TracedEventEmitter {
     applicationId;
     branchName;
     lockType;
     heartbeatIntervalMs;
-    rpcClient;
     syncCallback;
+    waitForGenerationCompleteCallback;
+    onGatewayLivenessLapsed;
+    onLockConflict;
     _status = LockServiceStatus.IDLE;
     _lockId;
     _heartbeatTimeout;
-    _shutdownTimeout;
-    _connectedUserPeerIdsMap = new Map();
+    // Incremented on every heartbeat (re)start and on stop, so an in-flight
+    // scheduleNextHeartbeat() chain can detect it was superseded and avoid
+    // re-arming after the heartbeat was intentionally stopped.
+    _heartbeatGeneration = 0;
+    // True only while the heartbeat is stopped because the user went idle
+    // (ready for takeover). Distinguishes that case from operational stops
+    // (lock release, shutdown, branch switch) so only idle-stops auto-resume.
+    _heartbeatStoppedForIdle = false;
+    // True from the moment the lock is deliberately given up until one is held
+    // again. The durable answer to "did we choose to let this go?", which the
+    // status cannot give: `checkAndUpdateLockIfPossible`, `switchBranch` and a
+    // failed release all reset it to IDLE, and IDLE is what tells the claim path
+    // a lock has never been held. Also the only thing that still remembers by the
+    // time a grab left over from before the release fails.
+    _lockGivenUp = false;
+    _closedByServer = false;
+    /**
+     * True only while the last-chance sync of a session that is ending is in
+     * flight. That write is not gated on still holding the lock — see
+     * {@link ensureLockForWrite}.
+     */
+    _flushingFinalWork = false;
+    /** The evaluation overlapping callers join rather than starting their own. */
+    _inFlightLockEvaluation;
+    _inactivityTimeout;
+    _bufferPeriodTimeout;
+    _isRestarting = false;
     _tracer;
+    _logger;
+    _rpcClient;
+    _inactivityThresholdMs;
+    _lockBufferMs;
+    /** In-flight acquisition kicked off by a client attaching, if any. */
+    _clientLockAcquisition;
+    _lockOperationQueue = new OperationQueue();
+    _activityTracker;
+    /** Gateway peer id -> when its liveness was last refreshed. */
+    _gatewayLivenessByPeerId = new Map();
+    _gatewayLivenessTtlMs;
+    _gatewayLivenessSweep;
     constructor(config) {
-        super();
-        this.authToken = config.authToken;
-        this.superblocksBaseUrl = config.superblocksBaseUrl;
+        super(config.tracer);
         this.applicationId = config.applicationId;
         this.branchName = config.branchName;
         this.lockType = config.lockType;
+        this._inactivityThresholdMs = config.inactivityThresholdMs;
         this.heartbeatIntervalMs =
             config.heartbeatIntervalMs || LOCK_HEARTBEAT_INTERVAL_MS;
-        this.rpcClient = null;
+        this._lockBufferMs = config.lockBufferMs || LOCK_BUFFER_MS;
+        this._gatewayLivenessTtlMs =
+            config.gatewayLivenessTtlMs || GATEWAY_LIVENESS_TTL_MS;
+        this._rpcClient = config.rpcClient;
         this._tracer = config.tracer;
+        this._logger = config.logger;
+        // Initialize activity tracker
+        this._activityTracker = new ActivityTracker({
+            logger: config.logger,
+            inactivityThresholdMs: this._inactivityThresholdMs,
+        });
         applyErrorHandling(this, {
             acquireLock: { operation: "acquiring lock" },
             releaseLock: { operation: "releasing lock" },
         });
-        const methods = [
-            "acquireLock",
-            "releaseLock",
-            "checkAndUpdateLockIfPossible",
-            "shutdown",
-            "shutdownAndExit",
-        ];
-        addTracingToMethods(this, methods, this._tracer);
+        addTracingToMethods(this, [...TRACED_LOCK_SERVICE_METHODS], this._tracer);
+        void this.restartInactivityTimer();
+    }
+    getLogger() {
+        return this._logger;
     }
     setSyncCallback(callback) {
         this.syncCallback = callback;
     }
+    setWaitForGenerationCompleteCallback(callback) {
+        this.waitForGenerationCompleteCallback = callback;
+    }
+    /**
+     * Called when a gateway peer's liveness expires without a clean close.
+     *
+     * Half-open TCP leaves the socket map entry and the headless turn binding
+     * in place until something else tears them down. The lock already stops
+     * protecting the sandbox here; this hook lets the turn router release the
+     * same peer so Clark stops targeting a dead gateway.
+     */
+    setOnGatewayLivenessLapsed(callback) {
+        this.onGatewayLivenessLapsed = callback;
+    }
+    /**
+     * Called when a client attached and somebody else already holds the lock.
+     *
+     * What a conflict means is the host's to decide, not this service's: a CLI
+     * with a person at it can describe the holder and offer a takeover, a
+     * sandbox can only write it down. This is the hook that used to be the
+     * `ConflictError` catch around the boot-time acquire.
+     */
+    setOnLockConflict(callback) {
+        this.onLockConflict = callback;
+    }
     get status() {
         return this._status;
     }
     set status(status) {
         if (this._status !== status) {
             this._status = status;
+            if (status === LockServiceStatus.LOCKED) {
+                // Derived from the transition rather than set by each of the three
+                // places that can obtain a lock, so it cannot be forgotten in one.
+                this._lockGivenUp = false;
+            }
             this.emit("statusChange", status);
         }
     }
@@ -85,110 +189,565 @@ export class LockService extends EventEmitter {
     get lockId() {
         return this._lockId;
     }
+    get currentBranchName() {
+        return this.branchName;
+    }
     get connectedUsers() {
-        return Array.from(this._connectedUserPeerIdsMap.keys());
+        return this._activityTracker.connectedUsers;
+    }
+    get isRestarting() {
+        return this._isRestarting;
+    }
+    get wasRecentlyActive() {
+        return this._activityTracker.wasRecentlyActive;
+    }
+    get timeSinceLastActivity() {
+        return this._activityTracker.timeSinceLastActivity;
+    }
+    /** Whether any client — a browser editor or a headless gateway peer — is here. */
+    get hasAttachedClient() {
+        return (this._activityTracker.connectedUsers.length > 0 ||
+            this.hasAttachedGatewayPeer);
+    }
+    /**
+     * A client attached and this pod has never held the lock: take it for them.
+     *
+     * The lock is a mutual-exclusion marker between clients, not a capability the
+     * pod needs in order to serve — no write path on either side gates on holding
+     * it. So it belongs to whoever is attached, and a pod that grabs it at boot
+     * only invents a state nobody wants: a lock held on behalf of nobody, which
+     * then needs a watchdog to clean up. Claiming it on attach makes that state
+     * unreachable instead.
+     *
+     * Deliberately narrower than {@link reclaimLockForActiveClient}: neither a
+     * lock this pod handed back nor one it was refused is taken here. A tab left
+     * open reconnects its socket on its own, so an attach is no evidence its user
+     * came back, and treating it as evidence would hand the app to somebody who
+     * walked away (APPS-4840).
+     */
+    claimLockForFirstClient() {
+        // `IDLE` on its own does not mean "never held". Several paths reset the
+        // status to it after a lock we did hold went away — a heartbeat grab that
+        // misses, a branch switch, a failed release — so trusting the status alone
+        // would turn a lock we handed back into a claimable one, and a tab that
+        // reconnects by itself would take the app back from whoever is using it.
+        if (this._lockGivenUp) {
+            return;
+        }
+        this.acquireLockForAttachedClient([LockServiceStatus.IDLE]);
+    }
+    /**
+     * The client proved it is still there: take the lock if we do not have it.
+     *
+     * Driven by editor activity pings and by a gateway peer starting a turn —
+     * both are a client doing something, which is the evidence a lock we are not
+     * holding needs before it is worth asking for again.
+     *
+     * That includes a lock we were refused. A refusal is what happened to one
+     * attempt, not a mode this pod is stuck in: the other session ends, and the
+     * user sitting here still wants to edit. Without this a pod that lost one
+     * race could never take the lock again for the rest of its life — and since
+     * SABS hands running pods to the next caller, it would go on failing for
+     * people who had nothing to do with the race.
+     */
+    reclaimLockForActiveClient() {
+        // Editors only. A gateway's route to the lock is {@link acquireLockForTurn}
+        // — an attached gateway peer is a socket, not a turn, and taking the lock
+        // for one would hold write access across the gap between prompts.
+        if (this._closedByServer ||
+            this._activityTracker.connectedUsers.length === 0) {
+            return;
+        }
+        this.acquireLockForAttachedClient([
+            LockServiceStatus.IDLE,
+            LockServiceStatus.LOCK_RELEASED,
+            LockServiceStatus.FAILED_TO_ACQUIRE_LOCK,
+        ]);
+    }
+    /**
+     * Fire-and-forget by design: the sockets, pings and branch switches that ask
+     * for this have nothing to do with the answer.
+     *
+     * What keeps a retry from becoming a stream of 409s is the trigger, not the
+     * status: the only thing that asks repeatedly is the editor's activity ping,
+     * which the pod acts on solely while the user is genuinely active. A blocked
+     * session asks about as often as a held lock heartbeats; one nobody is
+     * sitting at goes quiet on its own.
+     */
+    acquireLockForAttachedClient(from) {
+        if (this._clientLockAcquisition || !this.hasAttachedClient) {
+            return;
+        }
+        if (!from.includes(this._status)) {
+            return;
+        }
+        // Only the first refusal is news. The host's handler can prompt on stdin,
+        // so reporting each retry would be a prompt every ping.
+        const alreadyRefused = this._status === LockServiceStatus.FAILED_TO_ACQUIRE_LOCK;
+        if (!alreadyRefused) {
+            this.getLogger().info(`[lock-service] client attached with no lock held, acquiring (appId=${this.applicationId})`);
+        }
+        // Track the queued operation immediately so a lock-state evaluation cannot
+        // slip in before the queue starts it. `acquireLock` tracks the RPC itself as
+        // well, which covers callers that do not use this attach path.
+        void this.trackAcquisition(this._lockOperationQueue.enqueue(async () => {
+            if (!this.hasAttachedClient || !from.includes(this._status)) {
+                return;
+            }
+            await this.acquireLock();
+        })).catch((error) => alreadyRefused ? undefined : this.reportLockConflict(error));
     }
     /**
-     * Acquire a lock on the specified application and branch
+     * Record an acquisition so anything that settles can see it.
+     *
+     * Every source goes through here — a client attaching, an activity ping, a
+     * force takeover, the reacquire after a heartbeat grab misses, a branch
+     * switch. Tracking only the attach path left the others invisible:
+     * `isLockedWhenSettled` would answer "no lock" for one that was an rpc away
+     * from landing, and `relinquishLock` would find nothing to release and let
+     * the lock land on a pod that had already gone.
+     *
+     * What is stored is a swallowed copy. Callers of
+     * {@link settleClientLockAcquisition} only want the state to have stopped
+     * moving; a rejection surfacing as theirs would turn a refused lock into a
+     * failed disconnect. The promise handed back keeps its rejection for whoever
+     * asked for the lock.
      */
-    async acquireLock() {
+    trackAcquisition(acquisition) {
+        const tracked = acquisition
+            .catch(() => undefined)
+            .finally(() => {
+            if (this._clientLockAcquisition === tracked) {
+                this._clientLockAcquisition = undefined;
+            }
+        });
+        this._clientLockAcquisition = tracked;
+        return acquisition;
+    }
+    /**
+     * Wait for an acquisition a client attach kicked off, if one is in flight.
+     *
+     * Anything that decides what to do about the lock has to do this first, or it
+     * decides on a half-known state. While the RPC is out `isLocked` is false and
+     * `_lockId` is unset, so a disconnect would "release" nothing and the lock
+     * would land moments later with nobody left to hold it for — and a branch
+     * switch would move on and leave it attached to the branch it came from.
+     *
+     * Never rejects: the acquisition's own catch has already handled failure.
+     */
+    async settleClientLockAcquisition() {
+        await this._clientLockAcquisition;
+    }
+    /**
+     * Whether this pod holds the lock after attach and queued turn operations
+     * already in flight have settled. The synchronous getter remains the current
+     * state for status reporting.
+     */
+    async isLockedWhenSettled() {
+        await this.settleClientLockAcquisition();
+        return await this._lockOperationQueue.enqueue(async () => this.isLocked);
+    }
+    /**
+     * Nothing is awaiting the acquisition a client triggers, so this is where a
+     * failure stops: swallowing it here is what keeps a conflict from surfacing
+     * as an unhandled rejection. `acquireLock` has already logged it and moved
+     * the status to `FAILED_TO_ACQUIRE_LOCK`; the host is told separately because
+     * only it knows whether there is anyone to tell.
+     */
+    async reportLockConflict(error) {
+        if (!(error instanceof ConflictError) || !this.onLockConflict) {
+            return;
+        }
+        try {
+            await this.onLockConflict(error);
+        }
+        catch (handlerError) {
+            this.getLogger().warn(`[lock-service] onLockConflict threw; continuing (appId=${this.applicationId})`, getErrorMeta(handlerError));
+        }
+    }
+    /**
+     * Serializes branch changes with lock acquisition and handback. Omitting
+     * `reacquireLock` preserves the lock state observed inside that operation.
+     */
+    async switchBranch(nextBranchName, options) {
+        // Git activation runs off the same socket connect that starts an
+        // acquisition, so the switch really can arrive while one is out.
+        await this.settleClientLockAcquisition();
+        await this._lockOperationQueue.enqueue(() => this.switchBranchNow(nextBranchName, options));
+    }
+    async switchBranchNow(nextBranchName, options) {
+        if (this.branchName === nextBranchName) {
+            return;
+        }
+        const previousBranchName = this.branchName;
+        const lockIdBeforeSwitch = this._lockId;
+        const reacquireLock = options?.reacquireLock ?? this.isLocked;
+        if (reacquireLock && this.isLocked && lockIdBeforeSwitch) {
+            this.stopHeartbeat();
+            try {
+                const lockResponse = await this._rpcClient.call(async (client) => {
+                    return unwrapResponseDto(client.call.v3.lock.transfer({
+                        applicationId: this.applicationId,
+                        fromBranchName: previousBranchName,
+                        toBranchName: nextBranchName,
+                        lockId: lockIdBeforeSwitch,
+                    }));
+                });
+                const transferredLock = lockResponse.appBranchLock[0];
+                if (!transferredLock) {
+                    throw new Error(`[lock-service] lock transfer returned no lock for branch switch '${previousBranchName}' -> '${nextBranchName}'`);
+                }
+                this.branchName = nextBranchName;
+                this._lockId = transferredLock.lockId;
+                this.status = LockServiceStatus.LOCKED;
+                this.getLogger().info(`[lock-service] atomically transferred lock branch context from '${previousBranchName}' to '${nextBranchName}'`);
+                void this.scheduleNextHeartbeat();
+                return;
+            }
+            catch (error) {
+                // Preserve lock liveness when transfer fails: we still hold the original
+                // lock and must resume heartbeat to avoid silent lock expiration.
+                if (this.isLocked && this._lockId === lockIdBeforeSwitch) {
+                    this.getLogger().warn(`[lock-service] lock transfer failed, resuming heartbeat on original lock '${lockIdBeforeSwitch}'`);
+                    void this.scheduleNextHeartbeat();
+                }
+                throw error;
+            }
+        }
+        if (this.isLocked) {
+            await this.releaseLock();
+        }
+        else {
+            this.stopHeartbeat();
+            this._lockId = undefined;
+            if (this.status !== LockServiceStatus.FAILED_TO_ACQUIRE_LOCK) {
+                this.status = LockServiceStatus.IDLE;
+            }
+        }
+        this.branchName = nextBranchName;
+        this.getLogger().info(`[lock-service] switched branch context from '${previousBranchName}' to '${nextBranchName}'`);
+        if (reacquireLock) {
+            await this.acquireLock();
+        }
+    }
+    /**
+     * Acquire a lock on the specified application and branch.
+     *
+     * Not `async`: the body has to start and be registered in the same tick, so
+     * a caller that immediately settles sees this acquisition rather than
+     * missing it by a microtask.
+     */
+    acquireLock() {
+        return this.trackAcquisition(this.acquireLockImpl());
+    }
+    async acquireLockImpl() {
         this.status = LockServiceStatus.ACQUIRING;
-        const logger = getLogger();
+        // Stop any existing heartbeat before acquiring a new lock to prevent duplicate heartbeat loops
+        this.stopHeartbeat();
         try {
-            const rpcClient = await this.getRpcClient();
-            const lockResponse = await unwrapResponseDto(rpcClient.call.v3.lock.acquire({
-                applicationId: this.applicationId,
-                branchName: this.branchName,
-                sessionType: this.lockType,
-            }));
+            const lockResponse = await this._rpcClient.call(async (client) => {
+                return unwrapResponseDto(client.call.v3.lock.acquire({
+                    applicationId: this.applicationId,
+                    branchName: this.branchName,
+                    sessionType: this.lockType,
+                }));
+            });
+            // Currently lock response only returns one lock
             if (lockResponse.appBranchLock[0]) {
                 const lock = lockResponse.appBranchLock[0];
                 this._lockId = lock.lockId;
+                this.getLogger().info(`[lock-service] lock acquired: ${this._lockId}`);
                 this.status = LockServiceStatus.LOCKED;
+                this._heartbeatStoppedForIdle = false;
                 this.emit("lockAcquired", this._lockId);
-                this.scheduleNextHeartbeat();
+                void this.scheduleNextHeartbeat();
                 return;
             }
+            // A response carrying no lock is not success. Falling through would leave
+            // the status in ACQUIRING, which is what the catch below exists to avoid.
+            throw new Error("lock acquire returned no lock");
         }
         catch (error) {
+            // Whatever went wrong, this attempt is over and the lock is not held.
+            // Leaving ACQUIRING behind would be a lie the retry paths cannot see past:
+            // it is in neither the claim nor the reclaim set, so a single transient
+            // failure would stop this pod ever taking the lock again.
+            this.status = LockServiceStatus.FAILED_TO_ACQUIRE_LOCK;
             if (error instanceof ConflictError) {
-                logger.error(`[lock-service] Lock is already acquired by another user. Please try again later.`, getErrorMeta(error));
+                this.getLogger().error(`[lock-service] ${error.message}`);
                 this.emit("statusChange", LockServiceStatus.FAILED_TO_ACQUIRE_LOCK);
-                this.status = LockServiceStatus.FAILED_TO_ACQUIRE_LOCK;
-                await this.shutdown();
-                throw new Error(`${error}`);
+                // Deliberately no further teardown. The lock was never held, so there is
+                // nothing to release, and the `shutdown` that used to be here only
+                // closed the rpc client — leaving a pod bound to its port with no way
+                // to reach the server, which is the zombie state. The error goes to the
+                // caller, which owns what happens to the process.
+                throw error;
             }
             else {
                 throw new Error(`${error}. Please try again later.`);
             }
         }
     }
+    /**
+     * Take write access for a turn that is about to start.
+     *
+     * The lock is permission to write for one turn, not a lease on the session: a
+     * headless turn takes it on the way in and hands it back when it ends, so the
+     * app sits unlocked between prompts and a person can open it in the editor.
+     *
+     * Deliberately not routed through {@link claimLockForFirstClient} or
+     * {@link reclaimLockForActiveClient}. Those weigh up whether a signal is
+     * evidence of a client that wants the lock; a turn starting is not evidence
+     * of that, it *is* that, so it asks directly and a lock we handed back
+     * earlier is taken again without ceremony.
+     *
+     * Unlike an attach, this is awaited and its failure is the caller's: a turn
+     * that cannot write must fail before routing is bound, carrying the server's
+     * own reason. Failing does not take the pod down — the lock is per app+branch
+     * while a pod is per live edit, so somebody editing in the browser says
+     * nothing about whether this pod can serve the turn after them.
+     */
+    async acquireLockForTurn() {
+        await this.settleClientLockAcquisition();
+        await this._lockOperationQueue.enqueue(async () => {
+            if (!this.isLocked) {
+                await this.acquireLock();
+            }
+        });
+    }
+    /**
+     * Hand back the write access a turn took, once that turn has finished.
+     *
+     * The wait belongs here rather than in the callers. A turn ends in more than
+     * one way — the gateway releases it, its socket drops, its liveness lapses —
+     * and only the first of those arrives with the generation already complete.
+     * The other two reach this while Clark may still be writing, and handing the
+     * lock back there gives write access away mid-generation.
+     *
+     * Before the queue, never inside it, for the reason spelled out on
+     * {@link handBackTurnLockWhenGenerationSettles}: that queue serialises the
+     * handback, branch switches and the next turn's acquisition, so a wait
+     * inside it lets one hung turn stall all of them.
+     *
+     * `isStillNeeded` is re-read after that wait, because waiting is exactly
+     * what makes the caller's decision stale: a replacement gateway can attach
+     * and take a turn while the old one's generation is finishing, and releasing
+     * then would pull write access out from under it. The caller owns the
+     * question — this cannot ask "is a gateway attached?" itself, since the
+     * explicit `editor.releaseTurnLock` path runs with one attached by
+     * definition.
+     */
+    async relinquishLockForTurn(isStillNeeded) {
+        await this.waitForGenerationCompleteCallback?.();
+        await this._lockOperationQueue.enqueue(async () => {
+            if (!this.isLocked ||
+                this._activityTracker.connectedUsers.length > 0 ||
+                isStillNeeded?.()) {
+                return;
+            }
+            await this.relinquishLockNow(() => this._activityTracker.connectedUsers.length > 0 ||
+                (isStillNeeded?.() ?? false));
+        });
+    }
     /**
      * Release the currently held lock
      */
     async releaseLock() {
-        const logger = getLogger();
         if (this._status !== LockServiceStatus.LOCKED) {
             return false;
         }
+        this._lockGivenUp = true;
         this.status = LockServiceStatus.RELEASING;
         this.emit("statusChange", LockServiceStatus.RELEASING);
+        // Stop heartbeat immediately and clear local lock id first to prevent any
+        // in-flight grab calls from using a stale lock id during branch switching.
+        this.stopHeartbeat();
+        const lockIdToRelease = this._lockId;
+        this._lockId = undefined;
         try {
+            if (!lockIdToRelease) {
+                this.status = LockServiceStatus.LOCK_RELEASED;
+                this.emit("statusChange", LockServiceStatus.LOCK_RELEASED);
+                return true;
+            }
             // Try to release the lock when this class is destructed
-            const rpcClient = await this.getRpcClient();
-            await unwrapResponseDto(rpcClient.call.v3.lock.release({
-                applicationId: this.applicationId,
-                branchName: this.branchName,
-                lockId: this._lockId,
-            }));
-            this._lockId = undefined;
+            await this._rpcClient.call(async (client) => {
+                await unwrapResponseDto(client.call.v3.lock.release({
+                    applicationId: this.applicationId,
+                    branchName: this.branchName,
+                    lockId: lockIdToRelease,
+                }));
+            });
             this.status = LockServiceStatus.LOCK_RELEASED;
             this.emit("statusChange", LockServiceStatus.LOCK_RELEASED);
-            logger.info("[lock-service] lock released");
+            this.getLogger().info("[lock-service] lock released");
             return true;
         }
         catch (error) {
+            if (error instanceof NotFoundError) {
+                this.status = LockServiceStatus.LOCK_RELEASED;
+                this.emit("statusChange", LockServiceStatus.LOCK_RELEASED);
+                this.getLogger().warn("[lock-service] lock already released on server");
+                return true;
+            }
             this.status = LockServiceStatus.IDLE;
-            logger.error("[lock-service] error releasing lock", getErrorMeta(error));
+            this.getLogger().error("[lock-service] error releasing lock", getErrorMeta(error));
             throw error;
         }
         finally {
             this.stopHeartbeat();
+            // Clear any pending buffer or inactivity timeouts since lock is being released
+            if (this._bufferPeriodTimeout) {
+                clearTimeout(this._bufferPeriodTimeout);
+                this._bufferPeriodTimeout = undefined;
+            }
+            if (this._inactivityTimeout) {
+                clearTimeout(this._inactivityTimeout);
+                this._inactivityTimeout = undefined;
+            }
         }
     }
-    async checkAndUpdateLockIfPossible() {
-        const logger = getLogger();
+    async grabLockImpl() {
         if (this._lockId) {
-            try {
-                const rpcClient = await this.getRpcClient();
-                const response = await unwrapResponseDto(rpcClient.call.v3.lock.grab({
+            const lockResponse = await this._rpcClient.call(async (client) => {
+                return unwrapResponseDto(client.call.v3.lock.grab({
                     applicationId: this.applicationId,
                     branchName: this.branchName,
                     lockId: this._lockId,
                 }));
+            });
+            return lockResponse;
+        }
+        return null;
+    }
+    /**
+     * Inspect lock information for the current application and branch
+     */
+    async inspectLock() {
+        const lockInfo = await this._rpcClient.call(async (client) => {
+            return unwrapResponseDto(client.call.v3.lock.inspect({
+                applicationId: this.applicationId,
+                branchName: this.branchName,
+            }));
+        });
+        return lockInfo;
+    }
+    /**
+     * Force takeover of the lock from another user (only allowed when user is inactive)
+     */
+    forceTakeover() {
+        return this.trackAcquisition(this.forceTakeoverImpl());
+    }
+    async forceTakeoverImpl() {
+        this.status = LockServiceStatus.ACQUIRING;
+        try {
+            const lockResponse = await this._rpcClient.call(async (client) => {
+                return unwrapResponseDto(client.call.v3.lock.forceTake({
+                    applicationId: this.applicationId,
+                    branchName: this.branchName,
+                    sessionType: this.lockType,
+                }));
+            });
+            // Currently lock response only returns one lock
+            if (lockResponse.appBranchLock[0]) {
+                const lock = lockResponse.appBranchLock[0];
+                this._lockId = lock.lockId;
+                this.getLogger().info(`[lock-service] lock acquired via force takeover: ${this._lockId}`);
+                this.status = LockServiceStatus.LOCKED;
+                this.emit("lockAcquired", this._lockId);
+                void this.scheduleNextHeartbeat();
+                return;
+            }
+            // As in `acquireLock`: a response carrying no lock is not success.
+            // Falling through would leave the status in ACQUIRING, which belongs to
+            // neither the claim set nor the reclaim set — so nothing would ever try
+            // again and the pod would sit there unable to edit.
+            throw new Error("lock force takeover returned no lock");
+        }
+        catch (error) {
+            this.getLogger().error(`[lock-service] ${getErrorMeta(error).error.message}`);
+            this.status = LockServiceStatus.FAILED_TO_ACQUIRE_LOCK;
+            throw error;
+        }
+    }
+    async checkAndUpdateLockIfPossible() {
+        const baseRetryMs = 1000;
+        const maxAttempts = 5;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const response = await this.grabLockImpl();
                 if (response?.appBranchLock?.[0]) {
-                    // If the csb lock is overridden by dev, the lock will be released
-                    // TODO(David): Implement the status update to the user where CSB users needs to save their work
-                    logger.info(`[lock-service] lock is still valid with expiration timestamp: ${response.appBranchLock[0].expirationTimestamp}`);
+                    const returnedLock = response.appBranchLock[0];
+                    if (returnedLock.sessionType &&
+                        returnedLock.sessionType !== this.lockType) {
+                        this.getLogger().warn(`[lock-service] lock fallback returned mismatched session type (${returnedLock.sessionType}) for expected ${this.lockType}; ignoring fallback lock`);
+                        throw new NotFoundError("Lock not found");
+                    }
+                    if (returnedLock.lockId && returnedLock.lockId !== this._lockId) {
+                        this.getLogger().info(`[lock-service] lock ID changed from ${this._lockId} to ${returnedLock.lockId} (cross-branch transfer)`);
+                        this._lockId = returnedLock.lockId;
+                    }
+                    this.getLogger().info(`[lock-service] lock is still valid with expiration timestamp: ${returnedLock.expirationTimestamp}`);
                     return true;
                 }
             }
             catch (error) {
-                if (error instanceof ConflictError) {
-                    logger.error("[lock-service] Lock has been overridden by another user", getErrorMeta(error));
-                    this.emit("statusChange", LockServiceStatus.LOCK_INVALID);
-                    this.status = LockServiceStatus.LOCK_INVALID;
-                    await this.shutdownAndExit();
+                if (error instanceof NotFoundError) {
+                    this.getLogger().warn("[lock-service] lock not found during heartbeat grab, attempting to reacquire before shutdown");
+                    this.stopHeartbeat();
+                    this._lockId = undefined;
+                    this.status = LockServiceStatus.IDLE;
+                    // Only take it back if we still wanted it, and only for somebody.
+                    //
+                    // A grab left over from before a release lands after the lock is
+                    // already gone on purpose — acquiring fires a heartbeat immediately,
+                    // so that overlap is the norm on the attach-and-drop path rather than
+                    // a rare coincidence. Reacquiring there takes back a lock we chose to
+                    // give up, either for nobody at all or for a tab that has merely
+                    // reconnected, which is the app being held away from whoever is
+                    // actually using it (APPS-4840). A released lock is taken back by an
+                    // activity ping, never from here.
+                    if (this._lockGivenUp || !this.hasAttachedClient) {
+                        this.getLogger().info(`[lock-service] lock lost during heartbeat grab with nothing to take it back for, leaving it (appId=${this.applicationId})`);
+                        return false;
+                    }
+                    try {
+                        await this.acquireLock();
+                        this.getLogger().info("[lock-service] lock reacquired after heartbeat grab miss");
+                        return true;
+                    }
+                    catch (reacquireError) {
+                        if (reacquireError instanceof ConflictError) {
+                            const message = "⚠️  Edit access lost – another user has taken over this branch. Shutting down server.";
+                            if (process.env.SUPERBLOCKS_VSCODE === "true") {
+                                this.getLogger().error(`clierr: ${JSON.stringify({ message })}`);
+                            }
+                            else {
+                                this.getLogger().error(message);
+                            }
+                            this.emit("statusChange", LockServiceStatus.LOCK_INVALID);
+                            this.status = LockServiceStatus.LOCK_INVALID;
+                            await this.shutdownAndExit();
+                            return false;
+                        }
+                        if (attempt < maxAttempts) {
+                            const delayMs = baseRetryMs * 2 ** (attempt - 1);
+                            this.getLogger().warn(`[lock-service] lock reacquire attempt ${attempt} failed with error: ${getErrorMeta(reacquireError).error.message}, retrying in ${delayMs}ms...`);
+                            await new Promise((resolve) => setTimeout(resolve, delayMs));
+                            continue;
+                        }
+                        throw reacquireError;
+                    }
                 }
-                else if (error instanceof NotFoundError) {
-                    logger.error("[lock-service] Lock is not found, shutting down", getErrorMeta(error));
-                    this.emit("statusChange", LockServiceStatus.LOCK_INVALID);
-                    this.status = LockServiceStatus.LOCK_INVALID;
-                    await this.shutdownAndExit();
-                }
-                else {
-                    logger.error("[lock-service] error checking and updating lock", getErrorMeta(error));
+                if (attempt < maxAttempts) {
+                    const delayMs = baseRetryMs * 2 ** (attempt - 1);
+                    this.getLogger().warn(`[lock-service] Attempt ${attempt} failed with error: ${getErrorMeta(error).error.message}, retrying in ${delayMs}ms...`);
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                    continue;
                 }
+                this.getLogger().error("[lock-service] error checking and updating lock", getErrorMeta(error));
+                this.status = LockServiceStatus.IDLE;
+                this.stopHeartbeat();
                 throw error;
             }
         }
@@ -197,70 +756,309 @@ export class LockService extends EventEmitter {
         return false;
     }
     /**
-     * Cleanup method to be called when the class is destroyed
-     * This ensures the lock is released
+     * Make sure this pod holds the lock a write is about to need.
+     *
+     * The write is itself the demand for the lock, which is what separates this
+     * from the heartbeat's check above. That one asks whether a lock we already
+     * hold is still there, and answers for a lock id; this one is asked before a
+     * sync, when there may be no lock at all.
+     *
+     * The distinction is load-bearing at boot. Nothing acquires the lock at
+     * startup any more — a client attaching is what claims it — but the dev
+     * server still uploads the user's local files before any editor connects.
+     * With no lock id {@link checkAndUpdateLockIfPossible} skips the grab
+     * entirely and reports false without ever asking the server, so routing that
+     * upload through it failed the sync and took the dev server down with it.
+     *
+     * A lock this session handed back is still not taken back here: a write
+     * queued before the handback belongs to the session that ended.
      */
-    async shutdown() {
-        const logger = getLogger();
-        // Perform one last sync using the sync callback if it is set
-        if (this.syncCallback && this.isLocked) {
-            // If the lock is still valid, then we can perform one last sync
-            await this.syncCallback();
+    async ensureLockForWrite() {
+        await this.settleClientLockAcquisition();
+        if (this._lockId) {
+            const held = await this.checkAndUpdateLockIfPossible();
+            // The last write of a session that is ending is not gated on still
+            // holding the lock. By the time the server closes a session the other
+            // one has usually taken the lock already, so the grab above misses and
+            // the answer is "no" — which would drop whatever the editor had not
+            // synced yet, and make the flush that runs at exactly this moment dead
+            // code, since it could never succeed.
+            //
+            // Writing anyway is safe in the way that matters: the lock is a
+            // mutual-exclusion marker between clients, not something the server
+            // enforces on writes, and the session being handed to on a local<->cloud
+            // switch belongs to the same user whose edits these are.
+            return held || this._flushingFinalWork;
         }
-        else {
-            logger.info("[lock-service] no sync callback because lock is not valid anymore");
+        if (this._lockGivenUp) {
+            this.getLogger().info(`[lock-service] write wants a lock this session handed back, leaving it (appId=${this.applicationId})`);
+            return false;
+        }
+        // Read before the attempt, because a refusal is what moves the status
+        // there: only the first one is news.
+        const alreadyRefused = this._status === LockServiceStatus.FAILED_TO_ACQUIRE_LOCK;
+        try {
+            await this.trackAcquisition(this._lockOperationQueue.enqueue(async () => {
+                // Re-read inside the queue: an attach or a handback can have landed
+                // while this waited its turn.
+                if (this._lockId || this._lockGivenUp) {
+                    return;
+                }
+                await this.acquireLock();
+            }));
+        }
+        catch (error) {
+            // A refusal is the other session's answer, not a failure of this write.
+            if (!(error instanceof ConflictError)) {
+                throw error;
+            }
+            // The host is told because only it knows whether there is anyone to
+            // tell — and told once. Its handler can prompt on stdin or hand the
+            // session to the VS Code extension, so reporting every autosave that
+            // runs into the same held lock is a prompt per save.
+            if (!alreadyRefused) {
+                await this.reportLockConflict(error);
+            }
+        }
+        // Not `false` on the conflict path: that handler can take the lock, as the
+        // CLI's does for one whose owner has gone inactive. Whether this write may
+        // go ahead is whether the lock is held now, however it was come by.
+        //
+        // Arming applies to both outcomes for the same reason: a lock taken here
+        // was taken for a write, not for a client, and nothing else will ask
+        // whether it has gone idle.
+        this.ensureIdleEvaluationArmed();
+        return this.isLocked;
+    }
+    /**
+     * Flush what this client left behind and hand the lock back.
+     *
+     * The only way to give the lock up, and the whole of what this service does
+     * about a session ending. Whether the process then stops is the caller's
+     * business and this cannot tell: the same call serves a tab closing on a
+     * sandbox that keeps serving, a `superblocks dev` the user is quitting, and
+     * every exit path in `dev()`. So it says nothing about the server's fate —
+     * that used to be `shutdown()`'s job, and a lock service asserting a process
+     * was exiting is precisely the tangle that made a lock release look like a
+     * teardown.
+     *
+     * Releasing the lock and stopping the dev server used to be one action, so a
+     * client going away took the sandbox with it. On the cloud path it did not
+     * even stop — it closed the rpc client and returned, leaving a pod still
+     * bound to its port with no lock, no heartbeat and nothing behind it: healthy
+     * to every probe and unable to do anything. SABS hands such a pod straight
+     * back to the next caller, whose requests then go nowhere.
+     *
+     * Where the pod does stay up, reopening is cheap for the same reason keeping
+     * it was worth it: Vite is still running, packages are installed, files are
+     * downloaded. A returning editor reacquires through
+     * {@link restartInactivityTimer}.
+     */
+    async relinquishLock() {
+        // Settle first, for the same reason `switchBranch` and `evaluateLockState`
+        // do. The attach-time acquisition is awaited by nobody, so an exit can land
+        // on top of one: `releaseLock` no-ops while the status is ACQUIRING, the
+        // pod leaves having released nothing, and the lock the acquire then lands
+        // is held until the server-side TTL - blocking the replacement sandbox,
+        // which is the whole reason the exit paths release promptly at all.
+        await this.settleClientLockAcquisition();
+        await this._lockOperationQueue.enqueue(() => this.relinquishLockNow());
+    }
+    async relinquishLockNow(shouldRetainLock) {
+        await this.flushPendingWork("handing the lock back");
+        if (shouldRetainLock?.()) {
+            return;
         }
+        const released = await this.releaseLock();
+        // `releaseLock` answers false without doing anything when there was no lock
+        // to give back. Saying "handed back" regardless tells oncall the
+        // server-side lock is clear when it may not be, which is the wrong
+        // direction to send someone chasing a stuck sandbox.
+        this.getLogger().info(released
+            ? `[lock-service] lock handed back (appId=${this.applicationId})`
+            : `[lock-service] no lock to hand back (status=${this._status}, appId=${this.applicationId})`);
+    }
+    /**
+     * The server closed this session: tell the editor, flush, and stop
+     * heartbeating — but do not release.
+     *
+     * The lock is already gone. `/_sb_disconnect` is the server saying it has
+     * taken it, typically to hand the app to a session moving the other way
+     * across local↔cloud, so releasing from here would give back something that
+     * is not ours; on a switch it belongs to whoever is taking over. What is
+     * still ours is the heartbeat, which would otherwise keep refreshing a lock
+     * the server reassigned.
+     *
+     * The editor needs both halves of {@link EventMap.closedByServer}: it has to
+     * distinguish "the server closed you" from a socket dropping, and a switch
+     * from an ending.
+     */
+    async notifyClosedByServer({ switchingTo, initiatedByEmail, }) {
+        this.emit("closedByServer", { initiatedByEmail, switchingTo });
+        this._closedByServer = true;
+        // Record that the lock is no longer ours before anything can act on it
+        // being missing. This is the same fact `releaseLock` records, arrived at
+        // from the other direction — there we gave it up, here it was taken — and
+        // the three places that ask are already written against it: a bare attach
+        // must not claim, a grab that misses must not reacquire, and a rejected
+        // heartbeat must not be read as losing a lock we still wanted.
+        //
+        // Without it, each of those fights the session taking over on a local↔cloud
+        // switch: the reacquire takes the app straight back off them, and the
+        // heartbeat path ends this process mid-`/_sb_disconnect`, before the
+        // response is sent. Stopping the heartbeat below is not enough on its own
+        // — a grab already in flight is not cancelled by clearing a timer.
+        this._lockGivenUp = true;
+        // Before the flush, not after it. Every refresh from here on is against
+        // something we do not hold, and the flush can take as long as the unsynced
+        // work does — which is the window one of those refreshes comes back
+        // rejected in.
         this.stopHeartbeat();
-        if (this.isLocked) {
-            await this.releaseLock();
+        this.clearGatewayLivenessSweep();
+        await this.flushPendingWork("the server closed this session");
+    }
+    /**
+     * Push whatever the editor has not synced yet.
+     *
+     * Both ways of giving a session up run this first, and neither can be held up
+     * by it: the caller is either handing the lock to the next client or on its
+     * way out of the process, and a sync that fails is strictly better than one
+     * that blocks the handover. An unheld lock means nothing to flush — the files
+     * belong to whoever holds it now.
+     */
+    async flushPendingWork(reason) {
+        if (!this.syncCallback || !this.isLocked) {
+            return;
+        }
+        this.getLogger().info(`[lock-service] performing a final sync before ${reason}`);
+        // Tells {@link ensureLockForWrite} that the upload it is about to gate is
+        // this flush, which writes on the way out whether or not the lock is still
+        // ours.
+        this._flushingFinalWork = true;
+        try {
+            await this.syncCallback();
+        }
+        catch (error) {
+            this.getLogger().error(`[lock-service] sync failed before ${reason}, continuing anyway`, getErrorMeta(error));
+        }
+        finally {
+            this._flushingFinalWork = false;
         }
-        await this.closeRpcClient();
-        logger.info("[lock-service] shutting down and exiting dev server");
     }
     /**
-     * Shutdown the lock service and exit the dev server
+     * Hand the lock back and end the process.
+     *
+     * The only method here that ends anything, and it exists for the four callers
+     * inside this service that have already decided the pod cannot continue: a
+     * heartbeat that failed, a reacquire lost to another user, and the two
+     * {@link LockType.LOCAL} disconnect branches, where the dev server is the
+     * user's foreground process and they expect their terminal back.
+     *
+     * Callers outside this service drive {@link relinquishLock} and own their own
+     * exit. That is not a style preference: `process.exit` is synchronous, so
+     * folding it in here makes everything a caller sequences after it dead code —
+     * which is exactly how the fatal-exit paths in `dev()` came to skip their
+     * telemetry flush on every pod that had a lock service.
+     *
+     * The release is best effort and the exit is not. A lock left held TTL-expires
+     * in two minutes, the same as any pod that dies; a process that fails to exit
+     * is a zombie until something reaps it.
      */
     async shutdownAndExit() {
-        await this.shutdown();
-        process.exit(1);
+        try {
+            await this.relinquishLock();
+        }
+        catch (error) {
+            this.getLogger().error("[lock-service] failed to hand the lock back, exiting anyway", getErrorMeta(error));
+        }
+        finally {
+            process.exit(1);
+        }
     }
     /**
-     * Add a connected user to the lock service.
+     * Add a connected user to the activity tracker.
      */
     addConnectedPeerIdToUser(userId, peerId) {
-        if (!this._connectedUserPeerIdsMap.has(userId)) {
-            this._connectedUserPeerIdsMap.set(userId, new Set([peerId]));
+        this._activityTracker.addConnectedPeerIdToUser(userId, peerId);
+        this._isRestarting = false;
+        this.claimLockForFirstClient();
+        if (this._bufferPeriodTimeout) {
+            clearTimeout(this._bufferPeriodTimeout);
+            this._bufferPeriodTimeout = undefined;
+            this.getLogger().info("[lock-service] user reconnected, cleared pending buffer period timeout");
         }
-        else {
-            this._connectedUserPeerIdsMap.get(userId)?.add(peerId);
+        this.ensureIdleEvaluationArmed();
+    }
+    /**
+     * Make sure something is still due to ask whether this lock is idle.
+     *
+     * The inactivity timer is one-shot, and the evaluation it fires returns
+     * early on a service that has never held a lock without arming another. So
+     * any path that ends up holding one for something other than an attached
+     * client has to put the question back on the clock, or the lock is refreshed
+     * by the heartbeat for a client that never arrives.
+     */
+    ensureIdleEvaluationArmed() {
+        const alreadyConcludedIdle = this._activityTracker.isReadyForTakeover || this._heartbeatStoppedForIdle;
+        if (this._inactivityTimeout || alreadyConcludedIdle) {
+            return;
         }
-        const logger = getLogger();
-        logger.debug(`[lock-service] added peerId ${peerId} to user ${userId}`);
+        this.scheduleInactivityEvaluation();
+    }
+    evaluateLockStateInBackground(occasion) {
+        void this.evaluateLockState().catch((error) => {
+            this.getLogger().error(`[lock-service] failed to evaluate lock state after ${occasion} (lockId=${this._lockId}, appId=${this.applicationId})`, getErrorMeta(error));
+            this.ensureIdleEvaluationArmed();
+        });
     }
     /**
-     * Remove a connected user from the lock service.
+     * Remove a connected user from the activity tracker.
      */
     removeConnectedPeerIdFromUser(userId, peerId) {
-        const logger = getLogger();
-        if (this._connectedUserPeerIdsMap.has(userId)) {
-            this._connectedUserPeerIdsMap.get(userId)?.delete(peerId);
-            logger.debug(`[lock-service] removed peerId ${peerId} from user ${userId}`);
-        }
-        if (this._connectedUserPeerIdsMap.get(userId)?.size === 0) {
-            this._connectedUserPeerIdsMap.delete(userId);
-            logger.debug(`[lock-service] removed connected user ${userId}`);
+        this._activityTracker.removeConnectedPeerIdFromUser(userId, peerId);
+        if (this._activityTracker.isDisconnected) {
+            this.getLogger().info("[lock-service] all users disconnected, evaluating lock state");
+            this.evaluateLockStateInBackground("the last editor disconnected");
         }
     }
     async scheduleNextHeartbeat() {
-        const logger = getLogger();
+        const generation = ++this._heartbeatGeneration;
         try {
             if (this._status === LockServiceStatus.LOCKED) {
                 await this.sendHeartbeat();
-                this._heartbeatTimeout = setTimeout(() => this.scheduleNextHeartbeat(), this.heartbeatIntervalMs);
+                // If the heartbeat was stopped (e.g. idle takeover) or a newer chain
+                // started while this grab was in flight, do not re-arm — otherwise the
+                // lock would keep refreshing after we intentionally stopped (APPS-4840).
+                if (generation !== this._heartbeatGeneration ||
+                    this._status !== LockServiceStatus.LOCKED) {
+                    return;
+                }
+                // Clear any existing timeout before scheduling new one to prevent duplicate heartbeat loops
+                if (this._heartbeatTimeout) {
+                    clearTimeout(this._heartbeatTimeout);
+                }
+                this._heartbeatTimeout = setTimeout(() => void this.scheduleNextHeartbeat(), this.heartbeatIntervalMs);
+                // This is to avoid the process from staying alive to wait for the heartbeat timeout
+                this._heartbeatTimeout.unref();
             }
         }
         catch (error) {
-            logger.error("[lock-service] Error sending heartbeat, shutting down", getErrorMeta(error));
+            // If the heartbeat was intentionally stopped for idle takeover while this
+            // grab was in flight, a failure here is moot — don't shut the pod down out
+            // from under a user who may still be connected (the lock just TTL-expires).
+            // A genuine heartbeat failure (not an idle stop) still shuts down as before.
+            //
+            // Same for a lock we handed back on purpose. Acquiring fires a heartbeat
+            // immediately, so on the attach-and-drop path a grab is always still out
+            // when the release lands; reading its failure as "we lost a lock we still
+            // wanted" would take a cloud sandbox down for a lock it had already given
+            // up. Neither the status nor the heartbeat generation can be used to tell
+            // the two apart here — `checkAndUpdateLockIfPossible` resets both while
+            // cleaning up after itself, before the error ever reaches this catch.
+            if (this._heartbeatStoppedForIdle || this._lockGivenUp) {
+                return;
+            }
+            this.getLogger().error("[lock-service] Error sending heartbeat, shutting down", getErrorMeta(error));
             this.emit("statusChange", LockServiceStatus.LOCK_INVALID);
             this.status = LockServiceStatus.LOCK_INVALID;
             clearTimeout(this._heartbeatTimeout);
@@ -281,44 +1079,324 @@ export class LockService extends EventEmitter {
      * Stop the heartbeat
      */
     stopHeartbeat() {
-        const logger = getLogger();
+        // Bump the generation so any in-flight scheduleNextHeartbeat() chain bails
+        // out instead of re-arming the heartbeat after we stop.
+        this._heartbeatGeneration++;
         if (this._heartbeatTimeout) {
             clearTimeout(this._heartbeatTimeout);
             this._heartbeatTimeout = undefined;
-            logger.info("[lock-service] heartbeat stopped");
+            this.getLogger().info("[lock-service] heartbeat stopped");
         }
     }
     /**
-     * Start the shutdown timer when no socket connection is detected
+     * Evaluate if the lock should be released (user disconnected) or marked as ready for takeover (user inactive but connected)
      */
-    async startShutdownTimer() {
-        this._shutdownTimeout = setTimeout(() => {
-            this.shutdownAndExit();
-        }, SHUTDOWN_TIMEOUT_MS);
+    async evaluateLockState() {
+        // Single-flight. Several unrelated things ask for an evaluation — a client
+        // disconnecting, the last gateway peer detaching, the inactivity timer —
+        // and the body awaits twice before it decides anything (the acquisition,
+        // then any running generation). The `_bufferPeriodTimeout` guard below is
+        // read before those awaits, so two overlapping callers both saw no timer
+        // and both armed one; the second arming overwrote the first handle, leaving
+        // a timer nothing could cancel. Joining the in-flight evaluation is what
+        // makes the guard mean what it says, and it holds for any await added to
+        // the body later.
+        this._inFlightLockEvaluation ??= this.evaluateLockStateOnce().finally(() => {
+            this._inFlightLockEvaluation = undefined;
+        });
+        return this._inFlightLockEvaluation;
     }
-    async stopShutdownTimerIfNeeded() {
-        const logger = getLogger();
-        if (this._shutdownTimeout) {
-            clearTimeout(this._shutdownTimeout);
-            this._shutdownTimeout = undefined;
-            logger.info("[lock-service] activity detected, shutdown timer stopped");
+    async evaluateLockStateOnce() {
+        // A client can attach and drop again before its lock arrives — the flaky
+        // connect this whole change is downstream of. Deciding now would find
+        // `isLocked` false, release nothing, and leave the lock to land on an empty
+        // sandbox and heartbeat there for nobody.
+        await this.settleClientLockAcquisition();
+        // Skip if already evaluating lock release (buffer timeout exists)
+        if (this._bufferPeriodTimeout) {
+            this.getLogger().info("[lock-service] lock release already in progress, skipping duplicate evaluation");
+            return;
+        }
+        // Nothing to evaluate before a client has ever claimed the lock. The
+        // inactivity timer is armed from the constructor, so on the cloud path it
+        // now elapses on a warm, unclaimed sandbox — that is an empty sandbox, not
+        // a lock going stale. A client that came and went is DISCONNECTED rather
+        // than untouched, and still needs the release path below.
+        if (this._status === LockServiceStatus.IDLE &&
+            !this._activityTracker.isDisconnected) {
+            return;
+        }
+        // 1. Wait for Clark generation to complete if it's generating
+        if (this.waitForGenerationCompleteCallback) {
+            this.getLogger().info("[lock-service] waiting for Clark generation to complete before evaluating lock state");
+            await this.waitForGenerationCompleteCallback();
+            this.getLogger().info("[lock-service] Clark generation complete");
+        }
+        // A headless turn holds the sandbox on its own: nobody is watching a
+        // gateway build, so idleness measured from editor pings says nothing about
+        // whether the work is still running.
+        if (this.hasAttachedGatewayPeer) {
+            this.getLogger().info(`[lock-service] gateway peer attached, keeping the lock (lockId=${this._lockId}, appId=${this.applicationId})`);
+            return;
+        }
+        // Check if user is still connected AND active, or became active again
+        const shouldAbortRelease = this._activityTracker.connectedUsers.length > 0 &&
+            this._activityTracker.wasRecentlyActive;
+        if (!this._isRestarting && shouldAbortRelease) {
+            this.getLogger().debug("[lock-service] user is still active, not changing lock state");
+            return;
+        }
+        const isUserDisconnected = this._activityTracker.isDisconnected;
+        // Case 1: User is disconnected - release the lock
+        if (isUserDisconnected) {
+            if (this._activityTracker.wasRecentlyActive) {
+                // User was recently active - give buffer period before releasing
+                this.getLogger().debug(`[lock-service] user disconnected but was recently active, waiting for ${this._lockBufferMs}ms buffer period before releasing lock`);
+                this._bufferPeriodTimeout = setTimeout(() => {
+                    this.getLogger().debug("[lock-service] buffer period expired, releasing lock");
+                    if (this.lockType === LockType.LOCAL) {
+                        void this.shutdownAndExit();
+                    }
+                    else {
+                        void this.relinquishLock();
+                    }
+                }, this._lockBufferMs);
+                this._bufferPeriodTimeout.unref();
+            }
+            else {
+                // User was NOT recently active - release immediately
+                this.getLogger().debug("[lock-service] user disconnected and was not recently active, releasing lock immediately");
+                if (this.lockType === LockType.LOCAL) {
+                    await this.shutdownAndExit();
+                }
+                else {
+                    await this.relinquishLock();
+                }
+            }
+        }
+        else {
+            // Case 2: the lock is idle - either a connected client has gone quiet, or
+            // a boot-time force takeover was never claimed by one. Either way, mark
+            // it ready for takeover AND stop the heartbeat. The pod
+            // heartbeat is the ONLY thing refreshing the server-side AppBranchLock;
+            // if we keep heartbeating while nobody is using it, the lock never
+            // TTL-expires and no other user can take over the app (APPS-4840).
+            // Stopping it lets the lock expire so another user can acquire it
+            // normally, without taking a dev server that is serving fine down with
+            // it. restartInactivityTimer() resumes the heartbeat if this user becomes
+            // active again before the lock expires.
+            // The two cases reach the same handling but are very different
+            // incidents, so the line names which one it is. A lock no client ever
+            // claimed is the state the deleted startup watchdog used to report with
+            // its own distinctive line; without a field here, oncall reconstructing a
+            // stuck-lock incident cannot tell "nobody ever attached" from "someone
+            // stepped away", and both read as routine idleness.
+            const reason = this.hasAttachedClient
+                ? "connected client went quiet"
+                : "never claimed by a client";
+            this.getLogger().info(`[lock-service] lock idle (${reason}), marking ready for takeover and stopping heartbeat so it can expire (lockId=${this._lockId}, appId=${this.applicationId})`);
+            this._activityTracker.markReadyForTakeover();
+            this._heartbeatStoppedForIdle = true;
+            this.stopHeartbeat();
         }
     }
-    async closeRpcClient() {
-        if (this.rpcClient) {
-            await this.rpcClient.close();
-            this.rpcClient = null;
+    /**
+     * Restart the inactivity timer when user activity is detected.
+     * This timer tracks if the user goes inactive (no pings for N minutes).
+     */
+    async restartInactivityTimer() {
+        // Clear any existing inactivity timer since we have activity
+        if (this._inactivityTimeout) {
+            clearTimeout(this._inactivityTimeout);
+            this._inactivityTimeout = undefined;
+        }
+        // Clear any buffer period timeout since we're receiving activity pings
+        // This prevents shutdown when keep-alive pings continue after a disconnect event
+        if (this._bufferPeriodTimeout) {
+            clearTimeout(this._bufferPeriodTimeout);
+            this._bufferPeriodTimeout = undefined;
+            this.getLogger().info("[lock-service] activity detected, cleared pending buffer period timeout");
         }
+        // If the heartbeat was stopped because the user went idle (ready for
+        // takeover), they are active again now - resume refreshing the lock so we
+        // keep it (or reacquire it if it already expired). If another user took
+        // over in the meantime, the heartbeat grab will fail and shut us down.
+        // Gating on _heartbeatStoppedForIdle (rather than just a missing timeout)
+        // avoids racing the heartbeat back to life during lock acquisition or a
+        // branch-switch transfer, which stop the heartbeat for their own reasons.
+        if (this._heartbeatStoppedForIdle &&
+            this._status === LockServiceStatus.LOCKED &&
+            this._lockId) {
+            this._heartbeatStoppedForIdle = false;
+            // The user is back, so the lock is no longer up for grabs.
+            this._activityTracker.resetReadyForTakeover();
+            this.getLogger().info(`[lock-service] user active again, resuming lock heartbeat (lockId=${this._lockId}, appId=${this.applicationId})`);
+            void this.scheduleNextHeartbeat();
+        }
+        this.reclaimLockForActiveClient();
+        this.scheduleInactivityEvaluation();
     }
-    async getRpcClient() {
-        // TODO(David): Move this to a shared socket with the sync service
-        if (!this.rpcClient) {
-            this.rpcClient = await connectToISocketRPCServer({
-                superblocksBaseUrl: this.superblocksBaseUrl,
-                token: this.authToken,
-            });
+    scheduleInactivityEvaluation() {
+        this._inactivityTimeout = setTimeout(() => {
+            this._inactivityTimeout = undefined;
+            this.getLogger().debug(`[lock-service] No activity for ${this._inactivityThresholdMs}ms, evaluating lock state`);
+            this.evaluateLockStateInBackground("the inactivity deadline");
+        }, this._inactivityThresholdMs);
+        this._inactivityTimeout.unref();
+    }
+    /**
+     * Mark the user's activity from UI ping
+     */
+    markActivity(isUserActive) {
+        this._activityTracker.markActivity(isUserActive);
+    }
+    /**
+     * A gateway peer attached and is driving headless work.
+     *
+     * Gateway peers are deliberately not connected-user presence — they are not
+     * a browser editor and must not keep an editor's lock alive — so they need
+     * their own liveness signal. Without it the inactivity reaper would take the
+     * sandbox out from under a headless build that nobody is watching. Tracked
+     * per peer id so a reattach that closes the socket it replaced does not hand
+     * the sandbox back while its successor is still working.
+     */
+    markGatewayAttached(peerId) {
+        const isNew = !this._gatewayLivenessByPeerId.has(peerId);
+        // Refreshed on every authorized gateway call, so only the first one is
+        // worth a line — the rest would be per-RPC noise.
+        this._gatewayLivenessByPeerId.set(peerId, Date.now());
+        if (!isNew) {
+            return;
+        }
+        this.getLogger().info(`[lock-service] gateway peer attached (peerId=${peerId}, appId=${this.applicationId})`);
+        this.armGatewayLivenessSweep();
+        // No lock is taken here. A gateway peer being attached says only that a
+        // socket is open; {@link acquireLockForTurn} takes write access when there
+        // is actually a turn to write for, which is what keeps the app openable
+        // between prompts.
+        void this.restartInactivityTimer();
+    }
+    /**
+     * A gateway peer detached. The sandbox stays protected while any other
+     * gateway peer is still attached.
+     */
+    markGatewayDetached(peerId) {
+        if (!this._gatewayLivenessByPeerId.delete(peerId)) {
+            return;
         }
-        return this.rpcClient;
+        this.getLogger().info(`[lock-service] gateway peer detached (peerId=${peerId}, appId=${this.applicationId})`);
+        if (this._gatewayLivenessByPeerId.size !== 0) {
+            return;
+        }
+        this.clearGatewayLivenessSweep();
+        this.handleLastGatewayPeerGone();
+    }
+    /**
+     * The last gateway peer is gone, so no turn is running.
+     *
+     * Write access was taken for the turn, so it goes back now rather than being
+     * left to TTL out — that would leave the app unopenable for up to the lock's
+     * two-minute lifetime after a headless build had already finished. This is
+     * also the backstop for a gateway that dies mid-turn.
+     *
+     * Deliberately not a shutdown: the gateway drops its socket after every turn
+     * and opens a new one for the next prompt, and in between the pod keeps
+     * serving. The next turn takes the lock again through
+     * {@link acquireLockForTurn}. What bounds the pod's life is SABS's live-edit
+     * expiry, not this.
+     *
+     * Only when no editor is attached. An editor disconnect releases on its own
+     * buffer in {@link evaluateLockState}, and a second releaser over the top of
+     * that would race it.
+     */
+    handleLastGatewayPeerGone() {
+        if (this._activityTracker.connectedUsers.length > 0) {
+            this.evaluateLockStateInBackground("the last gateway peer detached");
+            return;
+        }
+        void this.handBackTurnLockWhenGenerationSettles().catch((error) => {
+            this.getLogger().error(`[lock-service] failed to hand the turn lock back after the last gateway peer detached (lockId=${this._lockId}, appId=${this.applicationId})`, getErrorMeta(error));
+        });
+    }
+    /**
+     * Wait for the turn to finish, then hand its lock back.
+     *
+     * The wait sits outside the lock queue, the way {@link evaluateLockState}
+     * does it. That queue serialises the handback itself, branch switches,
+     * `isLockedWhenSettled` and the next turn's acquisition, so waiting inside
+     * it lets a single hung generation stall all of them — including a graceful
+     * shutdown, which awaits the handback with no timeout of its own.
+     */
+    async handBackTurnLockWhenGenerationSettles() {
+        await this.waitForGenerationCompleteCallback?.();
+        await this._lockOperationQueue.enqueue(async () => {
+            if (this.hasAttachedGatewayPeer ||
+                this._activityTracker.connectedUsers.length > 0) {
+                return;
+            }
+            if (!this.isLocked) {
+                return;
+            }
+            this.getLogger().info(`[lock-service] no gateway peer left, handing the turn lock back and staying up (lockId=${this._lockId}, appId=${this.applicationId})`);
+            await this.relinquishLockNow(() => this.hasAttachedGatewayPeer ||
+                this._activityTracker.connectedUsers.length > 0);
+        });
+    }
+    /**
+     * Watches for the last gateway signal lapsing.
+     *
+     * The inactivity reaper a gateway defers fires once and is then only
+     * re-examined when something happens. A silent gateway is the absence of
+     * anything happening, so this is what notices it and puts the lock back up
+     * for evaluation.
+     */
+    armGatewayLivenessSweep() {
+        if (this._gatewayLivenessSweep) {
+            return;
+        }
+        this._gatewayLivenessSweep = setInterval(() => {
+            if (this.hasAttachedGatewayPeer) {
+                return;
+            }
+            this.clearGatewayLivenessSweep();
+            // A gateway that went silent is a turn that ended without saying so, so
+            // it takes the same route as a clean detach.
+            this.handleLastGatewayPeerGone();
+        }, Math.max(1, Math.floor(this._gatewayLivenessTtlMs / 2)));
+        this._gatewayLivenessSweep.unref?.();
+    }
+    clearGatewayLivenessSweep() {
+        if (!this._gatewayLivenessSweep) {
+            return;
+        }
+        clearInterval(this._gatewayLivenessSweep);
+        this._gatewayLivenessSweep = undefined;
+    }
+    /**
+     * Whether any gateway peer's liveness is still current. Lapsed entries are
+     * dropped as they are found: the socket they belong to may never close, and
+     * the sandbox must become available again either way.
+     */
+    get hasAttachedGatewayPeer() {
+        const now = Date.now();
+        for (const [peerId, lastSeenAt] of [...this._gatewayLivenessByPeerId]) {
+            if (now - lastSeenAt < this._gatewayLivenessTtlMs) {
+                continue;
+            }
+            this._gatewayLivenessByPeerId.delete(peerId);
+            this.getLogger().warn(`[lock-service] gateway peer liveness lapsed after ${this._gatewayLivenessTtlMs}ms (peerId=${peerId}, appId=${this.applicationId})`);
+            try {
+                this.onGatewayLivenessLapsed?.(peerId);
+            }
+            catch (error) {
+                this.getLogger().warn(`[lock-service] onGatewayLivenessLapsed threw; continuing (peerId=${peerId}, appId=${this.applicationId})`, getErrorMeta(error));
+            }
+        }
+        return this._gatewayLivenessByPeerId.size > 0;
+    }
+    /** when the dev server is restarting, we will use the 5-minute shutdown timer instead of the instant one */
+    async setIsRestarting() {
+        this._isRestarting = true;
     }
 }
 //# sourceMappingURL=index.js.map