@superblocksteam/sdk 2.0.157-next.4 → 2.0.157-next.5

package/src/cli-replacement/automatic-upgrades.ts

@@ -543,12 +543,10 @@ export async function checkVersionsAndWritePackageJson(
           getErrorMeta(error),
         );
         await traceFunction({
-          name: "shutdownLockService",
+          name: "relinquishLock",
           tracer,
           fn: async () => {
-            await lockService.shutdown({
-              serverInitiated: false,
-            });
+            await lockService.relinquishLock();
           },
         });
         hasFailedToUpgrade = true;
@@ -751,14 +749,9 @@ export async function checkVersionsAndWritePackageJson(
   // Restart CLI if anything was updated
   if (hasFailedToUpgrade) {
     try {
-      await lockService.shutdown({
-        serverInitiated: false,
-      });
+      await lockService.relinquishLock();
     } catch (error) {
-      logger.error(
-        "Error shutting down lock service and releasing lock",
-        getErrorMeta(error),
-      );
+      logger.error("Error handing the lock back", getErrorMeta(error));
     }
     process.exit(1);
   }

package/src/cli-replacement/dev-s3-restore.test.mts

@@ -174,9 +174,11 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/git-service", () => ({
 
 const mockLockService = {
   acquireLock: vi.fn(async () => undefined),
-  shutdown: vi.fn(async () => undefined),
+  relinquishLock: vi.fn(async () => undefined),
+  notifyClosedByServer: vi.fn(async () => undefined),
   shutdownAndExit: vi.fn(async () => undefined),
   setIsRestarting: vi.fn(),
+  setOnLockConflict: vi.fn(),
   isLocked: false,
   connectedUsers: [],
   wasRecentlyActive: false,
@@ -186,9 +188,11 @@ const mockLockService = {
 vi.mock("@superblocksteam/vite-plugin-file-sync/lock-service", () => ({
   LockService: class {
     acquireLock = mockLockService.acquireLock;
-    shutdown = mockLockService.shutdown;
+    relinquishLock = mockLockService.relinquishLock;
+    notifyClosedByServer = mockLockService.notifyClosedByServer;
     shutdownAndExit = mockLockService.shutdownAndExit;
     setIsRestarting = mockLockService.setIsRestarting;
+    setOnLockConflict = mockLockService.setOnLockConflict;
     isLocked = mockLockService.isLocked;
     connectedUsers = mockLockService.connectedUsers;
     wasRecentlyActive = mockLockService.wasRecentlyActive;

package/src/cli-replacement/dev-startup-git-before-dbfs-order.test.mts

@@ -224,9 +224,11 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/git-service", () => ({
 
 const mockLockService = {
   acquireLock: vi.fn(async () => undefined),
-  shutdown: vi.fn(async () => undefined),
+  relinquishLock: vi.fn(async () => undefined),
+  notifyClosedByServer: vi.fn(async () => undefined),
   shutdownAndExit: vi.fn(async () => undefined),
   setIsRestarting: vi.fn(),
+  setOnLockConflict: vi.fn(),
   isLocked: false,
   connectedUsers: [],
   wasRecentlyActive: false,
@@ -236,9 +238,11 @@ const mockLockService = {
 vi.mock("@superblocksteam/vite-plugin-file-sync/lock-service", () => ({
   LockService: class {
     acquireLock = mockLockService.acquireLock;
-    shutdown = mockLockService.shutdown;
+    relinquishLock = mockLockService.relinquishLock;
+    notifyClosedByServer = mockLockService.notifyClosedByServer;
     shutdownAndExit = mockLockService.shutdownAndExit;
     setIsRestarting = mockLockService.setIsRestarting;
+    setOnLockConflict = mockLockService.setOnLockConflict;
     isLocked = mockLockService.isLocked;
     connectedUsers = mockLockService.connectedUsers;
     wasRecentlyActive = mockLockService.wasRecentlyActive;

package/src/cli-replacement/dev-startup-lock-acquisition.test.mts

@@ -0,0 +1,573 @@
+import * as fs from "node:fs/promises";
+import * as http from "node:http";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type Mock,
+} from "vitest";
+
+const execMock = vi.fn();
+const execFileMock = vi.fn();
+vi.mock("node:child_process", () => ({
+  default: { exec: execMock, execFile: execFileMock },
+  exec: execMock,
+  execFile: execFileMock,
+}));
+
+vi.mock("node:readline", () => ({
+  default: {
+    createInterface: vi.fn(() => ({ question: vi.fn(), close: vi.fn() })),
+  },
+  createInterface: vi.fn(() => ({ question: vi.fn(), close: vi.fn() })),
+}));
+
+vi.mock("fs-extra", () => ({
+  default: {
+    existsSync: vi.fn(() => true),
+    readFileSync: vi.fn(() => "{}"),
+  },
+}));
+
+vi.mock("package-manager-detector/detect", () => ({
+  detect: vi.fn(async () => ({
+    name: "npm",
+    agent: "npm",
+    version: "10.0.0",
+  })),
+}));
+
+vi.mock("package-manager-detector", () => ({
+  resolveCommand: vi.fn(() => ({
+    command: "npm",
+    args: ["install", "--fund=false", "--audit=false"],
+  })),
+}));
+
+vi.mock("read-pkg", () => ({
+  readPackage: vi.fn(async () => ({
+    name: "test-app",
+    dependencies: { "@superblocksteam/library": "1.0.0" },
+  })),
+}));
+
+const mockLogger = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn(),
+};
+
+vi.mock("../telemetry/logging.js", () => ({
+  getLogger: () => mockLogger,
+  getErrorMeta: vi.fn(() => ({})),
+}));
+
+vi.mock("../telemetry/index.js", () => ({
+  getTracer: () => ({
+    startActiveSpan: vi.fn(
+      async (
+        _name: string,
+        fn: (span: {
+          end: () => void;
+          setStatus: () => void;
+        }) => Promise<unknown>,
+      ) => fn({ end: vi.fn(), setStatus: vi.fn() }),
+    ),
+  }),
+  isCloudPrem: false,
+  shutdownTelemetry: vi.fn(async () => true),
+}));
+
+vi.mock("@opentelemetry/api", () => ({
+  SpanStatusCode: { ERROR: 2 },
+}));
+
+vi.mock("colorette", () => ({
+  green: (s: string) => s,
+}));
+
+vi.mock("@superblocksteam/shared", async (importOriginal) => ({
+  // dev.mts now transitively loads @superblocksteam/shared (via the npm-error
+  // classifier re-exported from vite-plugin-file-sync/npm-registry — APPS-4450),
+  // pulling in many named exports (DeploymentTypeEnum, ISocket, …). Spread the
+  // real module so the closed overrides below don't have to enumerate them.
+  ...((await importOriginal()) as Record<string, unknown>),
+  buildGithubSuperblocksSyncWorkflow: vi.fn(),
+  buildGithubSuperblocksSyncWorkflowFromBaseUrl: vi.fn(),
+  ConflictError: class ConflictError extends Error {},
+  DEFAULT_NON_GIT_BRANCH: "__non_git__",
+  isGitHubRemoteUrl: vi.fn(() => false),
+  NotFoundError: class NotFoundError extends Error {},
+  SUPERBLOCKS_LIVE_GIT_BRANCH: "__live__",
+}));
+
+vi.mock("@superblocksteam/util", () => ({
+  maskUnixSignals: async function maskUnixSignals(fn: () => Promise<void>) {
+    return fn();
+  },
+}));
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
+  AiService: class {
+    initialize = vi.fn(async () => undefined);
+    notifyMigrationAppArtifactsReady = vi.fn();
+    removeIntegrationCache = vi.fn(async () => undefined);
+    remediateDeclaredDependencies = vi.fn(async () => undefined);
+    chatSessionStore = { invalidateCache: vi.fn() };
+    getNpmRegistryClient = mockGetNpmRegistryClient;
+  },
+  AiServiceFeatureFlags: class {
+    static create = vi.fn(() => ({}));
+  },
+  SnapshotManager: class {
+    executePendingRestore = vi.fn(async () => false);
+  },
+  hasEditLifecycleCapability: vi.fn(() => false),
+  isSdkApiTemplate: vi.fn(() => false),
+  stripResolvedFromLockfile: vi.fn(async () => undefined),
+}));
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", () => ({
+  shouldIgnoreInstallScripts: vi.fn(() => false),
+  maybeWriteNpmrcForDir: vi.fn(async () => {
+    // Delay before the log push so this test fails if syncHomeNpmrc is
+    // fire-and-forget (initiation order alone would still look correct).
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    startupOpLog.push("project-npmrc:maybeWriteNpmrcForDir");
+  }),
+}));
+
+const { startupOpLog, buildMockGitService, mockGetNpmRegistryClient } =
+  vi.hoisted(() => {
+    const startupOpLog: string[] = [];
+    const mockGetNpmRegistryClient = vi.fn(
+      ():
+        | {
+            getConfig: ReturnType<typeof vi.fn>;
+            organizationId: string;
+          }
+        | undefined => ({
+        organizationId: "org-1",
+        getConfig: vi.fn(async () => ({
+          source: "not-configured",
+          config: { configured: false },
+        })),
+      }),
+    );
+    function buildMockGitService(cwd: string) {
+      return {
+        workDir: cwd,
+        configure: vi.fn(async () => {
+          startupOpLog.push("git:configure");
+        }),
+        init: vi.fn(async () => {
+          startupOpLog.push("git:init");
+        }),
+        addRemote: vi.fn(async () => {
+          startupOpLog.push("git:addRemote");
+        }),
+        fetch: vi.fn(async () => {
+          startupOpLog.push("git:fetch");
+        }),
+        raw: vi.fn(async (args: string | string[]) => {
+          const argv = Array.isArray(args) ? args : [args];
+          startupOpLog.push(`git:raw:${argv.join(" ")}`);
+          if (argv[0] === "ls-remote" && argv.includes("__live__")) {
+            return "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef\trefs/heads/__live__\n";
+          }
+          if (argv[0] === "branch" && argv.includes("--show-current")) {
+            return "__live__\n";
+          }
+          if (argv[0] === "commit") {
+            return "";
+          }
+          return "";
+        }),
+        push: vi.fn(async () => {
+          startupOpLog.push("git:push");
+        }),
+        getDefaultBranch: vi.fn(async () => "main"),
+        getRemotes: vi.fn(async () => [
+          { name: "origin", refs: { fetch: "https://example.test/repo.git" } },
+        ]),
+        remote: vi.fn(async () => {
+          startupOpLog.push("git:remote");
+        }),
+        revparse: vi.fn(async (ref: string) => {
+          startupOpLog.push(`git:revparse:${ref}`);
+          return "abc123\n";
+        }),
+        checkout: vi.fn(async () => {
+          startupOpLog.push("git:checkout");
+        }),
+        checkoutOrCreate: vi.fn(async () => {
+          startupOpLog.push("git:checkoutOrCreate");
+        }),
+      };
+    }
+    return { startupOpLog, buildMockGitService, mockGetNpmRegistryClient };
+  });
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/git-service", () => ({
+  createGitService: vi.fn((cwd: string) => {
+    startupOpLog.push("createGitService");
+    return buildMockGitService(cwd);
+  }),
+}));
+
+const mockLockService = {
+  acquireLock: vi.fn(async () => undefined),
+  forceTakeover: vi.fn(async () => undefined),
+  inspectLock: vi.fn(async () => ({
+    ownerName: "someone@example.com",
+    canForceTakeover: false,
+    lockLifetimeMs: 60_000,
+    timeSinceLastActivityMs: 0,
+  })),
+  setOnLockConflict: vi.fn(),
+  relinquishLock: vi.fn(async () => undefined),
+  notifyClosedByServer: vi.fn(async () => undefined),
+  shutdownAndExit: vi.fn(async () => undefined),
+  setIsRestarting: vi.fn(),
+  isLocked: false,
+  // The git-service mock below simulates a live/target branch mismatch, which
+  // is what drives `ensureRuntimeDbfsBranchConsistency`. Both of the methods it
+  // calls have to exist here or the first one throws a TypeError that an outer
+  // catch swallows — leaving the suite green without ever having run the
+  // interaction.
+  isLockedWhenSettled: vi.fn(async () => false),
+  switchBranch: vi.fn(async () => undefined),
+  connectedUsers: [],
+  wasRecentlyActive: false,
+  timeSinceLastActivity: 0,
+};
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/lock-service", () => ({
+  LockService: class {
+    acquireLock = mockLockService.acquireLock;
+    forceTakeover = mockLockService.forceTakeover;
+    inspectLock = mockLockService.inspectLock;
+    setOnLockConflict = mockLockService.setOnLockConflict;
+    relinquishLock = mockLockService.relinquishLock;
+    notifyClosedByServer = mockLockService.notifyClosedByServer;
+    shutdownAndExit = mockLockService.shutdownAndExit;
+    setIsRestarting = mockLockService.setIsRestarting;
+    isLocked = mockLockService.isLocked;
+    isLockedWhenSettled = mockLockService.isLockedWhenSettled;
+    switchBranch = mockLockService.switchBranch;
+    connectedUsers = mockLockService.connectedUsers;
+    wasRecentlyActive = mockLockService.wasRecentlyActive;
+    timeSinceLastActivity = mockLockService.timeSinceLastActivity;
+  },
+  LockType: { CSB: "CSB", LOCAL: "LOCAL" },
+}));
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/operation-queue", () => ({
+  OperationQueue: class {
+    enqueue = vi.fn(async (fn: () => Promise<unknown>) => fn());
+  },
+}));
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/server-rpc", () => ({
+  AutoConnectingRpcClient: class {},
+}));
+
+const mockSyncService = {
+  downloadDirectory: vi.fn(async () => {
+    startupOpLog.push("dbfs:downloadDirectory");
+  }),
+  uploadDirectory: vi.fn(async () => undefined),
+  uploadDirectoryNowIfNeeded: vi.fn(async () => undefined),
+  cancelPendingSync: vi.fn(),
+};
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/sync-service", () => ({
+  SyncService: class {
+    downloadDirectory = mockSyncService.downloadDirectory;
+    uploadDirectory = mockSyncService.uploadDirectory;
+    uploadDirectoryNowIfNeeded = mockSyncService.uploadDirectoryNowIfNeeded;
+    cancelPendingSync = mockSyncService.cancelPendingSync;
+  },
+}));
+
+vi.mock("@superblocksteam/vite-plugin-file-sync/draft-interface", () => ({}));
+
+vi.mock("./version-detection.js", () => ({
+  getCurrentCliVersion: vi.fn(async () => ({
+    version: "2.0.0",
+    alias: undefined,
+  })),
+}));
+
+const mockCheckVersions = vi.fn(async () => ({
+  cliUpdated: false,
+  upgradePromises: [] as Promise<void>[],
+}));
+vi.mock("./automatic-upgrades.js", () => ({
+  checkVersionsAndWritePackageJson: (
+    ...args: Parameters<typeof mockCheckVersions>
+  ) => mockCheckVersions(...args),
+  buildInstallEnv: (userconfigPath: string) => ({
+    ...process.env,
+    NPM_CONFIG_USERCONFIG: userconfigPath,
+    PNPM_CONFIG_USERCONFIG: userconfigPath,
+  }),
+}));
+
+// The home `~/.npmrc` writer (APPS-4231) is a best-effort step that runs
+// before auto-upgrade. Mock it out here so this test stays focused on the
+// git-before-DBFS ordering. The `AiService` mock above exposes a minimal
+// `getNpmRegistryClient()` stub so the call site doesn't `TypeError`
+// and silently swallow this mock.
+vi.mock("./home-npmrc.mjs", () => ({
+  syncHomeNpmrc: vi.fn(async () => {
+    // Longer delay than maybeWriteNpmrcForDir: if both run without await,
+    // project pushes first and the order assertion fails.
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    startupOpLog.push("home-npmrc:syncHomeNpmrc");
+    return {
+      outcome: "skipped-not-configured",
+      path: "/tmp/.superblocks/npmrc",
+    };
+  }),
+  superblocksNpmrcPath: vi.fn(() => "/tmp/.superblocks/npmrc"),
+  superblocksLogsPath: vi.fn((appDir: string) => `${appDir}/.superblocks/logs`),
+}));
+
+vi.mock("./git-repo-setup.mjs", () => ({
+  ensureRemoteHasDefaultBranch: vi.fn(async () => undefined),
+  getGitErrorFields: vi.fn(() => ({})),
+}));
+
+const mockCreateDevServer = vi.fn(async () => http.createServer());
+vi.mock("../dev-utils/dev-server.mjs", () => ({
+  createDevServer: (...args: Parameters<typeof mockCreateDevServer>) =>
+    mockCreateDevServer(...args),
+}));
+
+vi.mock("../index.js", () => ({
+  AUTO_UPGRADE_EXIT_CODE: 99,
+}));
+
+const SERVER_DBFS_HASH = "dbfs-head-after-clark";
+
+function buildMockSdk() {
+  const hashLocalDirectory = vi
+    .fn()
+    .mockImplementationOnce(async () => {
+      startupOpLog.push("sdk:hashLocalDirectory:before-dbfs");
+      return { hash: "git-tree-without-uncommitted-clark-change" };
+    })
+    .mockImplementationOnce(async () => {
+      startupOpLog.push("sdk:hashLocalDirectory:after-dbfs");
+      return { hash: SERVER_DBFS_HASH };
+    });
+
+  return {
+    hashLocalDirectory,
+    dbfsGetApplicationDirectoryHash: vi.fn(async () => SERVER_DBFS_HASH),
+    getApplicationGitConfig: vi.fn(async () => ({
+      gitRemoteUrl: "https://github.com/example/superblocks-app.git",
+      hasCredential: false,
+    })),
+    fetchCurrentUser: vi.fn(async () => ({
+      user: {
+        id: "user-1",
+        name: "Test User",
+        email: "test@example.com",
+        currentOrganizationId: "org-1",
+      },
+      organizations: [{ id: "org-1", pluginExecutionVersions: {} }],
+      flagBootstrap: {},
+    })),
+    getFeatureFlagsForCurrentUser: vi.fn(async () => ({
+      devServerCloudInactivityTimeoutMinutes: () => 30,
+      devServerLocalInactivityTimeoutMinutes: () => 30,
+      enableSessionRecording: () => false,
+      removeManualCommitsEnabled: () => false,
+    })),
+    getFeatureFlagsForUser: vi.fn(() => ({
+      devServerCloudInactivityTimeoutMinutes: () => 30,
+      devServerLocalInactivityTimeoutMinutes: () => 30,
+    })),
+  };
+}
+
+function buildDevOptions(cwd: string, overrides: Record<string, unknown> = {}) {
+  return {
+    cwd,
+    downloadFirst: true,
+    autoUpgradeMode: "skip-upgrade",
+    applicationConfig: {
+      id: "app-test",
+      branchName: "main",
+    },
+    tokenConfig: {
+      superblocksBaseUrl: "https://example.test",
+      token: "test-token",
+    },
+    tokenManager: {
+      getToken: vi.fn(() => "test-token"),
+      onTokenRefresh: vi.fn(),
+      updateToken: vi.fn(),
+      getCurrentToken: vi.fn(() => "test-token"),
+    },
+    getCurrentToken: vi.fn(() => "test-token"),
+    sdk: buildMockSdk(),
+    ...overrides,
+  };
+}
+
+function setupExecMock() {
+  execMock.mockImplementation(
+    (
+      _cmd: string,
+      _opts: unknown,
+      cb?: (err: null, result: { stdout: string }) => void,
+    ) => {
+      startupOpLog.push("installPackages:exec");
+      if (typeof _opts === "function") {
+        (_opts as (err: null, result: { stdout: string }) => void)(null, {
+          stdout: "installed",
+        });
+      } else if (cb) {
+        cb(null, { stdout: "installed" });
+      }
+    },
+  );
+}
+
+describe("dev startup: who takes the live-edit lock, and when (ENG-6090)", () => {
+  let testCwd: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    delete process.env.SUPERBLOCKS_IS_CSB;
+    mockGetNpmRegistryClient.mockImplementation(() => ({
+      organizationId: "org-1",
+      getConfig: vi.fn(async () => ({
+        source: "not-configured",
+        config: { configured: false },
+      })),
+    }));
+    startupOpLog.length = 0;
+    setupExecMock();
+    mockCheckVersions.mockResolvedValue({
+      cliUpdated: false,
+      upgradePromises: [],
+    });
+    testCwd = await fs.mkdtemp(path.join(os.tmpdir(), "sb-dev-lock-acquire-"));
+    const { readPackage } = await import("read-pkg");
+    (readPackage as Mock).mockResolvedValue({
+      name: "test-app",
+      dependencies: { "@superblocksteam/library": "1.0.0" },
+    });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testCwd, { recursive: true, force: true });
+  });
+
+  it.each([
+    ["cloud", "true"],
+    ["local", undefined],
+  ])("does not take the lock at boot on the %s path", async (_name, isCsb) => {
+    if (isCsb) {
+      process.env.SUPERBLOCKS_IS_CSB = isCsb;
+    }
+    const { dev } = await import("./dev.mjs");
+
+    await dev(buildDevOptions(testCwd) as any);
+
+    // Nothing startup does is gated on holding the lock — not the DBFS
+    // download, not the package install, not the hash upload. Taking it before
+    // any client exists is holding it on behalf of nobody, which is the state
+    // the startup no-socket watchdog existed to clean up. A local dev server
+    // has no more claim to it at boot than a sandbox does: the browser tab
+    // that has not opened yet is the client, not the process.
+    expect(mockLockService.acquireLock).not.toHaveBeenCalled();
+    expect(mockLockService.forceTakeover).not.toHaveBeenCalled();
+    // ...and it still boots and serves.
+    expect(mockSyncService.downloadDirectory).toHaveBeenCalled();
+    expect(mockCreateDevServer).toHaveBeenCalled();
+  });
+
+  it("hands the conflict handler to the lock service instead of racing it at boot", async () => {
+    const { dev } = await import("./dev.mjs");
+
+    await dev(buildDevOptions(testCwd) as any);
+
+    // The reporting that used to wrap the boot-time acquire still exists; it is
+    // wired to where acquisition actually happens now.
+    expect(mockLockService.setOnLockConflict).toHaveBeenCalledWith(
+      expect.any(Function),
+    );
+  });
+
+  it("reports a conflict without stopping the dev server", async () => {
+    const { dev } = await import("./dev.mjs");
+    mockLockService.inspectLock.mockResolvedValueOnce({
+      ownerName: "someone@example.com",
+      canForceTakeover: false,
+      lockLifetimeMs: 120_000,
+      timeSinceLastActivityMs: 0,
+    });
+
+    await dev(buildDevOptions(testCwd) as any);
+    const onConflict = mockLockService.setOnLockConflict.mock.calls[0]![0];
+    await onConflict(new Error("Another user is currently editing this app."));
+
+    // Someone else holds it, so this client cannot edit — but the sandbox is
+    // still serving preview and the lock does not decide how long it lives.
+    expect(mockLockService.relinquishLock).not.toHaveBeenCalled();
+    expect(mockLockService.shutdownAndExit).not.toHaveBeenCalled();
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Could not take the live-edit lock"),
+    );
+  });
+
+  it("stops on an unresolvable conflict under the VS Code extension", async () => {
+    process.env.SUPERBLOCKS_VSCODE = "true";
+    const { shutdownTelemetry } = await import("../telemetry/index.js");
+    const exit = vi
+      .spyOn(process, "exit")
+      .mockImplementation(() => undefined as never);
+    const { dev } = await import("./dev.mjs");
+
+    await dev(buildDevOptions(testCwd) as any);
+    const onConflict = mockLockService.setOnLockConflict.mock.calls[0]![0];
+    await onConflict(new Error("Another user is currently editing this app."));
+
+    // The extension answers a takeover prompt by restarting this command with
+    // --force-takeover, and that hand-off has always ended with this process
+    // gone. Staying up would leave the replacement fighting us for the port.
+    expect(exit).toHaveBeenCalledWith(1);
+    // Through the same teardown as the other two fatal exits, not
+    // `shutdownAndExit`: that one exits synchronously from its own `finally`,
+    // which made the span end and the telemetry flush below it unreachable —
+    // so the trace for the conflict never left the process.
+    expect(mockLockService.shutdownAndExit).not.toHaveBeenCalled();
+    expect(mockLockService.relinquishLock).toHaveBeenCalled();
+    expect(shutdownTelemetry).toHaveBeenCalled();
+    exit.mockRestore();
+  });
+
+  it("honours an explicit force takeover at boot", async () => {
+    process.env.SUPERBLOCKS_IS_CSB = "true";
+    const { dev } = await import("./dev.mjs");
+
+    // The one thing that still acquires at boot, and it is not lock-type
+    // specific: someone asked for it by name.
+    await dev(buildDevOptions(testCwd, { forceTakeover: true }) as any);
+
+    expect(mockLockService.forceTakeover).toHaveBeenCalled();
+    expect(mockLockService.acquireLock).not.toHaveBeenCalled();
+  });
+});