@superblocksteam/sdk 2.0.137 → 2.0.138-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk",
-  "version": "2.0.137",
+  "version": "2.0.138-next.1",
   "description": "Superblocks JS SDK",
   "homepage": "https://www.superblocks.com",
   "license": "Superblocks Community Software License",
@@ -48,11 +48,11 @@
     "vite-tsconfig-paths": "^6.0.4",
     "winston": "^3.17.0",
     "yaml": "^2.7.1",
-    "@superblocksteam/shared": "0.9594.4",
-    "@superblocksteam/telemetry": "2.0.137",
-    "@superblocksteam/library-shared": "2.0.137",
-    "@superblocksteam/util": "2.0.137",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.137"
+    "@superblocksteam/util": "2.0.138-next.1",
+    "@superblocksteam/shared": "0.9595.1",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.138-next.1",
+    "@superblocksteam/library-shared": "2.0.138-next.1",
+    "@superblocksteam/telemetry": "2.0.138-next.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

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

@@ -25,6 +25,7 @@ import {
   buildInstallEnv,
   checkVersionsAndWritePackageJson,
 } from "./automatic-upgrades.js";
+import { UpgradeFailed } from "./dependency-install-classifier.mjs";
 
 // ---------------------------------------------------------------------------
 // Mocks
@@ -564,9 +565,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       // The structured log line fires before the rejection so the operator
       // sees the reason code in the crash-loop output. Reason is encoded
