@superblocksteam/vite-plugin-file-sync 2.0.155 → 2.0.156-next.1

package/dist/lock-service/index.js

@@ -2,18 +2,10 @@ import { addTracingToMethods, ConflictError, NotFoundError, TracedEventEmitter,
 import { unwrapResponseDto } from "@superblocksteam/shared";
 import { applyErrorHandling, } from "../errors/error-handler.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 LOCK_BUFFER_MS = 30 * 1000; // 30 seconds
-// Startup no-socket watchdog: if a freshly-acquired lock never sees an editor
-// socket attach, the pod is reclaimed so an abandoned startup can't hold the
-// exclusive per-app-branch lock forever. The window must cover the entire
-// startup — DBFS download + package install, then socket attach — so it sits
-// well above worst-case hydration (~90s observed) instead of racing app size
-// the way the old 90s window did and bricking slow-hydrating apps. Trade-off:
-// an abandoned-but-hydrated pod is reclaimed up to this long rather than
-// sooner; that case is bounded and force-takeover is available.
-const STARTUP_CONNECTION_TIMEOUT_MS = 4 * 60 * 1000; // 4 minutes
 /**
  * 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
@@ -49,6 +41,25 @@ export var LockType;
     LockType["LOCAL"] = "local";
     LockType["CSB"] = "csb";
 })(LockType || (LockType = {}));
+/**
+ * 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;
@@ -57,6 +68,7 @@ export class LockService extends TracedEventEmitter {
     syncCallback;
     waitForGenerationCompleteCallback;
     onGatewayLivenessLapsed;
+    onLockConflict;
     _status = LockServiceStatus.IDLE;
     _lockId;
     _heartbeatTimeout;
@@ -68,6 +80,22 @@ export class LockService extends TracedEventEmitter {
     // (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;
@@ -76,9 +104,9 @@ export class LockService extends TracedEventEmitter {
     _rpcClient;
     _inactivityThresholdMs;
     _lockBufferMs;
-    _startupConnectionTimeout;
-    _startupConnectionTimeoutStartedAt;
-    _startupConnectionTimeoutExpired = false;
+    /** 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();
@@ -107,15 +135,7 @@ export class LockService extends TracedEventEmitter {
             acquireLock: { operation: "acquiring lock" },
             releaseLock: { operation: "releasing lock" },
         });
-        const methods = [
-            "acquireLock",
-            "releaseLock",
-            "checkAndUpdateLockIfPossible",
-            "shutdown",
-            "shutdownAndExit",
-            "restartInactivityTimer",
-        ];
-        addTracingToMethods(this, methods, this._tracer);
+        addTracingToMethods(this, [...TRACED_LOCK_SERVICE_METHODS], this._tracer);
         void this.restartInactivityTimer();
     }
     getLogger() {
@@ -138,12 +158,28 @@ export class LockService extends TracedEventEmitter {
     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);
         }
     }
@@ -168,25 +204,185 @@ export class LockService extends TracedEventEmitter {
     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);
+    }
     /**
-     * Check if the lock service is in a state where it can reacquire a lock.
-     * This happens when the lock was released, the dev server is still alive,
-     * and an editor is attached to reacquire it for.
+     * 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).
      */
-    get canReacquireLock() {
-        if (this._activityTracker.connectedUsers.length === 0) {
-            return false;
+    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));
+    }
+    /**
+     * 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.
+     */
+    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));
         }
-        return (this._status === LockServiceStatus.LOCK_RELEASED ||
-            this._status === LockServiceStatus.IDLE);
     }
