@superblocksteam/sdk 2.0.129 → 2.0.130-next.1

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

@@ -15,6 +15,11 @@ import * as path from "node:path";
 
 import { describe, it, expect, beforeEach, vi } from "vitest";
 
+import type {
+  NpmInstallMetricInput,
+  NpmInstallSpanAttributes,
+} from "@superblocksteam/telemetry";
+
 import {
   buildGlobalInstallArgs,
   buildInstallEnv,
@@ -65,7 +70,12 @@ vi.mock("./version-detection.js", () => ({
 // either declare its mocks inline OR use `vi.hoisted()` to hoist the mock
 // fns alongside the mock registration. The latter lets us reuse the mocks
 // inside test bodies (e.g. `.mockReturnValue(...)`).
-const { stripUpgradedCliLockfilesMock, loggerMock } = vi.hoisted(() => {
+const {
+  stripUpgradedCliLockfilesMock,
+  loggerMock,
+  recordNpmInstallMock,
+  spanSetAttributeMock,
+} = vi.hoisted(() => {
   return {
     stripUpgradedCliLockfilesMock: vi.fn(async () => ({})),
     loggerMock: {
@@ -74,6 +84,29 @@ const { stripUpgradedCliLockfilesMock, loggerMock } = vi.hoisted(() => {
       error: vi.fn(),
       debug: vi.fn(),
     },
+    // APPS-4544: spy on the npm-install metric emit. The source calls
+    // `recordNpmInstall` once per `upgradeCliWithPackageManager` invocation
+    // (in a `finally`), so a test asserting the metric attributes is the
+    // contract we want pinned. We mock only this symbol — the rest of
+    // `@superblocksteam/telemetry` (sanitize/redact helpers, structured
+    // logger shims) is left untouched via `importOriginal` below.
+    //
+    // Signature is pinned to the real `recordNpmInstall` shape so the
+    // type-aware mock.calls[0] tuple resolves to `[NpmInstallMetricInput]`
+    // — otherwise `vi.fn(() => …)` infers `[]` and the test assertions
+    // can't index `[0]` without a cast.
+    recordNpmInstallMock: vi.fn<
+      (input: NpmInstallMetricInput) => NpmInstallSpanAttributes
+    >(() => ({
+      "npm.registry_host": "unknown",
+      "npm.outcome": "success",
+    })),
+    // APPS-4544: capture `span.setAttribute(...)` calls so the
+    // `upgradeCli`-span `outcome` attribute assertion can verify the
+    // emitted trace fact. The real OTel `Span#setAttribute` returns
+    // the span for chaining, but the source under test never chains,
+    // so a vi.fn with default `undefined` return is fine.
+    spanSetAttributeMock: vi.fn(),
   };
 });
 
@@ -106,12 +139,47 @@ vi.mock("@superblocksteam/shared", async (importOriginal) => {
     ...actual,
     NON_SB_ORG_UPDATE_ERROR: "non_sb_org_update_error",
     // traceFunction in tests is a passthrough — we just want the fn to run.
-    traceFunction: async ({ fn }: { fn: () => Promise<unknown> }) => {
-      return await fn();
+    // APPS-4544: pass a fake span so callbacks that set attributes
+    // (e.g. the `upgradeCli` outcome attribute) have somewhere to write,
+    // and the test can assert on the recorded calls. Callbacks that
+    // ignore the parameter are unaffected.
+    //
+    // ASSUMPTION (APPS-4544, scout F6): the SAME `spanSetAttributeMock` is
+    // handed to every nested `traceFunction` callback (`upgradeCli`,
+    // `upgradeCliWithOclif`, `upgradePackageWithPackageManager - cli`,
+    // `stripUpgradedCliLockfiles`, …). Today only the outer `upgradeCli`
+    // callback calls `span.setAttribute`, so assertions like
+    // `toHaveBeenCalledWith("outcome", "success")` are unambiguous. If a
+    // future inner fn starts setting span attributes, give it a dedicated
+    // span mock (or assert by call index) so its writes don't pollute the
+    // outcome assertions here.
+    traceFunction: async ({
+      fn,
+    }: {
+      fn: (span: {
+        setAttribute: typeof spanSetAttributeMock;
+      }) => Promise<unknown>;
+    }) => {
+      return await fn({ setAttribute: spanSetAttributeMock });
     },
   };
 });
 
+// APPS-4544: override only `recordNpmInstall`. The other npm-registry helpers
+// (`bucketNpmRegistryHost`, `normalizeInstallOutcome`,
+// `redactNpmRegistryHostsFromText`) the source still consumes must keep their
+// real implementations so the existing `[npm-install-blocked]` log assertions
+// continue to exercise the real bucket + redaction paths — a mocked
+// `bucketNpmRegistryHost` would silently mask a regression of the original
+// APPS-4381 fix.
+vi.mock("@superblocksteam/telemetry", async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...actual,
+    recordNpmInstall: recordNpmInstallMock,
+  };
+});
+
 // ---------------------------------------------------------------------------
 // Test fixtures
 // ---------------------------------------------------------------------------
@@ -140,6 +208,13 @@ beforeEach(() => {
   upgradeWithPackageManagerCalls.length = 0;
   // Restore default mock return values after `clearAllMocks` resets them.
   stripUpgradedCliLockfilesMock.mockImplementation(async () => ({}));
+  // APPS-4544: `clearAllMocks` wipes the implementation set in `vi.hoisted`,
+  // so re-pin the typed default so callers see a `NpmInstallSpanAttributes`
+  // return value instead of `undefined`.
+  recordNpmInstallMock.mockImplementation(() => ({
+    "npm.registry_host": "unknown",
+    "npm.outcome": "success",
+  }));
 
   // Mock global fetch used by getRemoteVersions
   global.fetch = vi.fn(async () => ({
@@ -770,6 +845,484 @@ describe("checkVersionsAndWritePackageJson", () => {
       );
     });
 
+    // -----------------------------------------------------------------
+    // APPS-4544: superblocks.npm.install.* metric emission for the
+    // CLI auto-upgrade runner. The structured `[npm-install-blocked]`
+    // log line above only fires on a perimeter block, so operators
+    // had no metric to alert on "auto-upgrade just failed everywhere"
+    // (vs. an isolated install in the app shell). These tests pin
+    // the metric attribute contract so a future refactor of
+    // `upgradeCliWithPackageManager` can't silently drop it.
+    // -----------------------------------------------------------------
+    it("APPS-4544: emits recordNpmInstall on the happy path with runner=auto_upgrade, outcome=success", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      // Drive the same flow as `mockNpmFallbackExec` but with a clean
+      // (no-error) exit so the metric records outcome="success".
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // Force fallback to the package-manager path.
+          cb?.(null, { stdout: "this version is not updatable\n", stderr: "" });
+          return {};
+        }
+        // Successful install — no error.
+        queueMicrotask(() => cb?.(null));
+        return { stdout: new EventEmitter(), stderr: new EventEmitter() };
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      // Post-install version validation must report the target version,
+      // otherwise `upgradeCliWithPackageManager` throws and the metric
+      // flips to `other` via the catch.
+      const versionDetection = await import("./version-detection.js");
+      vi.mocked(versionDetection.getCurrentCliVersion)
+        .mockResolvedValueOnce({ version: "2.0.0", alias: undefined }) // initial check (stale)
+        .mockResolvedValueOnce({
+          version: TARGET_CLI_VERSION,
+          alias: undefined,
+        }); // post-install validation
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+      await Promise.all(result.upgradePromises);
+
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args).toMatchObject({
+        runner: "auto_upgrade",
+        outcome: "success",
+        // No private registry was configured for this test, so the
+        // `configured` boolean falls through to its default (false).
+        configured: false,
+      });
+      expect(typeof args.durationMs).toBe("number");
+      expect(args.durationMs).toBeGreaterThanOrEqual(0);
+      // On the happy path no classifier ever ran, so the call site
+      // leaves `registryHost` undefined; the emitter coerces it to
+      // `unknown` via `bucketNpmRegistryHost`.
+      expect(args.registryHost).toBeUndefined();
+    });
+
+    it("APPS-4544: emits outcome=registry_unreachable on ECONNREFUSED so the auto_upgrade runner is alertable separately from happy upgrades", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code ECONNREFUSED",
+          "npm error errno ECONNREFUSED",
+          "npm error network request to https://registry.npmjs.org/@superblocksteam%2fcli failed, reason: connect ECONNREFUSED 127.0.0.1:443",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args.runner).toBe("auto_upgrade");
+      // Raw `NpmInstallBlocked.reason` flows through; the emitter
+      // aliases it to the short `unreachable` outcome internally
+      // (`normalizeInstallOutcome`), which the cardinality test in
+      // `emitter.test.ts` already pins.
+      expect(args.outcome).toBe("registry_unreachable");
+      // The classifier extracted the public-npm host from the stderr
+      // line, so it appears here unbucketed (`recordNpmInstall` does
+      // the bucketing). This pins that we DO pass it through, since
+      // otherwise the public/private split on the metric would be
+      // dropped for genuine registry failures.
+      expect(args.registryHost).toMatch(/registry\.npmjs\.org/);
+    });
+
+    it("APPS-4544: emits outcome=registry_auth_failed and the private registry host on E401 (the emitter buckets host at the emit boundary)", async () => {
+      const privateHost = "customer.jfrog.io";
+      await mockNpmFallbackExec(
+        [
+          "npm error code E401",
+          `npm error 401 Unauthorized - GET https://${privateHost}/@superblocksteam%2fcli`,
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args.runner).toBe("auto_upgrade");
+      expect(args.outcome).toBe("registry_auth_failed");
+      // The call-site passes the raw host through; `recordNpmInstall`
+      // (the real implementation, mocked here only to capture args)
+      // is what coerces it to `private`. The emitter cardinality
+      // test in `emitter.test.ts` pins that side; this test pins
+      // that the upgrade path actually feeds the host in.
+      expect(args.registryHost).toBe(privateHost);
+    });
+
+    it("APPS-4544: emits outcome=other for an unclassified failure (ERESOLVE) so the metric reflects the failure even without a NpmInstallBlocked match", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code ERESOLVE",
+          "npm error ERESOLVE unable to resolve dependency tree",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args.runner).toBe("auto_upgrade");
+      // No classifier match → `other`. The previous behaviour (before
+      // this test was added) was that the install promise rejected but
+      // no metric fired at all on the auto_upgrade runner, so a future
+      // refactor that drops the unclassified branch from the call site
+      // would silently turn this back into a metric gap.
+      expect(args.outcome).toBe("other");
+    });
+
+    // APPS-4544 (scout F2): the exec can SUCCEED (no error → outcome stays
+    // `success`) yet the upgrade still be broken — npm/pnpm reported success
+    // but the new binary isn't on PATH, a shadowing binary wins, or the
+    // install was corrupted. `upgradeCliWithPackageManager` validates the
+    // post-install version and, on mismatch/missing, flips `outcome` from
+    // `success` to `other` in its `catch` before re-throwing. That
+    // `success → other` flip is the ONLY transition of its kind and has no
+    // other coverage, so pin it: a future refactor that drops the flip would
+    // otherwise emit `outcome=success` for a CLI that's still stale.
+    it("APPS-4544: emits outcome=other when the exec succeeds but post-install version validation fails", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // Force the package-manager fallback (where post-install
+          // validation runs).
+          cb?.(null, { stdout: "this version is not updatable\n", stderr: "" });
+          return {};
+        }
+        // Install exec SUCCEEDS (no error) — so the classifier never runs
+        // and `outcome` stays `success` until post-install validation.
+        queueMicrotask(() => cb?.(null));
+        return { stdout: new EventEmitter(), stderr: new EventEmitter() };
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      // Initial check reports stale (triggers upgrade); post-install
+      // validation reports a version that does NOT match the target, so
+      // `upgradeCliWithPackageManager` throws "CLI version mismatch".
+      const versionDetection = await import("./version-detection.js");
+      vi.mocked(versionDetection.getCurrentCliVersion)
+        .mockResolvedValueOnce({ version: "2.0.0", alias: undefined }) // initial (stale)
+        .mockResolvedValueOnce({ version: "1.9.0", alias: undefined }); // post-install (mismatch)
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+
+      // The validation failure rejects the upgrade promise (so dev.mts
+      // won't restart into a stale CLI)...
+      await expect(Promise.all(result.upgradePromises)).rejects.toThrow(
+        /CLI version mismatch after upgrade/,
+      );
+
+      // ...and the metric still fires exactly once, flipped to `other`.
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args.runner).toBe("auto_upgrade");
+      expect(args.outcome).toBe("other");
+    });
+
+    // APPS-4544: ticket explicitly calls out "emit from both
+    // `upgradeCliWithPackageManager` and the oclif path". Without an
+    // oclif-success emission, dashboards undercount successful upgrades
+    // whenever the binary was installed via the oclif tarball channel —
+    // that path skips the pnpm fallback entirely, so there is no other
+    // call site that could fire the metric.
+    it("APPS-4544: emits recordNpmInstall on oclif success without falling back to the package manager", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // No "not updatable" in the output → oclif considers itself
+          // the canonical upgrader and the package-manager fallback does
+          // NOT run.
+          cb?.(null, { stdout: "Upgraded to 2.1.0\n", stderr: "" });
+          return {};
+        }
+        // Any other exec call is unexpected for the oclif-only path.
+        cb?.(new Error(`unexpected exec: ${cmd}`));
+        return {};
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      const versionDetection = await import("./version-detection.js");
+      vi.mocked(versionDetection.getCurrentCliVersion).mockResolvedValue({
+        version: "2.0.0",
+        alias: undefined,
+      });
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+      // The oclif `recordNpmInstall` fires inside the `upgradeCli`
+      // promise, which is pushed to `upgradePromises` and NOT awaited by
+      // `checkVersionsAndWritePackageJson`. Await it explicitly (matching
+      // the happy-path test) so the assertion can't race the microtask that
+      // emits the metric if the fixture's I/O ordering ever changes.
+      await Promise.all(result.upgradePromises);
+
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args).toMatchObject({
+        runner: "auto_upgrade",
+        outcome: "success",
+      });
+    });
+
+    // APPS-4554: a successful oclif upgrade replaces the on-disk CLI tarball
+    // but the running process keeps the OLD code, so the dev server must
+    // restart to pick it up. `dev.mts` gates that restart on
+    // `result.cliUpdated` (`hasCliUpdated`). Before this fix `cliUpdated` was
+    // only set in the package-manager fallback branch, so an oclif-only
+    // upgrade left the dev server running stale code until a manual restart.
+    // This test pins that the oclif-success branch flips the flag too, so the
+    // two upgrade paths stay symmetric.
+    it("APPS-4554: sets cliUpdated=true on oclif success so the dev server restarts", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // No "not updatable" in the output → oclif succeeds outright and
+          // the package-manager fallback (which historically set the flag)
+          // never runs.
+          cb?.(null, { stdout: "Upgraded to 2.1.0\n", stderr: "" });
+          return {};
+        }
+        cb?.(new Error(`unexpected exec: ${cmd}`));
+        return {};
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      const versionDetection = await import("./version-detection.js");
+      vi.mocked(versionDetection.getCurrentCliVersion).mockResolvedValue({
+        version: "2.0.0",
+        alias: undefined,
+      });
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+
+      expect(result.cliUpdated).toBe(true);
+    });
+
+    // APPS-4544: the ticket calls for an `outcome` attribute on the
+    // existing `upgradeCli` span so traces carry the upgrade result.
+    // This is the trace-side complement to the install metric — a
+    // single attribute lets operators correlate a failed CLI upgrade
+    // span with the pod that crash-looped, without correlating
+    // metric series back to traces by host+timestamp.
+    it("APPS-4544: sets outcome=success on the upgradeCli span when the upgrade completes", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          cb?.(null, { stdout: "Upgraded to 2.1.0\n", stderr: "" });
+          return {};
+        }
+        cb?.(null);
+        return { stdout: new EventEmitter(), stderr: new EventEmitter() };
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+      // The `upgradeCli` span callback runs inside one of the
+      // `upgradePromises` (the per-package upgrade futures pushed
+      // during the outer `checkVersionsAndUpgrade` span). The
+      // top-level `checkVersionsAndWritePackageJson` resolves before
+      // those finish — match the product call site that consumes
+      // `result.upgradePromises` directly.
+      await Promise.all(result.upgradePromises);
+
+      expect(spanSetAttributeMock).toHaveBeenCalledWith("outcome", "success");
+    });
+
+    it("APPS-4544: sets outcome=failure on the upgradeCli span when the package manager throws", async () => {
+      await mockNpmFallbackExec(
+        ["npm error code ECONNREFUSED", "npm error errno ECONNREFUSED"].join(
+          "\n",
+        ),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+      // The pkg-manager fallback rejects the upgrade promise; capture
+      // it so the test doesn't surface as an unhandled rejection,
+      // then assert on the span attribute the `catch` set.
+      await expect(Promise.all(result.upgradePromises)).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(spanSetAttributeMock).toHaveBeenCalledWith("outcome", "failure");
+    });
+
+    // APPS-4544 (Bugbot 613adfc7): when the detected package manager can't be
+    // turned into a global install command, `resolveCommand` returns
+    // undefined. The old code logged and returned without throwing, so the
+    // npm fallback became a silent no-op — the `upgradeCli` span still
+    // recorded `outcome=success` and no `recordNpmInstall` fired, producing a
+    // trace that claimed a successful auto-upgrade with no matching install
+    // metric. The fix emits a `runner=auto_upgrade` failure sample and flips
+    // the span to `outcome=failure` so the no-op is visible in metrics and
+    // traces — but it does NOT throw, because a rejected upgrade promise
+    // routes through `dev.mts` to `process.exit(1)` and crash-loops the
+    // live-edit pod. The no-op dev-server restart that still follows, graceful
+    // degrade, and user surfacing of the failed upgrade are tracked by
+    // APPS-4457, so this test asserts the promise RESOLVES.
+    it("APPS-4544: emits outcome=other and fails the span (without throwing) when no global install command can be resolved", async () => {
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // "not updatable" → oclif defers to the package-manager fallback,
+          // where `resolveCommand` is consulted.
+          cb?.(null, { stdout: "this version is not updatable\n", stderr: "" });
+          return {};
+        }
+        // The install exec must never run: `resolveCommand` fails first.
+        cb?.(new Error(`unexpected exec: ${cmd}`));
+        return {};
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+
+      // Force the single source-side `resolveCommand` call (the global
+      // install command builder) to fail to resolve a command. `*Once`
+      // takes precedence over the default mock implementation for the next
+      // call only, which is exactly the one we want to break.
+      const { resolveCommand } = await import("package-manager-detector");
+      vi.mocked(resolveCommand).mockReturnValueOnce(
+        undefined as unknown as ReturnType<typeof resolveCommand>,
+      );
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+
+      // The upgrade promise must RESOLVE, not reject: a no-resolvable-command
+      // upgrade is a no-op the live-edit pod degrades through, not a throw that
+      // `dev.mts` would route to `process.exit(1)` (crash-loop). Graceful
+      // degrade + user surfacing of the failed upgrade is tracked by APPS-4457.
+      await expect(Promise.all(result.upgradePromises)).resolves.toHaveLength(
+        1,
+      );
+
+      // A failure sample is still recorded for the auto_upgrade runner so the
+      // metric isn't silently missing for this path.
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      const args = recordNpmInstallMock.mock.calls[0]![0];
+      expect(args.runner).toBe("auto_upgrade");
+      expect(args.outcome).toBe("other");
+
+      // The span outcome must still reflect the failure, not the default
+      // success, so the no-op upgrade stays visible in traces even though the
+      // promise resolves.
+      expect(spanSetAttributeMock).toHaveBeenCalledWith("outcome", "failure");
+    });
+
     it("leaves sdk-api alone when the server response omits sdkApi (older deployment)", async () => {
       global.fetch = vi.fn(async () => ({
         ok: true,