@@ -604,9 +603,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(loggerMock.error).toHaveBeenCalledWith(
         expect.stringMatching(
@@ -640,9 +637,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       const blockedCall = loggerMock.error.mock.calls.find(
         (c) =>
@@ -670,9 +665,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       const blockedCall = loggerMock.error.mock.calls.find(
         (c) =>
@@ -717,9 +710,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       const blockedCall = loggerMock.error.mock.calls.find(
         (c) =>
@@ -758,9 +749,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(loggerMock.error).toHaveBeenCalledWith(
         expect.stringMatching(/\[npm-install-blocked\] reason=not_in_registry/),
@@ -776,9 +765,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       // The classifier returns null for ERESOLVE — no structured log fires.
       expect(loggerMock.error).not.toHaveBeenCalledWith(
@@ -809,9 +796,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         ].join("\n"),
       });
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(loggerMock.error).toHaveBeenCalledWith(
         expect.stringMatching(
@@ -834,9 +819,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(loggerMock.error).toHaveBeenCalledWith(
         expect.stringMatching(
@@ -928,9 +911,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
       const args = recordNpmInstallMock.mock.calls[0]![0];
@@ -958,9 +939,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
       const args = recordNpmInstallMock.mock.calls[0]![0];
@@ -974,6 +953,44 @@ describe("checkVersionsAndWritePackageJson", () => {
       expect(args.registryHost).toBe(privateHost);
     });
 
+    it("threads hasAnyRegistryConfigured into the classified error and the metric so private-registry upgrade failures get the admin guidance, not the public-npm copy", async () => {
+      // E404 against a private host = the org has a registry configured but it
+      // can't serve the target version. The caller derives
+      // hasAnyRegistryConfigured=true and forwards it here; without the
+      // threading both the overlay copy and the metric would wrongly read
+      // "no registry configured".
+      await mockNpmFallbackExec(
+        [
+          "npm error code E404",
+          "npm error 404 Not Found - GET https://npm.private.example.com/@superblocksteam%2fcli - Not found",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+        // appDir omitted (defaults to process.cwd()); pass the registry
+        // tri-state in the new trailing position.
+        undefined,
+        true,
+      );
+      const err = await Promise.all(result.upgradePromises).catch((e) => e);
+
+      // The classified error drives the overlay copy: true → "ask an org
+      // admin to add the version to your registry".
+      expect(err).toBeInstanceOf(UpgradeFailed);
+      expect(err.serverError.category).toBe("not_in_registry");
+      expect(err.serverError.hasAnyRegistryConfigured).toBe(true);
+
+      // The same signal lands on the install metric so `auto_upgrade`
+      // failures attribute to the configured-registry bucket.
+      expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
+      expect(recordNpmInstallMock.mock.calls[0]![0].configured).toBe(true);
+    });
+
     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(
         [
@@ -983,9 +1000,7 @@ describe("checkVersionsAndWritePackageJson", () => {
         new Error("Command failed: pnpm install ..."),
       );
 
-      await expect(runAndAwaitUpgrade()).rejects.toThrow(
-        /Command failed: pnpm install/,
-      );
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(UpgradeFailed);
 
       expect(recordNpmInstallMock).toHaveBeenCalledTimes(1);
       const args = recordNpmInstallMock.mock.calls[0]![0];
@@ -1053,7 +1068,7 @@ describe("checkVersionsAndWritePackageJson", () => {
       // 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/,
+        UpgradeFailed,
       );
 
       // ...and the metric still fires exactly once, flipped to `other`.
@@ -1240,26 +1255,21 @@ describe("checkVersionsAndWritePackageJson", () => {
       // 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/,
+        UpgradeFailed,
       );
 
       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 () => {
+    // When the detected package manager can't be turned into a global install
+    // command, `resolveCommand` returns undefined. It still emits a
+    // `runner=auto_upgrade` failure sample and flips the `upgradeCli` span to
+    // `outcome=failure` so the no-op stays visible in metrics and traces, and
+    // it throws `UpgradeFailed` so the upgrade promise REJECTS. The dev.mts
+    // join routes that marker to the degrade path (keep serving the current
+    // version) — NOT `process.exit(1)` — and the rejection also stops the
+    // `cliUpdated=true` enqueue from triggering a pointless restart loop.
+    it("emits outcome=other, fails the span, and rejects with UpgradeFailed when no global install command can be resolved", async () => {
       const { exec } = await import("node:child_process");
       const execMock = vi.mocked(exec);
       execMock.mockImplementation(((
@@ -1302,12 +1312,12 @@ describe("checkVersionsAndWritePackageJson", () => {
         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,
+      // The upgrade promise must REJECT with the `UpgradeFailed` marker so the
+      // dev.mts join degrades (keep serving the current version) instead of
+      // restarting on the no-op. `handleStartupError` maps the marker to
+      // "degrade", so this rejection never reaches `process.exit(1)`.
+      await expect(Promise.all(result.upgradePromises)).rejects.toBeInstanceOf(
+        UpgradeFailed,
       );
 
       // A failure sample is still recorded for the auto_upgrade runner so the

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

@@ -25,6 +25,10 @@ import type { ResponseMeta } from "../socket/handlers.js";
 import { getTracer } from "../telemetry/index.js";
 import { getErrorMeta, getLogger } from "../telemetry/logging.js";
 import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/common.js";
+import {
+  classifyUpgradeError,
+  UpgradeFailed,
+} from "./dependency-install-classifier.mjs";
 import { superblocksLogsPath, superblocksNpmrcPath } from "./home-npmrc.mjs";
 import { stripUpgradedCliLockfiles } from "./post-upgrade-lockfile-strip.mjs";
 import {
@@ -176,12 +180,14 @@ async function upgradeCliWithOclif(targetVersion: string): Promise<boolean> {
   }
 }
 
-// Returns `true` when an install command actually ran and post-install
-// validation passed (every other failure throws). Returns `false` only when no
-// global install command could be resolved for the detected package manager — a
-// no-op the caller marks as a failed span WITHOUT throwing, so the live-edit
-// pod degrades on the current version instead of crash-looping. Proper graceful
-// degrade + surfacing the failed upgrade to the user is tracked by APPS-4457.
+// Resolves when an install command ran and post-install validation passed.
+// Every failure throws `UpgradeFailed` carrying a classified, non-blocking
+// `DependencyUpgradeError` — the no-command branch, an exec failure, and a
+// post-install version mismatch all degrade the same way. The dev.mts join
+// routes that marker to the degrade path, so the live-edit pod keeps serving
+// the currently installed version instead of crash-looping. The auto-upgrade
+// is best-effort: the running version still works, so a failed upgrade is
+// never fatal.
 async function upgradeCliWithPackageManager(
   pm: DetectResult,
   targetVersion: string,
@@ -191,35 +197,33 @@ async function upgradeCliWithPackageManager(
   // `.superblocks/logs`). Optional so callers/tests that don't care keep
   // npm's default `_logs` location.
   logsDir?: string,
-): Promise<boolean> {
+  // Currently installed version, carried into the classified error so the
+  // overlay can say "still on X; couldn't reach Y". Best-effort context.
+  currentVersion?: string,
+): Promise<void> {
   const packageName = alias
     ? `@superblocksteam/cli@npm:${alias}@${targetVersion}`
     : `@superblocksteam/cli@${targetVersion}`;
 
+  // Context shared by every classification path below: the package being
+  // upgraded plus whether a registry is configured.
+  const parseCtx = {
+    requestedPackages: [{ name: packageName }],
+    hasAnyRegistryConfigured,
+  };
+  const versions = { currentVersion, targetVersion };
+
   const installArgs = buildGlobalInstallArgs({ agent: pm.agent }, packageName);
 
   const installCommand = resolveCommand(pm.agent, "global", installArgs);
 
   if (!installCommand) {
-    // APPS-4544 (Bugbot 613adfc7): we couldn't even build a global install
-    // command for the detected package manager, so no upgrade happened.
-    // Before this PR added the `upgradeCli` span `outcome` attribute and the
-    // `superblocks.npm.install.*` metric, this no-op left no telemetry: the
-    // span kept its default `outcome=success` and no install metric was
-    // emitted, so an auto-upgrade that did nothing looked successful.
-    //
-    // Emit a failure sample so the histogram carries a `runner="auto_upgrade"`
-    // failure sample for this path, then return `false` so the caller flips
-    // the `upgradeCli` span to `outcome=failure`. `durationMs` is 0 because no
-    // install process ran; `outcome="other"` mirrors the unclassified-failure
-    // fallback used by the exec/validation paths below.
-    //
-    // We deliberately do NOT throw: a rejected upgrade promise routes through
-    // `dev.mts` to `process.exit(1)`, crash-looping the live-edit pod. The
-    // no-op dev-server restart that still follows (`cliUpdated` is set
-    // unconditionally at enqueue time in `checkVersionsAndWritePackageJson`),
-    // plus degrading gracefully (continue on the current version) and
-    // surfacing the failed upgrade to the user, are tracked by APPS-4457.
+    // We couldn't build a global install command for the detected package
+    // manager, so no upgrade ran. Emit a failure sample (durationMs 0 — nothing
+    // ran) so the metric doesn't read this no-op as a success, then throw
+    // `UpgradeFailed` so the dev.mts join degrades (keep serving the current
+    // version) instead of leaving `cliUpdated=true` to trigger a pointless
+    // dev-server restart loop.
     logger.error("Could not determine how to upgrade Superblocks packages.");
     recordNpmInstall({
       runner: "auto_upgrade",
@@ -228,7 +232,15 @@ async function upgradeCliWithPackageManager(
       registryHost: undefined,
       durationMs: 0,
     });
-    return false;
+    throw new UpgradeFailed(
+      classifyUpgradeError(
+        {
+          message: "Could not determine how to upgrade Superblocks packages.",
+        },
+        parseCtx,
+        versions,
+      ),
+    );
   }
 
   const { command, args } = installCommand;
@@ -284,10 +296,7 @@ async function upgradeCliWithPackageManager(
         const errStderr = (error as { stderr?: unknown }).stderr;
         const stderrText =
           stderrBuffer || (typeof errStderr === "string" ? errStderr : "");
-        const blocked = classifyNpmExecStderr(stderrText, {
-          requestedPackages: [{ name: packageName }],
-          hasAnyRegistryConfigured,
-        });
+        const blocked = classifyNpmExecStderr(stderrText, parseCtx);
         // Surface the structured `NpmInstallBlocked.reason` (e.g.
         // `registry_unreachable`, `registry_auth_failed`) and raw host to
         // the install metric below; the emitter coerces both at the emit
@@ -399,7 +408,24 @@ async function upgradeCliWithPackageManager(
     if (outcome === "success") {
       outcome = "other";
     }
-    throw err;
+    // Both the exec failure (rejected with the raw npm error, re-thrown by
+    // `await promise`) and a post-install version mismatch land here. Classify
+    // into a non-blocking `DependencyUpgradeError` and throw the `UpgradeFailed`
+    // marker so the dev.mts join degrades instead of crash-looping. `stderrBuffer`
+    // holds the streamed npm stderr; fall back to the error's own fields when a
+    // fast-failing subprocess exited before the listener attached.
+    const e = err as { stdout?: string; stderr?: string; message?: string };
+    throw new UpgradeFailed(
+      classifyUpgradeError(
+        {
+          stdout: e.stdout,
+          stderr: stderrBuffer || e.stderr,
+          message: e.message,
+        },
+        parseCtx,
+        versions,
+      ),
+    );
   } finally {
     // Both the happy path and every throw above (exec failure → callback
     // sets outcome, post-install validation throw → catch sets outcome to
@@ -418,9 +444,7 @@ async function upgradeCliWithPackageManager(
   }
 
   // Reached only when the install ran and post-install validation passed
-  // (every failure above throws). Signals the caller that a real upgrade
-  // happened so it leaves the `upgradeCli` span `outcome=success`.
-  return true;
+  // (every failure above throws `UpgradeFailed`).
 }
 
 export async function checkVersionsAndWritePackageJson(
@@ -434,6 +458,14 @@ export async function checkVersionsAndWritePackageJson(
   // unaffected; `dev()` passes its `cwd` explicitly for consistency with
   // the startup install.
   appDir: string = process.cwd(),
+  // Whether the org routes installs through a configured npm registry, as a
+  // tri-state: `true` (configured/stale), `false` (deliberately none),
+  // `undefined` (couldn't resolve). The caller derives it from the same
+  // registry config the startup install classifier uses and forwards it into
+  // the CLI auto-upgrade, so a failure classifies/renders with the right
+  // guidance ("ask an org admin" vs "temporary") and records the correct
+  // `configured` install metric instead of always defaulting to `false`.
+  hasAnyRegistryConfigured?: boolean,
 ): Promise<{
   cliUpdated: boolean;
   upgradePromises: Promise<void>[];
@@ -521,16 +553,16 @@ export async function checkVersionsAndWritePackageJson(
         return;
       }
 
-      // Failure-mode contrast with AppShell's per-app install path: AppShell
-      // routes exec failures through `classifyNpmExecError` and emits a
-      // structured `NpmInstallBlocked` diagnostic. The auto-upgrade subprocess
-      // below does NOT route through that classifier — it `exec`s
-      // `npm install -g @superblocksteam/cli@...` directly. A perimeter block
-      // (ECONNREFUSED) surfaces here as a generic `Error` caught by the outer
-      // try/catch (`hasFailedToUpgrade = true` → release lock → `process.exit`),
-      // which Kubernetes restarts. The operator sees a visible crash-loop with
-      // "Error upgrading packages" rather than a silent fallback. For symmetry
-      // with the install path, wrap the upgrade exec in the same classifier.
+      // The auto-upgrade runs the global `npm install -g @superblocksteam/cli@...`
+      // and classifies its failures the same way the per-app install does. On
+      // any failure (network block, registry/auth/TLS error, version mismatch,
+      // or no resolvable install command) it throws the `UpgradeFailed` marker
+      // carrying a classified `DependencyUpgradeError`. The dev.mts join routes
+      // that marker to the degrade path, so the pod keeps serving the current
+      // version instead of crash-looping — the upgrade is best-effort. The
+      // early `process.exit(1)` below is reserved for genuinely-unusable cases
+      // (no package manager, an unparseable version, a corrupt package.json)
+      // that are not upgrade failures.
       try {
         if (
           !skipCliUpgrade &&
@@ -600,30 +632,20 @@ export async function checkVersionsAndWritePackageJson(
                   logger.info(
                     `Falling back to package manager upgrade for CLI`,
                   );
-                  const cliUpgradeRan = await traceFunction({
+                  await traceFunction({
                     name: "upgradePackageWithPackageManager - cli",
                     tracer,
                     fn: async () => {
-                      return await upgradeCliWithPackageManager(
+                      await upgradeCliWithPackageManager(
                         packageManager,
                         targetVersions.cli,
                         currentCliInfo.alias,
-                        undefined,
+                        hasAnyRegistryConfigured,
                         superblocksLogsPath(appDir),
+                        currentCliInfo.version,
                       );
                     },
                   });
-                  if (!cliUpgradeRan) {
-                    // No global install command could be resolved → the CLI
-                    // upgrade was a no-op (the failure metric was already
-                    // emitted inline). Flip the span to `failure` so the trace
-                    // is accurate, but do NOT throw: throwing routes through
-                    // `dev.mts` to `process.exit(1)` and crash-loops the pod.
-                    // The no-op dev-server restart that still follows
-                    // (`cliUpdated = true` below), graceful degrade, and user
-                    // surfacing of the failed upgrade are tracked by APPS-4457.
-                    outcome = "failure";
-                  }
                 }
                 // The freshly fetched tarball may ship bundled lockfiles with
                 // stale public-host `resolved` URLs; strip them so the next

package/src/cli-replacement/dependency-install-classifier.mts

@@ -1,4 +1,7 @@
-import type { DependencyInstallError } from "@superblocksteam/library-shared/types";
+import type {
+  DependencyInstallError,
+  DependencyUpgradeError,
+} from "@superblocksteam/library-shared/types";
 import {
   classifyNpmExecStderr,
   parseNpmJsonDiagnostic,
@@ -23,6 +26,19 @@ export class InitialInstallFailed extends Error {
   }
 }
 
+/** Marker thrown by the best-effort CLI/library auto-upgrade so the dev.mts
+ *  catch can DEGRADE (keep serving the current version) instead of crash-looping
+ *  the pod. Carries the classified, non-blocking upgrade error. */
+export class UpgradeFailed extends Error {
+  readonly serverError: DependencyUpgradeError;
+  constructor(serverError: DependencyUpgradeError) {
+    super(`dependency upgrade failed (${serverError.category})`);
+    this.name = "UpgradeFailed";
+    this.serverError = serverError;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
 export interface ExecFailure {
   stdout?: string;
   stderr?: string;
@@ -130,3 +146,60 @@ export function classifyInitialInstallError(
     rawError,
   };
 }
+
+/**
+ * Classify a failed CLI/library auto-upgrade exec into a non-blocking
+ * `DependencyUpgradeError`. Always returns an error (never null) — every
+ * upgrade failure degrades, because the pod keeps running the current version.
+ *
+ * Mirrors `classifyInitialInstallError` but maps to the upgrade error's
+ * narrower category set: registry/network reasons keep their classification;
+ * everything else (no install command, post-install version mismatch,
+ * unclassified exec error) folds to `unknown`. We deliberately do NOT surface
+ * `dependency_conflict` / `disk_full` here — a global `-g` CLI install does not
+ * resolve the app's dependency tree, and the remediation is uniform (an org
+ * admin makes the target version installable), so finer buckets would not
+ * change the user-facing guidance.
+ */
+export function classifyUpgradeError(
+  failure: ExecFailure,
+  ctx: ParseContext,
+  versions: { currentVersion?: string; targetVersion?: string } = {},
+): DependencyUpgradeError {
+  const stdout = failure.stdout ?? "";
+  const stderr = failure.stderr ?? "";
+  const rawError = scrubSecrets(
+    parseNpmJsonDiagnostic(stdout) || stderr || failure.message || "",
+  );
+
+  const base = {
+    type: "dev-server/dependency-upgrade" as const,
+    timestamp: new Date().toISOString(),
+    currentVersion: versions.currentVersion,
+    targetVersion: versions.targetVersion,
+    rawError,
+  };
+
+  const blocked =
+    parseNpmJsonError(stdout, ctx) ?? classifyNpmExecStderr(stderr, ctx);
+  if (blocked) {
+    return {
+      ...base,
+      // `NpmInstallBlockedReason` is exactly the four registry/network reasons,
+      // each of which is also a `DependencyUpgradeError` category, so the reason
+      // doubles as the category directly (REASON_TO_CATEGORY is identity here).
+      category: blocked.reason,
+      npmErrorCode: blocked.npmErrorCode,
+      hasAnyRegistryConfigured: blocked.hasAnyRegistryConfigured,
+    };
+  }
+
+  const combined = `${stdout}\n${stderr}`;
+  const unknownCode = combined.match(/npm (?:error|ERR!) code (\S+)/)?.[1];
+  return {
+    ...base,
+    category: "unknown",
+    npmErrorCode: unknownCode,
+    hasAnyRegistryConfigured: ctx.hasAnyRegistryConfigured,
+  };
+}

package/src/cli-replacement/dependency-install-classifier.test.mts

@@ -2,7 +2,9 @@ import { describe, it, expect } from "vitest";
 
 import {
   InitialInstallFailed,
+  UpgradeFailed,
   classifyInitialInstallError,
+  classifyUpgradeError,
 } from "./dependency-install-classifier.mjs";
 
 const ERESOLVE_JSON = JSON.stringify({
@@ -109,3 +111,50 @@ describe("classifyInitialInstallError", () => {
     expect(marker.serverError).toBe(se);
   });
 });
+
+describe("classifyUpgradeError", () => {
+  it("maps a registry block to its reason and carries the versions", () => {
+    const e = classifyUpgradeError(
+      {
+        stdout: "",
+        stderr:
+          "npm error code E401\nnpm error 401 Unauthorized - GET https://reg.corp/@superblocksteam%2fcli",
+        message: "Command failed",
+      },
+      { hasAnyRegistryConfigured: true },
+      { currentVersion: "2.0.133", targetVersion: "2.0.134" },
+    );
+    expect(e.type).toBe("dev-server/dependency-upgrade");
+    expect(e.category).toBe("registry_auth_failed");
+    expect(e.currentVersion).toBe("2.0.133");
+    expect(e.targetVersion).toBe("2.0.134");
+    expect(e.rawError.length).toBeGreaterThan(0);
+  });
+
+  it("folds anything unclassified to unknown — an odd exec code or the no-command message", () => {
+    const exec = classifyUpgradeError(
+      {
+        stdout: "",
+        stderr: "npm error code EWEIRD\nsomething broke",
+        message: "Command failed",
+      },
+      {},
+    );
+    expect(exec.category).toBe("unknown");
+    expect(exec.npmErrorCode).toBe("EWEIRD");
+
+    const noCommand = classifyUpgradeError(
+      { message: "Could not determine how to upgrade Superblocks packages." },
+      {},
+    );
+    expect(noCommand.category).toBe("unknown");
+    expect(noCommand.rawError).toContain("Could not determine");
+  });
+
+  it("UpgradeFailed carries the classified error", () => {
+    const se = classifyUpgradeError({ stderr: "npm error code EWEIRD" }, {});
+    const marker = new UpgradeFailed(se);
+    expect(marker).toBeInstanceOf(Error);
+    expect(marker.serverError).toBe(se);
+  });
+});