+    /**
+     * 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;
-        if (options?.reacquireLock && this.isLocked && lockIdBeforeSwitch) {
+        const reacquireLock = options?.reacquireLock ?? this.isLocked;
+        if (reacquireLock && this.isLocked && lockIdBeforeSwitch) {
             this.stopHeartbeat();
             try {
                 const lockResponse = await this._rpcClient.call(async (client) => {
@@ -204,9 +400,6 @@ export class LockService extends TracedEventEmitter {
                 this.branchName = nextBranchName;
                 this._lockId = transferredLock.lockId;
                 this.status = LockServiceStatus.LOCKED;
-                // A same-pod atomic transfer is not a fresh startup, so the no-socket
-                // watchdog is intentionally left untouched: it keeps ticking from the
-                // original acquisition rather than restarting on every branch switch.
                 this.getLogger().info(`[lock-service] atomically transferred lock branch context from '${previousBranchName}' to '${nextBranchName}'`);
                 void this.scheduleNextHeartbeat();
                 return;
@@ -227,19 +420,27 @@ export class LockService extends TracedEventEmitter {
         else {
             this.stopHeartbeat();
             this._lockId = undefined;
-            this.status = LockServiceStatus.IDLE;
+            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 (options?.reacquireLock) {
+        if (reacquireLock) {
             await this.acquireLock();
         }
     }
     /**
-     * Acquire a lock on the specified application and branch
+     * 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.
      */
