@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

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

@@ -8,9 +8,11 @@ import { beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import { packageJsonSnapshot } from "./package-json-snapshot.mjs";
 
 const execMock = vi.fn();
+const execFileMock = vi.fn();
 vi.mock("node:child_process", () => ({
-  default: { exec: execMock },
+  default: { exec: execMock, execFile: execFileMock },
   exec: execMock,
+  execFile: execFileMock,
 }));
 
 vi.mock("node:readline", () => ({
@@ -83,7 +85,12 @@ vi.mock("colorette", () => ({
   green: (s: string) => s,
 }));
 
-vi.mock("@superblocksteam/shared", () => ({
+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 {},
@@ -104,6 +111,12 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
     initialize = vi.fn(async () => undefined);
     removeIntegrationCache = vi.fn(async () => undefined);
     chatSessionStore = { invalidateCache: vi.fn() };
+    // `dev.mts` reads this at startup for two paths: `syncHomeNpmrc`
+    // (APPS-4231 home `~/.npmrc` writer) and the startup `installPackages`
+    // call (APPS-4251 per-org `allow_install_scripts`). Returning undefined
+    // keeps the install path on the "no policy resolved" branch and is also
+    // valid input for the mocked-out `syncHomeNpmrc`.
+    getNpmRegistryClient = vi.fn(() => undefined);
   },
   AiServiceFeatureFlags: class {
     static create = vi.fn(() => ({}));
@@ -115,6 +128,21 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
   stripResolvedFromLockfile: vi.fn(async () => undefined),
 }));
 
+vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", () => ({
+  shouldIgnoreInstallScripts: vi.fn(() => false),
+  // Used by the dependency-install-classifier reachable from installPackages'
+  // catch path (APPS-4450). Previously the only test that hit this codepath
+  // (`logs a structured error when the background install fails`) didn't
+  // assert classification, so the missing exports surfaced silently as a
+  // ReferenceError instead of an InitialInstallFailed. The new
+  // restart-vs-degrade test depends on installPackages re-throwing an actual
+  // InitialInstallFailed marker, so stub all classifier-required exports.
+  scrubSecrets: vi.fn((value: string) => value),
+  parseNpmJsonDiagnostic: vi.fn(() => ""),
+  parseNpmJsonError: vi.fn(() => null),
+  classifyNpmExecStderr: vi.fn(() => null),
+}));
+
 vi.mock("@superblocksteam/vite-plugin-file-sync/git-service", () => ({
   createGitService: vi.fn(async () => undefined),
 }));
@@ -187,6 +215,25 @@ 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 these tests stay focused on the
+// DBFS / S3 restore behaviour. 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 () => ({
+    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", () => ({
@@ -246,6 +293,8 @@ function buildDevOptions(overrides: Record<string, unknown> = {}) {
     tokenManager: {
       getToken: vi.fn(() => "test-token"),
       onTokenRefresh: vi.fn(),
+      updateToken: vi.fn(),
+      getCurrentToken: vi.fn(() => "test-token"),
     },
     getCurrentToken: vi.fn(() => "test-token"),
     sdk: buildMockSdk(),
@@ -718,29 +767,26 @@ describe("dev background package install join semantics", () => {
   it("logs a structured error when the background install fails", async () => {
     const deferred = setupDeferredInstallMock({ fail: true });
     // Use upgradePromises so the install runs without forcing the upload
-    // path — the failure then propagates through the pre-Vite join, whose
-    // outer catch only sets the span status and rethrows (no process.exit,
-    // which vitest replaces with a throw that becomes an unhandled error).
+    // path — the failure propagates through the pre-Vite join. With the
+    // dependency-install-classifier fully wired in tests, the rejection is
+    // an InitialInstallFailed marker and `handleStartupError` routes it to
+    // "degrade" (Vite still starts up, dev() resolves with the error
+    // recorded on devServerStatus). The point of THIS test is the
+    // independent `.catch` backstop on packageInstallPromise — it must
+    // log a structured error regardless of which downstream join consumes
+    // the rejection.
     mockCheckVersions.mockResolvedValue({
       cliUpdated: false,
       upgradePromises: [Promise.resolve()],
     });
     const { dev } = await import("./dev.mjs");
 
-    // Pre-attach a catcher so vitest's unhandled-rejection detector observes
-    // the rejection synchronously with promise creation; without this, the
-    // .catch backstop's logging counts as a handler but lands on the
-    // microtask queue after vitest's check.
-    let caughtError: unknown;
-    const devPromise = dev(buildDevOptions() as any).catch((err: unknown) => {
-      caughtError = err;
-    });
+    const devPromise = dev(buildDevOptions() as any).catch(() => undefined);
 
     await deferred.awaitInstallStarted();
     await deferred.finishInstall();
     await devPromise;
 
-    expect(caughtError).toBeDefined();
     // The .catch backstop fires regardless and tags the log with errorId so
     // alert rules can match without needing typed attributes.
     expect(
@@ -752,4 +798,154 @@ describe("dev background package install join semantics", () => {
       ),
     ).toBe(true);
   });
+
+  // APPS-4450 review: an InitialInstallFailed observed in the "before upload"
+  // join must NOT preempt a successful CLI upgrade restart. Previously the
+  // join's rejection was caught by the outer sync/setup catch (→ degrade) and
+  // execution never reached the `hasCliUpdated` branch, so the restart was
+  // silently dropped. The fix catches the join locally when `hasCliUpdated`
+  // and falls through to the restart block.
+  it("prioritises CLI restart over install-failure degrade when both fire in the upload path", async () => {
+    const deferred = setupDeferredInstallMock({ fail: true });
+    // CLI upgrade succeeds + `forcePackageInstall` triggers the upload path.
+    mockCheckVersions.mockResolvedValue({
+      cliUpdated: true,
+      upgradePromises: [Promise.resolve()],
+    });
+
+    // Capture `process.exit` synchronously; the production path calls it on
+    // the restart with AUTO_UPGRADE_EXIT_CODE (mocked to 99). Track every
+    // call and throw a tagged error so the test can assert the exit code
+    // without actually terminating the vitest worker. We replace
+    // `process.exit` directly instead of `vi.spyOn` — vitest's `process`
+    // object is partially shadowed and `vi.spyOn(process, "exit")` swallows
+    // calls intermittently here.
+    const originalExit = process.exit;
+    const exitCalls: Array<number | undefined> = [];
+    (process as any).exit = (code?: number) => {
+      exitCalls.push(code);
+      throw new Error(`__test_process_exit__:${String(code)}`);
+    };
+
+    try {
+      const { dev } = await import("./dev.mjs");
+
+      let caughtError: unknown;
+      const devPromise = dev(
+        buildDevOptions({ forcePackageInstall: true }) as any,
+      ).catch((err: unknown) => {
+        caughtError = err;
+      });
+
+      await deferred.awaitInstallStarted();
+      await deferred.finishInstall();
+      await devPromise;
+
+      // First exit call MUST be the CLI-restart with AUTO_UPGRADE_EXIT_CODE
+      // (mocked to 99). The throw escapes through the outer catch, which
+      // routes the non-InitialInstallFailed thrown wrapper through
+      // handleStartupError → exit, so a follow-up `process.exit(1)` is
+      // expected and benign. The invariant is the FIRST call.
+      expect(exitCalls[0]).toBe(99);
+      // devPromise resolved (or rejected) after the chain settled.
+      expect(caughtError).toBeDefined();
+      // Upload was skipped — install failed before the upload body could run
+      // and the local catch routed straight to the restart branch.
+      expect(mockSyncService.uploadDirectory).not.toHaveBeenCalled();
+      expect(mockSyncService.uploadDirectoryNowIfNeeded).not.toHaveBeenCalled();
+      // Restart actually got reached (logged + skip-upload reason logged).
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        "CLI was updated, restarting the dev server…",
+      );
+      expect(
+        mockLogger.info.mock.calls.some(
+          (call) =>
+            typeof call[0] === "string" &&
+            call[0].includes(
+              "Initial package install failed before startup upload",
+            ),
+        ),
+      ).toBe(true);
+    } finally {
+      (process as any).exit = originalExit;
+    }
+  });
+
+  // APPS-4450 review (companion to above): the new local try/catch in the
+  // upload path must only swallow `InitialInstallFailed`. A non-marker
+  // rejection from `joinUpgradeThenInstall("before upload")` (e.g. a failed
+  // package upgrade) must rethrow so the outer sync/setup catch routes it to
+  // `process.exit(1)` — even when `hasCliUpdated` is true. Otherwise an
+  // upgrade rejection could be silently dropped on the upload path.
+  it("rethrows non-InitialInstallFailed join errors so the outer catch exits", async () => {
+    // Install succeeds instantly — only the UPGRADE rejects, so the join's
+    // first await (`joinPackageUpgrade`) is what surfaces.
+    execMock.mockImplementation(
+      (
+        _cmd: string,
+        opts: unknown,
+        cb?: (err: Error | null, result?: { stdout: string }) => void,
+      ) => {
+        const callback =
+          typeof opts === "function"
+            ? (opts as (err: Error | null, result?: { stdout: string }) => void)
+            : cb;
+        callback?.(null, { stdout: "installed" });
+      },
+    );
+    // hasCliUpdated=true ensures we'd hit the restart branch IF the local
+    // catch wrongly swallowed the rejection. A rejecting upgrade promise
+    // surfaces a generic Error (not InitialInstallFailed), so the local catch
+    // must rethrow.
+    mockCheckVersions.mockResolvedValue({
+      cliUpdated: true,
+      upgradePromises: [Promise.reject(new Error("simulated upgrade failure"))],
+    });
+
+    const originalExit = process.exit;
+    const exitCalls: Array<number | undefined> = [];
+    (process as any).exit = (code?: number) => {
+      exitCalls.push(code);
+      throw new Error(`__test_process_exit__:${String(code)}`);
+    };
+
+    try {
+      const { dev } = await import("./dev.mjs");
+
+      let caughtError: unknown;
+      await dev(buildDevOptions({ forcePackageInstall: true }) as any).catch(
+        (err: unknown) => {
+          caughtError = err;
+        },
+      );
+
+      // First exit MUST be the outer-catch exit(1), NOT the
+      // AUTO_UPGRADE_EXIT_CODE (99). If the local catch wrongly swallowed
+      // the upgrade rejection, execution would fall through to the
+      // `if (hasCliUpdated)` restart branch and call exit(99).
+      expect(exitCalls[0]).toBe(1);
+      expect(exitCalls[0]).not.toBe(99);
+      expect(caughtError).toBeDefined();
+      // Upload skipped — join rejected before the upload body could run.
+      expect(mockSyncService.uploadDirectory).not.toHaveBeenCalled();
+      expect(mockSyncService.uploadDirectoryNowIfNeeded).not.toHaveBeenCalled();
+      // Restart was NOT reached — outer catch exited before that block.
+      expect(mockLogger.info).not.toHaveBeenCalledWith(
+        "CLI was updated, restarting the dev server…",
+      );
+      // The skip-upload-for-restart log must NOT fire either; it's gated on
+      // the `InitialInstallFailed` branch of the local catch.
+      expect(
+        mockLogger.info.mock.calls.some(
+          (call) =>
+            typeof call[0] === "string" &&
+            call[0].includes(
+              "Initial package install failed before startup upload",
+            ),
+        ),
+      ).toBe(false);
+    } finally {
+      (process as any).exit = originalExit;
+    }
+  });
 });

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

@@ -14,9 +14,11 @@ import {
 } from "vitest";
 
 const execMock = vi.fn();
+const execFileMock = vi.fn();
 vi.mock("node:child_process", () => ({
-  default: { exec: execMock },
+  default: { exec: execMock, execFile: execFileMock },
   exec: execMock,
+  execFile: execFileMock,
 }));
 
 vi.mock("node:readline", () => ({
@@ -89,7 +91,12 @@ vi.mock("colorette", () => ({
   green: (s: string) => s,
 }));
 
-vi.mock("@superblocksteam/shared", () => ({
+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 {},
@@ -110,6 +117,7 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
     initialize = vi.fn(async () => undefined);
     removeIntegrationCache = vi.fn(async () => undefined);
     chatSessionStore = { invalidateCache: vi.fn() };
+    getNpmRegistryClient = vi.fn(() => undefined);
   },
   AiServiceFeatureFlags: class {
     static create = vi.fn(() => ({}));
@@ -121,6 +129,10 @@ vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
   stripResolvedFromLockfile: vi.fn(async () => undefined),
 }));
 
+vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", () => ({
+  shouldIgnoreInstallScripts: vi.fn(() => false),
+}));
+
 const { startupOpLog, buildMockGitService } = vi.hoisted(() => {
   const startupOpLog: string[] = [];
   function buildMockGitService(cwd: string) {
@@ -254,6 +266,25 @@ 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 () => ({
+    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", () => ({
@@ -330,6 +361,8 @@ function buildDevOptions(cwd: string, overrides: Record<string, unknown> = {}) {
     tokenManager: {
       getToken: vi.fn(() => "test-token"),
       onTokenRefresh: vi.fn(),
+      updateToken: vi.fn(),
+      getCurrentToken: vi.fn(() => "test-token"),
     },
     getCurrentToken: vi.fn(() => "test-token"),
     sdk: buildMockSdk(),

package/src/cli-replacement/dev-token-priming.test.mts

@@ -0,0 +1,103 @@
+/**
+ * Tests for the cold-start `TokenManager` priming step (APPS-4231 follow-up).
+ *
+ * Background
+ * ----------
+ * `NpmRegistryClient.getJwt()` (`packages/vite-plugin-file-sync/src/ai-service/index.ts`)
+ * has two bearer-credential sources:
+ *   1. `tokenManagerJwt`, seeded synchronously at `AiService` construction
+ *      from `tokenManager.getCurrentToken()` and kept current via the
+ *      `tokenUpdated` listener for future refreshes.
+ *   2. `clark?.context?.jwt`, primed lazily by the first socket RPC's
+ *      `peerAuthorization` header (`socket-manager.ts`).
+ *
+ * `TokenManager.updateToken()` has exactly one production writer outside
+ * `dev()` itself: `AuthHotReloadServer` (`auth-hot-reload.mts`). That socket
+ * is explicitly disabled on live-edit pods (SABS sets
+ * `SUPERBLOCKS_AUTH_HOT_RELOAD=false`). So on cold start neither source is
+ * primed until the UI socket lands — which is AFTER `syncHomeNpmrc` and
+ * AFTER the AiService's `TemplateRenderer` prefetch fires.
+ *
+ * The CLI does have a usable token in scope at `dev()` entry
+ * (`tokenConfig.token`, sourced from auth.json or `/_sb_activate`).
+ * `primeTokenManagerWithInitialToken` seeds it. Because `TokenManager`
+ * retains the current token as state and consumers read it synchronously
+ * during construction (see `getCurrentToken()` on `ITokenManager`), the
+ * call-site ordering between the prime and consumer construction is NOT
+ * load-bearing: the seed reaches AiService whether the prime fires before
+ * or after `new AiService(...)`.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { TokenManager } from "../dev-utils/token-manager.js";
+import { primeTokenManagerWithInitialToken } from "./dev.mjs";
+
+describe("primeTokenManagerWithInitialToken", () => {
+  it("emits a `tokenUpdated` event carrying the supplied token to listeners subscribed before the call", () => {
+    const tokenManager = new TokenManager();
+    const events: string[] = [];
+    tokenManager.on("tokenUpdated", (event) => {
+      events.push(event.token);
+    });
+
+    primeTokenManagerWithInitialToken(tokenManager, "jwt-from-cold-start");
+
+    expect(events).toEqual(["jwt-from-cold-start"]);
+  });
+
+  it("no-ops when the token is empty (no spurious `tokenUpdated` event)", () => {
+    const tokenManager = new TokenManager();
+    const events: string[] = [];
+    tokenManager.on("tokenUpdated", (event) => {
+      events.push(event.token);
+    });
+
+    primeTokenManagerWithInitialToken(tokenManager, "");
+
+    expect(events).toEqual([]);
+  });
+});
+
+describe("TokenManager state retention (cold-start contract)", () => {
+  it("exposes the primed token via getCurrentToken() to consumers constructed AFTER the prime call", () => {
+    // This is what makes the dev.mts call site order-independent. AiService
+    // reads tokenManager.getCurrentToken() synchronously in its constructor
+    // to seed `tokenManagerJwt` — so even if `dev()` primes BEFORE
+    // `new AiService(...)`, the seed survives.
+    const tokenManager = new TokenManager();
+    primeTokenManagerWithInitialToken(tokenManager, "seed-jwt");
+
+    expect(tokenManager.getCurrentToken()).toBe("seed-jwt");
+  });
+
+  it("returns undefined from getCurrentToken() when no token has been set", () => {
+    const tokenManager = new TokenManager();
+
+    expect(tokenManager.getCurrentToken()).toBeUndefined();
+  });
+
+  it("does NOT auto-replay prior emissions to late-attached listeners", () => {
+    // Deliberate: auto-replaying would cause refresh-handling subscribers
+    // (e.g. AutoConnectingRpcClient, which closes and reconnects the socket
+    // on every `tokenUpdated`) to fire on what is conceptually a seed read.
+    // Late-attached subscribers MUST opt in via `getCurrentToken()` if they
+    // need the current value at attach time; the event channel is for
+    // changes only.
+    const tokenManager = new TokenManager();
+    primeTokenManagerWithInitialToken(tokenManager, "abc");
+
+    const lateListener = vi.fn();
+    tokenManager.on("tokenUpdated", lateListener);
+
+    expect(lateListener).not.toHaveBeenCalled();
+  });
+
+  it("overwrites the stored token on each updateToken call so refreshes win", () => {
+    const tokenManager = new TokenManager();
+    primeTokenManagerWithInitialToken(tokenManager, "first");
+    tokenManager.updateToken("second");
+
+    expect(tokenManager.getCurrentToken()).toBe("second");
+  });
+});

package/src/cli-replacement/dev.interception.test.mts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import { InitialInstallFailed } from "./dependency-install-classifier.mjs";
+import { handleStartupError } from "./dev.mjs";
+
+// Mock the metrics module so we can assert recordInitialInstallFailure calls.
+// vi.mock is hoisted, so we use vi.hoisted to declare the spy before the factory.
+const { recordInitialInstallFailureMock } = vi.hoisted(() => ({
+  recordInitialInstallFailureMock: vi.fn(),
+}));
+vi.mock("../dev-utils/dev-server-metrics.mjs", () => ({
+  devServerMetrics: {
+    recordInitialInstallFailure: recordInitialInstallFailureMock,
+    flush: vi.fn(),
+    recordEndpoint: vi.fn(),
+    recordSocketUpgrade: vi.fn(),
+    recordViteEagerInit: vi.fn(),
+    recordWarmPrewarm: vi.fn(),
+    recordWarmActivation: vi.fn(),
+    recordWarmHandoff: vi.fn(),
+  },
+}));
+
+const makeLogger = () =>
+  ({ error: () => {}, info: () => {}, warn: () => {} }) as any;
+
+beforeEach(() => {
+  recordInitialInstallFailureMock.mockClear();
+});
+
+describe("handleStartupError", () => {
+  it("records + does NOT exit for InitialInstallFailed", () => {
+    const status = { serverErrors: [] as any[] };
+    const marker = new InitialInstallFailed({
+      type: "dev-server/dependency-install",
+      timestamp: "t",
+      category: "dependency_conflict",
+      rawError: "x",
+    });
+    const decision = handleStartupError(marker, status, makeLogger());
+    expect(decision).toBe("degrade");
+    expect(status.serverErrors).toHaveLength(1);
+  });
+
+  it("emits the install-failure metric with category on the degrade path", () => {
+    const status = { serverErrors: [] as any[] };
+    const marker = new InitialInstallFailed({
+      type: "dev-server/dependency-install",
+      timestamp: "t",
+      category: "registry_auth_failed",
+      npmErrorCode: "E401",
+      hasAnyRegistryConfigured: true,
+      rawError: "x",
+    });
+    handleStartupError(marker, status, makeLogger());
+    expect(recordInitialInstallFailureMock).toHaveBeenCalledOnce();
+    expect(recordInitialInstallFailureMock).toHaveBeenCalledWith({
+      category: "registry_auth_failed",
+      npmErrorCode: "E401",
+      hasAnyRegistryConfigured: true,
+    });
+  });
+
+  it("does NOT emit the install-failure metric on the exit path", () => {
+    const status = { serverErrors: [] as any[] };
+    handleStartupError(new Error("lock failed"), status, makeLogger());
+    expect(recordInitialInstallFailureMock).not.toHaveBeenCalled();
+  });
+
+  it("exits for a non-marker error (upgrade / lock / sync)", () => {
+    const status = { serverErrors: [] as any[] };
+    const decision = handleStartupError(
+      new Error("lock failed"),
+      status,
+      makeLogger(),
+    );
+    expect(decision).toBe("exit");
+    expect(status.serverErrors).toHaveLength(0);
+  });
+});