@superblocksteam/sdk 2.0.137-next.0 → 2.0.138-next.0

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

@@ -1,16 +1,23 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
-import { InitialInstallFailed } from "./dependency-install-classifier.mjs";
+import {
+  InitialInstallFailed,
+  UpgradeFailed,
+} 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(),
-}));
+// Mock the metrics module so we can assert recordInitialInstallFailure /
+// recordUpgradeFailure calls. vi.mock is hoisted, so we use vi.hoisted to
+// declare the spies before the factory.
+const { recordInitialInstallFailureMock, recordUpgradeFailureMock } =
+  vi.hoisted(() => ({
+    recordInitialInstallFailureMock: vi.fn(),
+    recordUpgradeFailureMock: vi.fn(),
+  }));
 vi.mock("../dev-utils/dev-server-metrics.mjs", () => ({
   devServerMetrics: {
     recordInitialInstallFailure: recordInitialInstallFailureMock,
+    recordUpgradeFailure: recordUpgradeFailureMock,
     flush: vi.fn(),
     recordEndpoint: vi.fn(),
     recordSocketUpgrade: vi.fn(),
@@ -26,6 +33,7 @@ const makeLogger = () =>
 
 beforeEach(() => {
   recordInitialInstallFailureMock.mockClear();
+  recordUpgradeFailureMock.mockClear();
 });
 
 describe("handleStartupError", () => {
@@ -67,7 +75,7 @@ describe("handleStartupError", () => {
     expect(recordInitialInstallFailureMock).not.toHaveBeenCalled();
   });
 
-  it("exits for a non-marker error (upgrade / lock / sync)", () => {
+  it("exits for a non-marker error (lock / sync / genuinely-unusable upgrade env)", () => {
     const status = { serverErrors: [] as any[] };
     const decision = handleStartupError(
       new Error("lock failed"),
@@ -77,4 +85,28 @@ describe("handleStartupError", () => {
     expect(decision).toBe("exit");
     expect(status.serverErrors).toHaveLength(0);
   });
+
+  it("records + does NOT exit for UpgradeFailed (best-effort upgrade degrades)", () => {
+    const status = { serverErrors: [] as any[] };
+    const marker = new UpgradeFailed({
+      type: "dev-server/dependency-upgrade",
+      timestamp: "t",
+      category: "not_in_registry",
+      npmErrorCode: "ETARGET",
+      hasAnyRegistryConfigured: true,
+      currentVersion: "2.0.133",
+      targetVersion: "2.0.134",
+      rawError: "x",
+    });
+    const decision = handleStartupError(marker, status, makeLogger());
+    expect(decision).toBe("degrade");
+    expect(status.serverErrors).toHaveLength(1);
+    expect(recordUpgradeFailureMock).toHaveBeenCalledWith({
+      category: "not_in_registry",
+      npmErrorCode: "ETARGET",
+      hasAnyRegistryConfigured: true,
+    });
+    // The upgrade failure must not be miscounted as an initial-install failure.
+    expect(recordInitialInstallFailureMock).not.toHaveBeenCalled();
+  });
 });

package/src/cli-replacement/dev.mts

@@ -54,7 +54,7 @@ import type {
   TokenManager,
   SuperblocksSdk,
 } from "../index.js";
-import { getTracer } from "../telemetry/index.js";
+import { getTracer, shutdownTelemetry } from "../telemetry/index.js";
 import { getErrorMeta, getLogger, type Logger } from "../telemetry/logging.js";
 import type {
   ApplicationConfig,
@@ -68,6 +68,7 @@ import {
 import {
   classifyInitialInstallError,
   InitialInstallFailed,
+  UpgradeFailed,
 } from "./dependency-install-classifier.mjs";
 import { getDiskSpace, recoverFromDiskFull } from "./disk-space.mjs";
 import {
@@ -89,6 +90,12 @@ import {
 } from "./package-json-snapshot.mjs";
 import { getCurrentCliVersion } from "./version-detection.js";
 
+// APPS-5072: bound on the pre-restart telemetry flush. Deliberately well
+// under the 10s metric-reader export interval so the flush is meaningful, yet
+// short enough that a slow/unreachable OTel collector can't wedge the CLI
+// restart.
+const TELEMETRY_FLUSH_TIMEOUT_MS = 3000;
+
 const passErrorToVSCode = (message: string | undefined, logger: Logger) => {
   if (message && process.env.SUPERBLOCKS_VSCODE === "true") {
     // Prefixing with `clierr:` will make the VS code extension capture this message and show it to the user.
@@ -648,6 +655,39 @@ export async function installPackages(
   }
 }
 
+/**
+ * Resolve whether the org routes installs through a configured npm registry, as
+ * a tri-state mirroring AppShell's `deriveHasAnyRegistryConfigured`
+ * (`shell.ts`): `configured`/`stale` → `true` (rows known to exist),
+ * `not-configured` → `false` (deliberate "no rows"), `unreachable` →
+ * `undefined` ("we don't know" — renderers fall back to the default variant).
+ * Left `undefined` when no client is wired in or the resolution itself throws.
+ *
+ * Single derivation site shared by the startup-install classifier
+ * (`buildInstallParseContext`) and the CLI auto-upgrade path, so both classify
+ * a registry-blocked failure the same way.
+ */
+async function resolveHasAnyRegistryConfigured(
+  npmRegistryClient?: NpmRegistryClient,
+): Promise<boolean | undefined> {
+  if (!npmRegistryClient) return undefined;
+  try {
+    const result = await npmRegistryClient.getConfig();
+    switch (result.source) {
+      case "configured":
+      case "stale":
+        return true;
+      case "not-configured":
+        return false;
+      case "unreachable":
+        return undefined;
+    }
+  } catch {
+    /* leave undefined → renderers treat as "don't know" / default variant */
+  }
+  return undefined;
+}
+
 /**
  * Build the `ParseContext` the dependency-install classifier needs from the
  * failing install's working directory + registry client:
@@ -655,13 +695,8 @@ export async function installPackages(
  *   - `requestedPackages` — the union of `dependencies` + `devDependencies`
  *     in the app's `package.json`, used by the registry-blocked renderers to
  *     name the failing specs when npm's `--json` `detail` doesn't.
- *   - `hasAnyRegistryConfigured` — the tri-state derived from the registry
- *     client's most recent `getConfig()`, mirroring AppShell's
- *     `deriveHasAnyRegistryConfigured` (`shell.ts`): `configured`/`stale`
- *     → `true` (rows known to exist), `not-configured` → `false` (deliberate
- *     "no rows"), `unreachable` → `undefined` ("we don't know" — the renderer
- *     falls back to the default variant). Left `undefined` when no client is
- *     wired in or the resolution itself throws.
+ *   - `hasAnyRegistryConfigured` — the registry tri-state from
+ *     `resolveHasAnyRegistryConfigured`.
  *
  * Best-effort throughout: a missing/unparseable package.json or a registry
  * outage must not mask the underlying install failure, so both lookups are
@@ -684,26 +719,8 @@ async function buildInstallParseContext(
     /* best-effort: a missing/unparseable package.json yields no specs */
   }
 
-  let hasAnyRegistryConfigured: boolean | undefined;
-  if (npmRegistryClient) {
-    try {
-      const result = await npmRegistryClient.getConfig();
-      switch (result.source) {
-        case "configured":
-        case "stale":
-          hasAnyRegistryConfigured = true;
-          break;
-        case "not-configured":
-          hasAnyRegistryConfigured = false;
-          break;
-        case "unreachable":
-          hasAnyRegistryConfigured = undefined;
-          break;
-      }
-    } catch {
-      /* leave undefined → renderers treat as "don't know" / default variant */
-    }
-  }
+  const hasAnyRegistryConfigured =
+    await resolveHasAnyRegistryConfigured(npmRegistryClient);
 
   return { requestedPackages, hasAnyRegistryConfigured };
 }
@@ -759,8 +776,10 @@ export interface DevServerStatus {
 }
 
 /** Decide how the startup catch handles an error: degrade (record, keep Vite up)
- *  for an app-install failure (the InitialInstallFailed marker), or exit for
- *  anything else (lock/sync/upgrade). Pure + unit-tested. Does NOT call process.exit. */
+ *  for an app-install failure (`InitialInstallFailed`) or a best-effort
+ *  CLI/library auto-upgrade failure (`UpgradeFailed`), or exit for anything else
+ *  (lock/sync/genuinely-unusable upgrade env). Pure + unit-tested. Does NOT call
+ *  process.exit. */
 export function handleStartupError(
   error: unknown,
   status: DevServerStatus,
@@ -779,6 +798,23 @@ export function handleStartupError(
     });
     return "degrade";
   }
+  if (error instanceof UpgradeFailed) {
+    // The auto-upgrade is best-effort and the pod is still running the current
+    // version, so a failed upgrade degrades instead of crash-looping. Recording
+    // here also makes the failure observable: the process survives to the next
+    // metrics export tick, which the pre-exit `process.exit(1)` always lost.
+    status.serverErrors.push(error.serverError);
+    logger.error(
+      "[dev-server] dependency upgrade failed; keeping the current version",
+      getErrorMeta(error),
+    );
+    devServerMetrics.recordUpgradeFailure({
+      category: error.serverError.category,
+      npmErrorCode: error.serverError.npmErrorCode,
+      hasAnyRegistryConfigured: error.serverError.hasAnyRegistryConfigured,
+    });
+    return "degrade";
+  }
   return "exit";
 }
 
@@ -872,24 +908,26 @@ export async function dev(options: {
   // We keep them SEPARATE so an install rejection cannot swallow an upgrade
   // rejection (or vice-versa) the way a single `Promise.all` would: that
   // bundle settles on the FIRST rejection and silently absorbs the other's
-  // outcome, breaking APPS-4457's intent that auto-upgrade failures still
-  // exit (not degrade) and CLI-restart-on-upgrade still happens even if the
-  // app install fails.
+  // outcome. Separate handles let each outcome be observed on its own join, so
+  // CLI-restart-on-successful-upgrade still happens even if the app install
+  // fails, and each failure mode gets its own surfacing.
   //
-  //   - packageUpgradePromise: library upgrades (and their `npm install`
-  //     side-effects) from `checkVersionsAndWritePackageJson`. Rejection is
-  //     OUT of scope for graceful degrade (APPS-4457) — `handleStartupError`
-  //     routes it to `process.exit(1)`.
+  //   - packageUpgradePromise: CLI/library upgrades from
+  //     `checkVersionsAndWritePackageJson`. Rejection is the `UpgradeFailed`
+  //     marker, which `handleStartupError` routes to the degrade path — the
+  //     auto-upgrade is best-effort, so the pod keeps the current version.
+  //     A SUCCESSFUL upgrade instead resolves and triggers the CLI restart
+  //     below.
   //   - packageInstallPromise: the app's verification `npm install`.
   //     Rejection MAY be the `InitialInstallFailed` marker, which
-  //     `handleStartupError` routes to the degrade path.
+  //     `handleStartupError` also routes to the degrade path.
   let packageUpgradePromise: Promise<void> | undefined;
   let packageInstallPromise: Promise<void> | undefined;
   const tracer = getTracer();
   const logger = getLogger(options.logger);
-  // Joins the in-flight upgrade. Rejection propagates so the caller's step
-  // can abort cleanly (handleStartupError exits — auto-upgrade graceful
-  // degrade is OOS per APPS-4457).
+  // Joins the in-flight upgrade. Rejection propagates so the caller's step can
+  // abort cleanly (handleStartupError degrades for the `UpgradeFailed` marker,
+  // exits otherwise).
   const joinPackageUpgrade = async (reason: string): Promise<void> => {
     if (!packageUpgradePromise) {
       return;
@@ -924,9 +962,11 @@ export async function dev(options: {
     packageInstallPromise = undefined;
     await Promise.allSettled([promise]);
   };
-  // Joins upgrade THEN install. Upgrade failures surface first so
-  // handleStartupError exits (per APPS-4457) before an install rejection
-  // gets a chance to route to degrade.
+  // Joins upgrade THEN install. Upgrade outcome is observed first: a failed
+  // upgrade (`UpgradeFailed`) degrades and skips the CLI restart below, while a
+  // SUCCESSFUL upgrade lets the `InitialInstallFailed` branch route to the
+  // restart (the new CLI re-runs install). Both markers degrade; the ordering
+  // is about which branch the catch sites see first, not exit-vs-degrade.
   const joinUpgradeThenInstall = async (reason: string): Promise<void> => {
     await joinPackageUpgrade(reason);
     await joinPackageInstall(reason);
@@ -1431,6 +1471,15 @@ export async function dev(options: {
                         featureFlags: sdk.getFeatureFlagsForUser(currentUser),
                       };
 
+                    // Derive the registry tri-state the same way the startup
+                    // install classifier does so a failed CLI auto-upgrade
+                    // classifies/renders with the right private-registry
+                    // guidance ("ask an org admin" vs "temporary") and records
+                    // the correct `configured` install metric. Resolved here,
+                    // before the upgrade promise launches, because the promise
+                    // outlives this call.
+                    const hasAnyRegistryConfigured =
+                      await resolveHasAnyRegistryConfigured(npmRegistryClient);
                     const result = await checkVersionsAndWritePackageJson(
                       lockService,
                       applicationConfigWithTokenConfigAndUserInfo,
@@ -1439,6 +1488,7 @@ export async function dev(options: {
                       // Route the CLI-upgrade install's npm debug log into the
                       // same `<app>/.superblocks/logs` as the startup install.
                       cwd,
+                      hasAnyRegistryConfigured,
                     );
                     hasCliUpdated = result.cliUpdated;
                     upgradePromises = result.upgradePromises;
@@ -1541,11 +1591,13 @@ export async function dev(options: {
 
             // Launch upgrades and app install as INDEPENDENT promises (not a
             // single `Promise.all`) so each outcome is observed on its own
-            // join: upgrade failure exits (APPS-4457), install failure may
-            // degrade (InitialInstallFailed). A bundled `Promise.all` would
-            // settle on the first rejection and silently absorb the other's
-            // result. The `.catch` backstops convert "no join fired" cases
-            // into logged-then-handled rejections instead of unhandled ones.
+            // join: a failed upgrade degrades (`UpgradeFailed`) and skips the
+            // CLI restart, an install failure degrades (`InitialInstallFailed`),
+            // and a SUCCESSFUL upgrade still restarts even if the install fails.
+            // A bundled `Promise.all` would settle on the first rejection and
+            // silently absorb the other's result. The `.catch` backstops convert
+            // "no join fired" cases into logged-then-handled rejections instead
+            // of unhandled ones.
             if (upgradePromises.length > 0) {
               logger.info("Starting package upgrade in background…");
               const launchedUpgradeCount = upgradePromises.length;
@@ -1612,8 +1664,9 @@ export async function dev(options: {
             ) {
               // Upload serializes the post-install lockfile + node_modules
               // tree to DBFS, so it must observe quiesced upgrade+install.
-              // Upgrade first — its rejection exits before an install
-              // rejection can take the degrade path (APPS-4457).
+              // Upgrade first — a failed upgrade (`UpgradeFailed`) is seen
+              // before the install join and degrades via the outer catch,
+              // skipping both upload and restart.
               //
               // BUT: if a successful CLI upgrade is pending restart
               // (`hasCliUpdated`), the restart branch below MUST win over
@@ -1684,6 +1737,45 @@ export async function dev(options: {
                 );
               }
               logger.info("CLI was updated, restarting the dev server…");
+              // APPS-5072: the OTel metric reader exports on a 10s interval,
+              // but this restart exits within ~1-3s of recording the
+              // auto-upgrade install metric
+              // (superblocks.npm.install.* runner=auto_upgrade). Without an
+              // explicit flush the buffered sample dies with the process —
+              // which is why that runner reports zero samples in every env
+              // despite real upgrades emitting it (spans survive because they
+              // flush on the faster batch processor; the metric does not).
+              // shutdownTelemetry() never rejects; the catch is purely
+              // defensive. It resolves to `true` only when a flush actually
+              // ran — `false` on internal shutdown error or when telemetry was
+              // disabled — and the timeout branch leaves the flag false. So
+              // the log below reflects whether samples were really flushed, not
+              // merely that the race settled.
+              let telemetryFlushed = false;
+              try {
+                await Promise.race([
+                  shutdownTelemetry().then((flushed) => {
+                    telemetryFlushed = flushed;
+                  }),
+                  new Promise<void>((resolve) =>
+                    setTimeout(resolve, TELEMETRY_FLUSH_TIMEOUT_MS),
+                  ),
+                ]);
+              } catch (e) {
+                logger.error(
+                  "Error flushing telemetry before CLI restart",
+                  getErrorMeta(e),
+                );
+              }
+              if (telemetryFlushed) {
+                logger.info("Telemetry flushed before CLI restart");
+              } else {
+                logger.warn(
+                  `Telemetry flush did not complete (timed out after ${TELEMETRY_FLUSH_TIMEOUT_MS}ms, ` +
+                    "errored, or telemetry disabled) before CLI restart; " +
+                    "some auto_upgrade metric samples may be dropped",
+                );
+              }
               process.exit(AUTO_UPGRADE_EXIT_CODE);
             }
           });
@@ -1719,18 +1811,18 @@ export async function dev(options: {
       // here costs at most the install's remaining wall time — the upload
       // and CLI-restart joins above usually drain it first.
       // The "before upload" / "before CLI restart" joins above run inside the
-      // sync/lock catch that degrades on `InitialInstallFailed`. But when the
-      // install ran yet none of those joins fired (e.g.
+      // sync/lock catch that degrades on the install/upgrade markers. But when
+      // the install ran yet none of those joins fired (e.g.
       // `packageJsonRequiresInstall && !forcePackageInstall && !upload &&
-      // !hasCliUpdated`), the install rejection first surfaces HERE — outside
-      // that catch. Route it through the SAME origin gate so an app-install
-      // failure still degrades (keep Vite up + record the error) instead of
-      // escaping `dev()` to `process.exit(1)`. Non-install errors (including
-      // any background upgrade rejection that escaped the prior joins) take
-      // the same explicit exit path as the sync/lock catch above so the
-      // process actually terminates (the startupSpan catch only rethrows,
-      // and an unhandled rejection at that depth doesn't shut the lock
-      // service down or guarantee `process.exit(1)`).
+      // !hasCliUpdated`), the rejection first surfaces HERE — outside that
+      // catch. Route it through the SAME origin gate so an app-install failure
+      // (`InitialInstallFailed`) or a best-effort upgrade failure
+      // (`UpgradeFailed`) still degrades (keep Vite up + record the error)
+      // instead of escaping `dev()` to `process.exit(1)`. Genuinely fatal
+      // errors (lock/sync) take the explicit exit path below so the process
+      // actually terminates (the startupSpan catch only rethrows, and an
+      // unhandled rejection at that depth doesn't shut the lock service down or
+      // guarantee `process.exit(1)`).
       try {
         await joinUpgradeThenInstall("before Vite startup");
       } catch (error) {

package/src/cli-replacement/home-npmrc.mts

@@ -8,12 +8,12 @@ import {
   bucketNpmRegistryHost,
   NPM_REGISTRY_SPAN,
   NPM_REGISTRY_SPAN_ATTR,
+  npmRegistryEmitter,
   withNpmRegistrySpan,
 } from "@superblocksteam/telemetry";
 import {
   type NpmRegistryClient,
   type NpmRegistryFetchResult,
-  PRESERVE_NPMRC_SCOPES,
   restoreInitialNpmrc,
   snapshotInitialNpmrc,
   type SnapshotInitialNpmrcOutcome,
@@ -252,13 +252,19 @@ export async function syncHomeNpmrc(
     NPM_REGISTRY_SPAN.SYNC_HOME_NPMRC,
     deps.orgId ? { [NPM_REGISTRY_SPAN_ATTR.ORG_ID]: deps.orgId } : {},
     async (span) => {
+      // Time the sync so the span carries `duration_ms`, and emit a counter
+      // alongside it so the health of writing the npmrc at boot can be alerted
+      // on per service.name without querying traces.
+      const start = Date.now();
       const result = await syncHomeNpmrcImpl(deps);
       span.setAttributes({
         [NPM_REGISTRY_SPAN_ATTR.OUTCOME]: result.outcome,
+        [NPM_REGISTRY_SPAN_ATTR.DURATION_MS]: Date.now() - start,
         ...(result.source
           ? { [NPM_REGISTRY_SPAN_ATTR.SOURCE]: result.source }
           : {}),
       });
+      npmRegistryEmitter.recordSyncHomeNpmrc(result.outcome);
       return result;
     },
   );
@@ -272,7 +278,11 @@ async function syncHomeNpmrcImpl(
 
   let result: NpmRegistryFetchResult;
   try {
-    result = await deps.npmRegistryClient.getConfig();
+    // Force-refresh so the home userconfig reflects an admin clearing or
+    // changing the registry, rather than inheriting a config a sibling
+    // startup step (e.g. `privateRegistryValidationResult`) may have just
+    // warmed into the client's TTL cache.
+    result = await deps.npmRegistryClient.getConfig({ forceRefresh: true });
   } catch (error) {
     // `NpmRegistryClient` only throws for the deliberate-denial branches
     // (RBAC 403, malformed request 400, double-401). All three signal a
@@ -316,7 +326,6 @@ async function syncHomeNpmrcImpl(
       try {
         await mkdir(path.dirname(targetPath), { recursive: true });
         await writeNpmrc(targetPath, result.config, {
-          preserveScopeLines: PRESERVE_NPMRC_SCOPES,
           mode: HOME_NPMRC_MODE,
         });
         deps.logger.info(
@@ -435,7 +444,6 @@ async function syncHomeNpmrcImpl(
     }
 
     await writeNpmrc(targetPath, result.config, {
-      preserveScopeLines: PRESERVE_NPMRC_SCOPES,
       mode: HOME_NPMRC_MODE,
     });
     deps.logger.info(`${LOG_PREFIX} wrote ~/.superblocks/npmrc`, {

package/src/cli-replacement/home-npmrc.test.mts

@@ -20,6 +20,7 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { npmRegistryEmitter } from "@superblocksteam/telemetry";
 import * as npmRegistry from "@superblocksteam/vite-plugin-file-sync/npm-registry";
 import type {
   NpmRegistryClient,
@@ -150,7 +151,50 @@ describe("syncHomeNpmrc", () => {
     snapshotInitialNpmrcMock.mockReset();
   });
 
+  describe("outcome counter", () => {
+    it("emits sync_home_npmrc.outcome_total with the resolved outcome", async () => {
+      const spy = vi
+        .spyOn(npmRegistryEmitter, "recordSyncHomeNpmrc")
+        .mockImplementation(() => {});
+      try {
+        const { client } = makeClient(async () => CONFIGURED);
+        await syncHomeNpmrc({
+          npmRegistryClient: client,
+          logger: asLogger(makeLogger()),
+          homeDir,
+        });
+        expect(spy).toHaveBeenCalledWith("written");
+
+        spy.mockClear();
+        const { client: unreachableClient } = makeClient(
+          async () => UNREACHABLE,
+        );
+        await syncHomeNpmrc({
+          npmRegistryClient: unreachableClient,
+          logger: asLogger(makeLogger()),
+          homeDir,
+        });
+        expect(spy).toHaveBeenCalledWith("skipped-unreachable");
+      } finally {
+        spy.mockRestore();
+      }
+    });
+  });
+
   describe("configured → write", () => {
+    it("force-refreshes the registry config so a cleared registry is seen at sync time, not from a warmed TTL cache", async () => {
+      const { client, getConfig } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(getConfig).toHaveBeenCalledWith({ forceRefresh: true });
+    });
+
     it("writes ~/.superblocks/npmrc with the registry config at mode 0o400", async () => {
       const { client } = makeClient(async () => CONFIGURED);
       const logger = makeLogger();
@@ -242,21 +286,15 @@ describe("syncHomeNpmrc", () => {
       expect(stats.mode & 0o777).toBe(HOME_NPMRC_MODE);
     });
 
-    it("overwrites an image-baked default with the server config when set, but preserves the @superblocksteam scope and its auth", async () => {
-      // EE pods ship with `/home/node/.superblocks/npmrc` pre-populated
-      // with a GHPR scope mapping + token. When the runtime org
-      // configures its own private registry:
-      //   - The server-fetched default registry wins over any baked
-      //     default (none here, but the assertion pins that
-      //     `registry=…artifactory…` line lands).
-      //   - The baked `@superblocksteam:registry=…npm.pkg.github.com/`
-      //     scope mapping must SURVIVE (it's in `PRESERVE_NPMRC_SCOPES`
-      //     so `@superblocksteam/*` packages keep flowing through GHPR).
-      //   - And its matching `//npm.pkg.github.com/:_authToken=…` line
-      //     must survive with it — otherwise every `@superblocksteam/*`
-      //     install 401s against GHPR (APPS-4300). The earlier shape of
-      //     this test asserted the auth line was dropped, which was the
-      //     bug.
+    it("overwrites an image-baked default with the server config, dropping the baked @superblocksteam scope and its auth", async () => {
+      // EE pods no longer ship a baked `@superblocksteam` scope or GHPR
+      // token. The npm proxy now serves `@superblocksteam` as a regular
+      // server-config row, so the live userconfig is rewritten purely from
+      // the server fetch. A leftover baked `@superblocksteam:registry=…
+      // npm.pkg.github.com/` line (e.g. on a pod still running an older
+      // image) is clobbered rather than carried forward — the proxy entry
+      // is the single source for the scope. The baked file is still
+      // captured to `~/.superblocks/npmrc.default` for the restore path.
       const baked =
         "//npm.pkg.github.com/:_authToken=ghpr-baked\n" +
         "@superblocksteam:registry=https://npm.pkg.github.com/\n";
@@ -277,10 +315,12 @@ describe("syncHomeNpmrc", () => {
       expect(content).toContain(
         "registry=https://artifactory.example.com/api/npm/npm/",
       );
-      expect(content).toContain(
+      expect(content).not.toContain(
         "@superblocksteam:registry=https://npm.pkg.github.com/",
       );
-      expect(content).toContain("//npm.pkg.github.com/:_authToken=ghpr-baked");
+      expect(content).not.toContain(
+        "//npm.pkg.github.com/:_authToken=ghpr-baked",
+      );
     });
   });
 

package/src/cli-replacement/package-json-snapshot.mts

@@ -10,6 +10,8 @@ export const MANAGED_PACKAGE_DEPENDENCIES = [
   SUPERBLOCKS_SDK_API_PACKAGE,
 ] as const;
 
+export const MANAGED_OVERRIDE_PACKAGES = ["zod"] as const;
+
 export const PACKAGE_DEPENDENCY_FIELDS = [
   "dependencies",
   "devDependencies",
@@ -197,6 +199,50 @@ function dependencySpecEquals(a: unknown, b: unknown): boolean {
   return JSON.stringify(a) === JSON.stringify(b);
 }
 
+function overridesRecord(
+  packageJson: PackageJsonObject | null,
+): Record<string, unknown> | undefined {
+  const overrides = packageJson?.overrides;
+  if (overrides && typeof overrides === "object" && !Array.isArray(overrides)) {
+    return overrides as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function ensureManagedOverrides(
+  restoredPackageJson: PackageJsonObject,
+  warmPackageJson: PackageJsonObject | null,
+): boolean {
+  const warmOverrides = overridesRecord(warmPackageJson);
+  if (!warmOverrides) {
+    return false;
+  }
+
+  let changed = false;
+  for (const packageName of MANAGED_OVERRIDE_PACKAGES) {
+    const desired = warmOverrides[packageName];
+    if (desired === undefined) {
+      continue;
+    }
+
+    const existingOverrides = overridesRecord(restoredPackageJson);
+    if (
+      existingOverrides &&
+      dependencySpecEquals(existingOverrides[packageName], desired)
+    ) {
+      continue;
+    }
+
+    restoredPackageJson.overrides = {
+      ...(existingOverrides ?? {}),
+      [packageName]: desired,
+    };
+    changed = true;
+  }
+
+  return changed;
+}
+
 async function readPackageJson(cwd: string): Promise<unknown | null> {
   return (await readPackageJsonFile(cwd))?.packageJson ?? null;
 }
@@ -311,6 +357,10 @@ export async function restoreManagedPackageDependencies(
     changed = true;
   }
 
+  if (ensureManagedOverrides(restoredPackageJson, warmPackageJsonObject)) {
+    changed = true;
+  }
+
   if (!changed) {
     return false;
   }