-    async acquireLock() {
-        this.startStartupConnectionTimeoutIfNeeded();
+    acquireLock() {
+        return this.trackAcquisition(this.acquireLockImpl());
+    }
+    async acquireLockImpl() {
         this.status = LockServiceStatus.ACQUIRING;
         // Stop any existing heartbeat before acquiring a new lock to prevent duplicate heartbeat loops
         this.stopHeartbeat();
@@ -259,17 +460,27 @@ export class LockService extends TracedEventEmitter {
                 this.status = LockServiceStatus.LOCKED;
                 this._heartbeatStoppedForIdle = false;
                 this.emit("lockAcquired", this._lockId);
-                this.evaluateStartupConnectionTimeoutIfNeeded();
                 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) {
                 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({ serverInitiated: false });
+                // 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 {
@@ -277,6 +488,67 @@ export class LockService extends TracedEventEmitter {
             }
         }
     }
+    /**
+     * 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
      */
@@ -284,6 +556,7 @@ export class LockService extends TracedEventEmitter {
         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
@@ -332,7 +605,6 @@ export class LockService extends TracedEventEmitter {
                 clearTimeout(this._inactivityTimeout);
                 this._inactivityTimeout = undefined;
             }
-            this.clearStartupConnectionTimeout();
         }
     }
     async grabLockImpl() {
@@ -363,8 +635,10 @@ export class LockService extends TracedEventEmitter {
     /**
      * Force takeover of the lock from another user (only allowed when user is inactive)
      */
-    async forceTakeover() {
-        this.startStartupConnectionTimeoutIfNeeded();
+    forceTakeover() {
+        return this.trackAcquisition(this.forceTakeoverImpl());
+    }
+    async forceTakeoverImpl() {
         this.status = LockServiceStatus.ACQUIRING;
         try {
             const lockResponse = await this._rpcClient.call(async (client) => {
@@ -381,10 +655,14 @@ export class LockService extends TracedEventEmitter {
                 this.getLogger().info(`[lock-service] lock acquired via force takeover: ${this._lockId}`);
                 this.status = LockServiceStatus.LOCKED;
                 this.emit("lockAcquired", this._lockId);
-                this.evaluateStartupConnectionTimeoutIfNeeded();
                 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}`);
@@ -419,6 +697,20 @@ export class LockService extends TracedEventEmitter {
                     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");
@@ -464,50 +756,220 @@ export class LockService extends TracedEventEmitter {
         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({ serverInitiated, switchingTo, initiatedByEmail, }) {
-        if (serverInitiated) {
-            this.emit("closedByServer", { initiatedByEmail, switchingTo });
+    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;
         }
-        // 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
-            this.getLogger().info("[lock-service] performing one last sync before shutdown");
-            try {
-                await this.syncCallback();
-                this.getLogger().info("[lock-service] sync callback completed");
+        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;
             }
-            catch (error) {
-                this.getLogger().error("[lock-service] sync callback failed during shutdown, continuing with lock release", getErrorMeta(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);
             }
         }
-        else {
-            this.getLogger().info("[lock-service] no sync callback because lock is not valid anymore");
+        // 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();
-        this.clearStartupConnectionTimeout();
         this.clearGatewayLivenessSweep();
-        if (this.isLocked && !serverInitiated) {
-            // Server initiated shutdown means lock is already getting released
-            this.getLogger().info("[lock-service] releasing lock before shutdown");
-            await this.releaseLock();
-            this.getLogger().info("[lock-service] lock released before shutdown");
+        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;
         }
-        this.getLogger().info("[lock-service] closing rpc client before shutdown");
-        await this._rpcClient.close();
-        this.getLogger().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() {
         try {
-            await this.shutdown({ serverInitiated: false });
+            await this.relinquishLock();
         }
         catch (error) {
-            this.getLogger().error("[lock-service] Lock service failed to gracefully shutdown and will forcefully exit", getErrorMeta(error));
+            this.getLogger().error("[lock-service] failed to hand the lock back, exiting anyway", getErrorMeta(error));
         }
         finally {
             process.exit(1);
@@ -519,15 +981,24 @@ export class LockService extends TracedEventEmitter {
     addConnectedPeerIdToUser(userId, peerId) {
         this._activityTracker.addConnectedPeerIdToUser(userId, peerId);
         this._isRestarting = false;
-        this.clearStartupConnectionTimeout();
+        this.claimLockForFirstClient();
         if (this._bufferPeriodTimeout) {
             clearTimeout(this._bufferPeriodTimeout);
             this._bufferPeriodTimeout = undefined;
             this.getLogger().info("[lock-service] user reconnected, cleared pending buffer period timeout");
         }
-        this.armIdleEvaluationAfterReconnectIfNeeded();
+        this.ensureIdleEvaluationArmed();
     }
-    armIdleEvaluationAfterReconnectIfNeeded() {
+    /**
+     * 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;
@@ -570,7 +1041,15 @@ export class LockService extends TracedEventEmitter {
             // 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.
-            if (this._heartbeatStoppedForIdle) {
+            //
+            // 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));
@@ -603,58 +1082,44 @@ export class LockService extends TracedEventEmitter {
             this.getLogger().info("[lock-service] heartbeat stopped");
         }
     }
-    clearStartupConnectionTimeout() {
-        if (this._startupConnectionTimeout) {
-            clearTimeout(this._startupConnectionTimeout);
-            this._startupConnectionTimeout = undefined;
-        }
-        this._startupConnectionTimeoutExpired = false;
-        this._startupConnectionTimeoutStartedAt = undefined;
-    }
-    startStartupConnectionTimeoutIfNeeded() {
-        if (this._startupConnectionTimeoutStartedAt !== undefined) {
-            return;
-        }
-        this.clearStartupConnectionTimeout();
-        this._startupConnectionTimeoutStartedAt = Date.now();
-        // info (not debug) so oncall can confirm the watchdog armed when
-        // reconstructing a fire incident; fires once per lock acquisition.
-        this.getLogger().info(`[lock-service] starting initial connection timeout window (${STARTUP_CONNECTION_TIMEOUT_MS}ms)`);
-        this._startupConnectionTimeout = setTimeout(() => {
-            this._startupConnectionTimeout = undefined;
-            this._startupConnectionTimeoutExpired = true;
-            this.evaluateStartupConnectionTimeoutIfNeeded();
-        }, STARTUP_CONNECTION_TIMEOUT_MS);
-        this._startupConnectionTimeout.unref();
-    }
-    evaluateStartupConnectionTimeoutIfNeeded() {
-        if (!this._startupConnectionTimeoutExpired) {
-            return;
-        }
-        if (!this.isLocked) {
-            return;
-        }
-        if (this._activityTracker.connectedUsers.length > 0) {
-            return;
-        }
-        if (this.hasAttachedGatewayPeer) {
-            return;
-        }
-        this.getLogger().warn(`[lock-service] no socket connection detected within ${STARTUP_CONNECTION_TIMEOUT_MS}ms after initial lock acquisition, marking session inactive (lockId=${this._lockId}, appId=${this.applicationId})`);
-        this._activityTracker.markDisconnectedDueToStartupTimeout();
-        void this.evaluateLockState().catch((error) => {
-            this.getLogger().error(`[lock-service] failed to evaluate lock state after startup connection timeout (lockId=${this._lockId}, appId=${this.applicationId})`, getErrorMeta(error));
-        });
-    }
     /**
      * Evaluate if the lock should be released (user disconnected) or marked as ready for takeover (user inactive but connected)
      */
     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 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().debug("[lock-service] waiting for Clark generation to complete before evaluating lock state");
@@ -676,7 +1141,6 @@ export class LockService extends TracedEventEmitter {
             return;
         }
         const isUserDisconnected = this._activityTracker.isDisconnected;
-        const isAwaitingFirstEditor = this._activityTracker.connectedUsers.length === 0;
         // Case 1: User is disconnected - release the lock
         if (isUserDisconnected) {
             if (this._activityTracker.wasRecentlyActive) {
@@ -688,7 +1152,7 @@ export class LockService extends TracedEventEmitter {
                         void this.shutdownAndExit();
                     }
                     else {
-                        void this.shutdown({ serverInitiated: false });
+                        void this.relinquishLock();
                     }
                 }, this._lockBufferMs);
                 this._bufferPeriodTimeout.unref();
@@ -700,22 +1164,31 @@ export class LockService extends TracedEventEmitter {
                     await this.shutdownAndExit();
                 }
                 else {
-                    await this.shutdown({ serverInitiated: false });
+                    await this.relinquishLock();
                 }
             }
         }
-        else if (isAwaitingFirstEditor) {
-            this.getLogger().debug("[lock-service] no editor connected yet, leaving the lock to the startup watchdog");
-        }
         else {
-            // Case 2: User is still connected but inactive - mark the lock ready for
-            // takeover AND stop the heartbeat. The pod heartbeat is the ONLY thing
-            // refreshing the server-side AppBranchLock; if we keep heartbeating while
-            // the user is idle, 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. restartInactivityTimer() resumes the
-            // heartbeat if this user becomes active again before the lock expires.
-            this.getLogger().info(`[lock-service] user inactive but still connected, marking lock ready for takeover and stopping heartbeat so the lock can expire (lockId=${this._lockId}, appId=${this.applicationId})`);
+            // 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();
@@ -754,10 +1227,7 @@ export class LockService extends TracedEventEmitter {
             this.getLogger().info(`[lock-service] user active again, resuming lock heartbeat (lockId=${this._lockId}, appId=${this.applicationId})`);
             void this.scheduleNextHeartbeat();
         }
-        if (this.canReacquireLock) {
-            this.getLogger().info("[lock-service] user active again with no lock held, reacquiring");
-            void this.acquireLock();
-        }
+        this.reclaimLockForActiveClient();
         this.scheduleInactivityEvaluation();
     }
     scheduleInactivityEvaluation() {
@@ -779,11 +1249,10 @@ export class LockService extends TracedEventEmitter {
      *
      * 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 startup watchdog and 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.
+     * 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);
@@ -795,6 +1264,10 @@ export class LockService extends TracedEventEmitter {
         }
         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();
     }
     /**
@@ -806,20 +1279,72 @@ export class LockService extends TracedEventEmitter {
             return;
         }
         this.getLogger().info(`[lock-service] gateway peer detached (peerId=${peerId}, appId=${this.applicationId})`);
-        if (this._gatewayLivenessByPeerId.size === 0) {
-            this.clearGatewayLivenessSweep();
+        if (this._gatewayLivenessByPeerId.size !== 0) {
+            return;
         }
-        // A window that expired while a gateway held the sandbox was deferred, not
-        // cancelled; re-evaluate now that the last one is gone.
-        this.evaluateStartupConnectionTimeoutIfNeeded();
+        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) {
+            void this.evaluateLockState().catch((error) => {
+                this.getLogger().error(`[lock-service] failed to evaluate lock state after the last gateway peer detached (lockId=${this._lockId}, appId=${this.applicationId})`, getErrorMeta(error));
+            });
+            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 windows a gateway defers (startup watchdog, inactivity reaper) fire
-     * once and are 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.
+     * 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) {
@@ -830,10 +1355,9 @@ export class LockService extends TracedEventEmitter {
                 return;
             }
             this.clearGatewayLivenessSweep();
-            this.evaluateStartupConnectionTimeoutIfNeeded();
-            void this.evaluateLockState().catch((error) => {
-                this.getLogger().error(`[lock-service] failed to evaluate lock state after gateway liveness lapsed (lockId=${this._lockId}, appId=${this.applicationId})`, getErrorMeta(error));
-            });
+            // 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?.();
     }