@superblocksteam/sdk 2.0.155 → 2.0.156-next.0

package/src/cli-replacement/dev.mts

@@ -16,10 +16,10 @@ import type {
   DependencyUpgradeError,
   ServerError,
 } from "@superblocksteam/library-shared/types";
+import type { ConflictError } from "@superblocksteam/shared";
 import {
   buildGithubSuperblocksSyncWorkflow,
   buildGithubSuperblocksSyncWorkflowFromBaseUrl,
-  ConflictError,
   DEFAULT_NON_GIT_BRANCH,
   isGitAuthErrorMessage,
   isGitHubRemoteUrl,
@@ -176,6 +176,19 @@ async function handleInactiveLockTakeover(
     throw new Error("Lock takeover prompt shown");
   }
 
+  // Only ask if somebody can answer. `promptUser` reads stdin, which on a
+  // sandbox nothing is attached to — it would wait forever for a keystroke
+  // that cannot come. Reachable now that conflicts surface when a client
+  // attaches rather than only during a CLI startup.
+  if (!process.stdin.isTTY) {
+    logger.warn(`${warningMessage} Run with --force-takeover to take it.`);
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: "Lock held by an inactive user, nobody available to prompt",
+    });
+    throw new Error(warningMessage);
+  }
+
   // Prompt user to force takeover (CLI only)
   logger.warn(warningMessage);
   const shouldTakeover = await getBooleanUserResponse(prompt);
@@ -1019,12 +1032,12 @@ export async function flushTelemetryWithTimeout(): Promise<boolean> {
  * MUST BE CALLED LAST in any shutdown sequence. This does not merely flush: it
  * awaits `shutdownTelemetry()`, which tears the provider down, so every signal
  * emitted after it goes into a dead pipeline. It can also block for up to
- * `TELEMETRY_FLUSH_TIMEOUT_MS`, and delaying `lockService.shutdown()` by that
- * much delays the lock release that lets a replacement sandbox take over —
+ * `TELEMETRY_FLUSH_TIMEOUT_MS`, and delaying `lockService.relinquishLock()` by
+ * that much delays the lock release that lets a replacement sandbox take over —
  * which is the entire recovery story this exit path exists to enable.
  *
  * "Last" is only reachable because the callers drive the lock service with
- * `shutdown()` rather than `shutdownAndExit()`. The latter ends in an
+ * `relinquishLock()` rather than `shutdownAndExit()`. The latter ends in an
  * unconditional `finally { process.exit(1) }`, and `process.exit` is
  * synchronous, so anything sequenced after it never runs at all. See the two
  * fatal-exit blocks in `dev()`.
@@ -1075,8 +1088,8 @@ const FATAL_EXIT_STEP_TIMEOUT_MS = 5000;
 
 /**
  * One teardown step. Returning `undefined` is allowed so callers can pass the
- * optional-chained call directly (`() => lockService?.shutdown(...)`) without
- * having to re-narrow a mutable binding at the call site.
+ * optional-chained call directly (`() => lockService?.relinquishLock()`)
+ * without having to re-narrow a mutable binding at the call site.
  */
 type FatalExitStep = () => Promise<unknown> | undefined;
 
@@ -1130,7 +1143,7 @@ async function runFatalExitStep(
  *
  * Order is load-bearing:
  *   1. `removeIntegrationCache` — ai-service state that must not outlive us.
- *   2. `shutdownLockService` — releases the AppBranchLock. Recovery-critical:
+ *   2. `relinquishLock` — hands the AppBranchLock back. Recovery-critical:
  *      the heartbeat dies with the process, so skipping this makes the
  *      replacement sandbox's `acquireLock()` fail with a ConflictError until
  *      the server-side TTL expires, and the replacement is the entire point of
@@ -1145,15 +1158,15 @@ async function runFatalExitStep(
  *
  * This does NOT exit. The caller owns `process.exit(1)` from a `finally`, so
  * the exit still happens even if this function is somehow bypassed. That is
- * also why callers must drive the lock service through `shutdown()` and not
- * `shutdownAndExit()`: the latter ends in its own unconditional
+ * also why callers must drive the lock service through `relinquishLock()` and
+ * not `shutdownAndExit()`: the latter ends in its own unconditional
  * `finally { process.exit(1) }`, and `process.exit` is synchronous, so
  * everything sequenced after it — including the flush — silently never ran.
  */
 export async function runFatalExitShutdown(steps: {
   logger: Logger;
   removeIntegrationCache?: FatalExitStep;
-  shutdownLockService?: FatalExitStep;
+  relinquishLock?: FatalExitStep;
 }): Promise<void> {
   const { logger } = steps;
   await runFatalExitStep(
@@ -1161,11 +1174,7 @@ export async function runFatalExitShutdown(steps: {
     "ai-service integration cache removal",
     steps.removeIntegrationCache,
   );
-  await runFatalExitStep(
-    logger,
-    "lock service shutdown",
-    steps.shutdownLockService,
-  );
+  await runFatalExitStep(logger, "lock hand-back", steps.relinquishLock);
   await flushTelemetryBeforeExit(logger);
 }
 
@@ -1635,35 +1644,84 @@ export async function dev(options: {
 
         logger.info("Checking if local files are synced with the server");
 
+        const lockSvc = lockService;
+
+        // Nobody takes the lock to boot: nothing startup does is gated on
+        // holding one, and a lock taken before any client exists is held on
+        // behalf of nobody. `LockService` takes it when the first client
+        // attaches, and tells us here if somebody else already has it —
+        // this is the `ConflictError` catch that used to wrap the boot-time
+        // acquire, moved to where acquisition actually happens (ENG-6090).
+        lockSvc.setOnLockConflict(async (error) => {
+          let stopForExtension = false;
+          await tracer.startActiveSpan("handlingLockConflict", async (span) => {
+            try {
+              await handleLockConflict(error, lockSvc, span, logger);
+            } catch (conflictError) {
+              // Reporting is all this owes the caller. The holder is someone
+              // else's live session and the pod is still serving preview, so
+              // there is nothing to tear down — the lock does not decide how
+              // long this process lives (ENG-6032).
+              logger.warn(
+                `Could not take the live-edit lock: ${conflictError instanceof Error ? conflictError.message : String(conflictError)}`,
+              );
+              // Except under the VS Code extension, which reads the `cliprompt`
+              // above, asks the user, and answers by restarting this command
+              // with `--force-takeover`. That hand-off has always ended with
+              // this process gone: it used to abort startup before anything
+              // bound a port. Staying up now would leave the replacement
+              // fighting us for :5173.
+              if (process.env.SUPERBLOCKS_VSCODE === "true") {
+                logger.info(
+                  "Stopping so the extension can restart with --force-takeover",
+                );
+                stopForExtension = true;
+              }
+            } finally {
+              span.end();
+            }
+          });
+          if (!stopForExtension) {
+            return;
+          }
+          // Outside the span, so `span.end()` above has already run and the
+          // flush below can carry it. This is the same teardown the two
+          // fatal-exit blocks in `dev()` use, and for the same reason: the
+          // `shutdownAndExit()` that used to be inside the `catch` exits
+          // synchronously from its own `finally`, which made both the
+          // `span.end()` and the telemetry flush unreachable — the trace for
+          // the one event this handler exists to record never left the process.
+          try {
+            await runFatalExitShutdown({
+              logger,
+              removeIntegrationCache: () => aiService?.removeIntegrationCache(),
+              relinquishLock: () => lockSvc.relinquishLock(),
+            });
+          } finally {
+            process.exit(1);
+          }
+        });
+
         try {
           await maskUnixSignals(async () => {
-            if (lockService) {
-              const lockSvc = lockService;
+            // `--force-takeover` is the one thing that still acquires at boot:
+            // it is an explicit "take it from them now" rather than a pod
+            // helping itself to a lock nobody asked it to hold.
+            if (options.forceTakeover) {
               await tracer.startActiveSpan(
-                "acquiringInitialLock",
+                "forcingInitialLockTakeover",
                 async (span) => {
                   try {
-                    // If --force-takeover flag is set, immediately force takeover instead of acquiring
-                    if (options.forceTakeover) {
-                      logger.info(
-                        "Force takeover requested, taking over lock...",
-                      );
-                      await lockSvc.forceTakeover();
-                      logger.info(
-                        "Lock acquired successfully via force takeover.",
-                      );
-                    } else {
-                      await lockSvc.acquireLock();
-                    }
+                    logger.info(
+                      "Force takeover requested, taking over lock...",
+                    );
+                    await lockSvc.forceTakeover();
+                    logger.info(
+                      "Lock acquired successfully via force takeover.",
+                    );
                   } catch (error) {
-                    // If we got a conflict error (409), inspect the lock for more information
-                    if (error instanceof ConflictError) {
-                      await handleLockConflict(error, lockSvc, span, logger);
-                      return;
-                    }
-
                     logger.error(
-                      "Failed to acquire lock on application",
+                      "Failed to force takeover of lock on application",
                       getErrorMeta(error),
                     );
                     span.setStatus({
@@ -2337,7 +2395,7 @@ export async function dev(options: {
               try {
                 logger.info("Releasing lock before restarting the dev server");
                 await aiService?.removeIntegrationCache();
-                await lockService?.shutdown({ serverInitiated: false });
+                await lockService?.relinquishLock();
               } catch (e) {
                 logger.error(
                   "Error releasing lock before restarting the dev server",
@@ -2414,13 +2472,13 @@ export async function dev(options: {
               }),
             );
             try {
-              // `shutdown()`, NOT `shutdownAndExit()`. The latter ends in an
-              // unconditional `finally { process.exit(1) }`; `process.exit` is
-              // synchronous, so every statement below it would be dead code
+              // `relinquishLock()`, NOT `shutdownAndExit()`. The latter ends in
+              // an unconditional `finally { process.exit(1) }`; `process.exit`
+              // is synchronous, so every statement below it would be dead code
               // whenever `lockService` is set — which is the normal state in a
               // SABS pod, exactly the population this exit path targets. The
-              // telemetry flush was silently never running. `shutdown()` does
-              // the same teardown without owning the exit, matching how
+              // telemetry flush was silently never running. `relinquishLock()`
+              // does the same teardown without owning the exit, matching how
               // `runGracefulShutdown` in dev-server.mts drives it; the
               // `finally` below performs the exit instead.
               //
@@ -2431,8 +2489,7 @@ export async function dev(options: {
                 logger,
                 removeIntegrationCache: () =>
                   aiService?.removeIntegrationCache(),
-                shutdownLockService: () =>
-                  lockService?.shutdown({ serverInitiated: false }),
+                relinquishLock: () => lockService?.relinquishLock(),
               });
             } finally {
               // The only exit on this path now that the lock service no longer
@@ -2489,15 +2546,14 @@ export async function dev(options: {
             }),
           );
           try {
-            // `shutdown()`, NOT `shutdownAndExit()` — same reason as the
+            // `relinquishLock()`, NOT `shutdownAndExit()` — same reason as the
             // sync/lock catch above: `shutdownAndExit()` exits the process
             // synchronously in its own `finally`, which made everything
             // sequenced after it unreachable.
             await runFatalExitShutdown({
               logger,
               removeIntegrationCache: () => aiService?.removeIntegrationCache(),
-              shutdownLockService: () =>
-                lockService?.shutdown({ serverInitiated: false }),
+              relinquishLock: () => lockService?.relinquishLock(),
             });
           } finally {
             // The only exit on this path; here so a thrown shutdown path can't
@@ -2695,7 +2751,8 @@ export async function dev(options: {
           logger.warn(`Error removing integration cache: ${error}`);
         });
         lockService?.shutdownAndExit().catch(() => {
-          // this is redundant, but it's here to make sure the lock service is shutdown and the process exits
+          // Redundant — `shutdownAndExit` exits from its own `finally` — but
+          // kept so the process still goes away if that ever stops being true.
           process.exit(1);
         });
       });
@@ -3094,7 +3151,7 @@ async function ensureRuntimeDbfsBranchConsistency({
   currentBranchName: string;
 }): Promise<string> {
   interface BranchSwitchingLockService {
-    isLocked: boolean;
+    isLockedWhenSettled(): Promise<boolean>;
     switchBranch(
       nextBranchName: string,
       options?: { reacquireLock?: boolean },
@@ -3124,7 +3181,8 @@ async function ensureRuntimeDbfsBranchConsistency({
 
   const lockSvc = lockService as unknown as BranchSwitchingLockService;
   const syncSvc = syncService as unknown as BranchSwitchingSyncService;
-  const wasLocked = lockSvc.isLocked;
+  // Retain the pre-switch state for explicit fallback and rollback paths.
+  const wasLocked = await lockSvc.isLockedWhenSettled();
   logger.info(
     `Switching runtime DBFS branch context from '${currentBranchName}' to '${targetBranchName}'`,
   );
@@ -3132,14 +3190,12 @@ async function ensureRuntimeDbfsBranchConsistency({
   try {
     syncSvc.setBranchName(targetBranchName);
     try {
-      await lockSvc.switchBranch(targetBranchName, {
-        reacquireLock: wasLocked,
-      });
+      await lockSvc.switchBranch(targetBranchName);
     } catch (switchError) {
       // Disconnecting native git can invalidate the previous live branch
       // context. Fall back to explicit release/reacquire on the target branch.
       logger.warn(
-        `Lock branch transfer failed for '${currentBranchName}' -> '${targetBranchName}', performing shutdown-style lock reset: ${switchError instanceof Error ? switchError.message : String(switchError)}`,
+        `Lock branch transfer failed for '${currentBranchName}' -> '${targetBranchName}', performing an explicit release and reacquire: ${switchError instanceof Error ? switchError.message : String(switchError)}`,
       );
       await lockSvc.switchBranch(targetBranchName, { reacquireLock: false });
       if (wasLocked) {
@@ -3156,7 +3212,7 @@ async function ensureRuntimeDbfsBranchConsistency({
     syncSvc.setBranchName(currentBranchName);
     try {
       await lockSvc.switchBranch(currentBranchName, {
-        reacquireLock: lockSvc.isLocked || wasLocked,
+        reacquireLock: (await lockSvc.isLockedWhenSettled()) || wasLocked,
       });
     } catch (rollbackError) {
       logger.warn(

package/src/dev-utils/dev-server.mts

@@ -69,11 +69,12 @@ import {
   type DevServerFailureType,
   devServerMetrics,
 } from "./dev-server-metrics.mjs";
+import { isRecoverableShutdownError, parseIsWarm } from "./fatal-exit.mjs";
 import {
-  buildFatalExitLog,
-  isRecoverableShutdownError,
-  parseIsWarm,
-} from "./fatal-exit.mjs";
+  fatalAwareExitCode,
+  installFatalProcessBarrier,
+  type FatalProcessHandler,
+} from "./fatal-process-barrier.mjs";
 import { OPTIMIZE_DEPS_CONFIG } from "./optimize-deps-config.mjs";
 import { prepareInPlaceRestart } from "./prepare-in-place-restart.mjs";
 import { handleRecoverableBuildError } from "./recoverable-build-error.mjs";
@@ -546,7 +547,7 @@ export function buildStatusPayload<T extends object>(
   return { ...base, serverErrors: devServerStatus?.serverErrors ?? [] };
 }
 
-type ProcessErrorHandler = "uncaughtException" | "unhandledRejection";
+type ProcessErrorHandler = FatalProcessHandler;
 
 // Both listeners log a recoverable shutdown, but with different wording, and
 // these lines are what on-call greps when a pod stays up instead of restarting.
@@ -557,6 +558,59 @@ const RECOVERABLE_SHUTDOWN_LOG_MESSAGE: Record<ProcessErrorHandler, string> = {
     "Ignoring recoverable shutdown rejection (unhandledRejection)",
 };
 
+/**
+ * What the dev server needs of the lock service on its way out. Structural so a
+ * test does not have to stand up a real one.
+ */
+type ExitingLockService = Pick<
+  LockService,
+  "notifyClosedByServer" | "relinquishLock"
+>;
+
+/**
+ * Give the AppBranchLock to whoever should have it next, then let the caller
+ * exit.
+ *
+ * Which of the two things to do is the dev server's knowledge, not the lock
+ * service's — it used to be a `serverInitiated` flag passed down into a
+ * `shutdown()` that branched on it, which is how a lock service came to have an
+ * opinion about why a process was stopping.
+ *
+ * Normally this process is the one stopping, so the lock goes back: the
+ * heartbeat dies with the process, and anything not released here makes the
+ * replacement sandbox's `acquireLock()` fail until the server-side TTL expires
+ * — and the replacement is the entire point of exiting.
+ *
+ * When the server closed us, the lock is already gone. `/_sb_disconnect` is
+ * usually a session moving across local↔cloud, so releasing would take the lock
+ * from whoever is taking over. The editor is told instead, because it has to
+ * distinguish "the server closed you" from a socket dropping.
+ *
+ * Extracted so both branches are testable: `runGracefulShutdown` is a closure
+ * over a booted dev server, so a unit test cannot otherwise reach either one.
+ */
+export async function handOverLockOnExit(
+  lockService: ExitingLockService | undefined,
+  {
+    serverInitiated,
+    switchingTo,
+    initiatedByEmail,
+  }: {
+    serverInitiated: boolean;
+    switchingTo?: "local" | "cloud" | "none";
+    initiatedByEmail?: string;
+  },
+): Promise<void> {
+  if (!lockService) {
+    return;
+  }
+  if (serverInitiated) {
+    await lockService.notifyClosedByServer({ switchingTo, initiatedByEmail });
+    return;
+  }
+  await lockService.relinquishLock();
+}
+
 /**
  * Decides whether a process-level error keeps the pod alive, and performs the
  * recording for the cases that do. Returns `true` when the caller must return
@@ -871,7 +925,7 @@ export async function createDevServer({
   }): Promise<void> {
     try {
       stopMemoryMetrics();
-      await lockService?.shutdown({
+      await handOverLockOnExit(lockService, {
         serverInitiated,
         switchingTo,
         initiatedByEmail,
@@ -882,16 +936,23 @@ export async function createDevServer({
     } catch (e) {
       logger.error(`Error during graceful shutdown: ${e}`);
     } finally {
+      // The statement about this process, made by the thing that owns its exit.
+      // It used to be the last line of `LockService.shutdown()`, prefixed
+      // `[lock-service]` — a lock service announcing a process exit, which is
+      // the tangle this change removes.
+      //
+      // Load bearing: cli-system-tests waits on this exact substring.
+      logger.info("[dev-server] shutting down and exiting dev server");
       const closeTimeout = setTimeout(() => {
         logger.info("Dev server closed");
-        process.exit(0);
+        process.exit(fatalAwareExitCode());
       }, 1000); // Fallback to exit if the HTTP server doesn't close within 1 second
 
       // Then close the HTTP server
       httpServer.close(() => {
         logger.info("Dev server closed");
         clearTimeout(closeTimeout);
-        process.exit(0);
+        process.exit(fatalAwareExitCode());
       });
     }
   }
@@ -1266,18 +1327,11 @@ export async function createDevServer({
   // even if the pod is activated later.
   const isWarm = parseIsWarm(process.env.SUPERBLOCKS_WARM_STANDBY);
 
-  // Only the first fatal event writes a fatal-exit line and starts shutdown.
-  // Without this, one crash could write several lines: an unhandled rejection
-  // fires once per rejected promise, so a burst of failures (say a dead DB pool
-  // rejecting every in-flight query) would each write a line and each start
-  // shutdown, making one crash look like many in the logs and the crash count.
-  let fatalExitHandled = false;
-
   // Signal handlers attach `.catch` so a synchronous throw in
   // `runGracefulShutdown` (e.g. logger init or lockService shutdown throwing
   // before the first `await`) is logged rather than surfacing as an
   // unhandled rejection across N handlers (one per fired signal). Symmetric
-  // with the `uncaughtException` handler below.
+  // with the process barrier below.
   process.on("SIGINT", () => {
     logger.info("SIGINT received");
     gracefulShutdown({
@@ -1311,86 +1365,37 @@ export async function createDevServer({
     );
   });
 
-  // The `.finally` always ends the process once shutdown settles. If an earlier
-  // signal already ran shutdown, this handler still needs to exit; without the
-  // final `process.exit` the process could hang instead of stopping.
-  process.on("uncaughtException", (error) => {
-    if (fatalExitHandled) {
-      return;
-    }
-    if (
+  // Preload may already have armed this from a separate module instance
+  // (node_modules export vs this esbuild bundle). A second call updates
+  // shutdown hooks on the shared host state and does not register another
+  // pair of listeners.
+  installFatalProcessBarrier({
+    isNonFatal: (handler, reason) =>
       handleNonFatalProcessError({
-        devServerStatus,
         devServerMetrics,
-        handler: "uncaughtException",
-        logger,
-        reason: error,
-      })
-    ) {
-      return;
-    }
-    fatalExitHandled = true;
-    // Write the fatal-exit line first, and synchronously, so the reason reaches
-    // the logs before anything else runs. Shutdown below may finish first and
-    // call `process.exit(0)`, so the container's real exit code can be 0 even
-    // though this was a crash. That is why `exit_code=1` here is the code this
-    // handler means to use, not a promise of what the container reports: for the
-    // JS-handler lines, trust that the line exists (and the `signal` field) over
-    // its `exit_code` when comparing against the pod's exit status.
-    logger.error(
-      buildFatalExitLog({ handler: "uncaughtException", exitCode: 1, isWarm }),
-      getErrorMeta(error),
-    );
-    gracefulShutdown({
-      logger,
-      serverInitiated: false,
-      source: "uncaughtException",
-    })
-      .catch((shutdownError) => {
-        logger.error(
-          "Error during shutdown after uncaught exception:",
-          getErrorMeta(shutdownError),
-        );
-      })
-      .finally(() => process.exit(1));
-  });
-
-  // Without its own listener, Node turns an unhandled promise rejection into an
-  // uncaught exception, which would log it under the wrong cause. Handle it here
-  // so a rejection is labelled as a rejection, then exit through the same
-  // shutdown path as an uncaught exception.
-  process.on("unhandledRejection", (reason) => {
-    if (fatalExitHandled) {
-      return;
-    }
-    if (
-      handleNonFatalProcessError({
         devServerStatus,
-        devServerMetrics,
-        handler: "unhandledRejection",
+        handler,
         logger,
         reason,
-      })
-    ) {
-      return;
-    }
-    fatalExitHandled = true;
-    logger.error(
-      buildFatalExitLog({ handler: "unhandledRejection", exitCode: 1, isWarm }),
-      getErrorMeta(reason),
-    );
-    gracefulShutdown({
-      logger,
-      serverInitiated: false,
-      source: "unhandledRejection",
-    })
-      .catch((shutdownError) => {
+      }),
+    isWarm,
+    log: (message, meta) => logger.error(message, meta),
+    onFatal: async (handler) => {
+      try {
+        await gracefulShutdown({
+          logger,
+          serverInitiated: false,
+          source: handler,
+        });
+      } catch (shutdownError) {
         logger.error(
-          "Error during shutdown after unhandled rejection:",
+          handler === "uncaughtException"
+            ? "Error during shutdown after uncaught exception:"
+            : "Error during shutdown after unhandled rejection:",
           getErrorMeta(shutdownError),
         );
-      })
-      .finally(() => process.exit(1));
+      }
+    },
   });
 
   if (existingServer) {

package/src/dev-utils/dev-server.shutdown-lock.test.mts

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { handOverLockOnExit } from "./dev-server.mjs";
+
+/**
+ * ENG-6128. The dev server's exit path used to drive the lock service through a
+ * `shutdown({ serverInitiated })` that decided, inside the lock service, whether
+ * to release. That flag is the dev server's knowledge, not the lock service's,
+ * and getting it wrong in either direction is a live-edit outage: releasing a
+ * lock the server has already reassigned takes the app away from the session
+ * taking over, and failing to release on a normal exit makes the replacement
+ * sandbox wait out the TTL.
+ */
+describe("handOverLockOnExit", () => {
+  const makeLockService = () => ({
+    notifyClosedByServer: vi.fn(async () => undefined),
+    relinquishLock: vi.fn(async () => undefined),
+  });
+
+  it("hands the lock back when the dev server is the one stopping", async () => {
+    const lockService = makeLockService();
+
+    await handOverLockOnExit(lockService, { serverInitiated: false });
+
+    // Prompt release is the whole recovery story for this path: the heartbeat
+    // dies with the process, so anything not released here blocks the
+    // replacement sandbox for the two-minute TTL.
+    expect(lockService.relinquishLock).toHaveBeenCalledOnce();
+    expect(lockService.notifyClosedByServer).not.toHaveBeenCalled();
+  });
+
+  it("only notifies when the server closed the session", async () => {
+    const lockService = makeLockService();
+
+    await handOverLockOnExit(lockService, {
+      serverInitiated: true,
+      switchingTo: "local",
+      initiatedByEmail: "someone@example.com",
+    });
+
+    // The server has already taken the lock — on a local↔cloud switch it now
+    // belongs to the session taking over, so releasing would take it away from
+    // them.
+    expect(lockService.relinquishLock).not.toHaveBeenCalled();
+    expect(lockService.notifyClosedByServer).toHaveBeenCalledWith({
+      switchingTo: "local",
+      initiatedByEmail: "someone@example.com",
+    });
+  });
+
+  it("is a no-op when the dev server never had a lock service", async () => {
+    // Startup can fail before the lock service exists, and the exit path still
+    // runs.
+    await expect(
+      handOverLockOnExit(undefined, { serverInitiated: false }),
+    ).resolves.toBeUndefined();
+  });
+});