@superblocksteam/sdk 2.0.123-next.0 → 2.0.124-next.0

package/src/cli-replacement/dev.mts

@@ -11,6 +11,7 @@ import fs from "fs-extra";
 import { resolveCommand } from "package-manager-detector";
 import { detect } from "package-manager-detector/detect";
 
+import type { ServerError } from "@superblocksteam/library-shared/types";
 import {
   buildGithubSuperblocksSyncWorkflow,
   buildGithubSuperblocksSyncWorkflowFromBaseUrl,
@@ -35,10 +36,16 @@ import {
   LockService,
   LockType,
 } from "@superblocksteam/vite-plugin-file-sync/lock-service";
+import {
+  type NpmRegistryClient,
+  type ParseContext,
+  shouldIgnoreInstallScripts,
+} from "@superblocksteam/vite-plugin-file-sync/npm-registry";
 import { OperationQueue } from "@superblocksteam/vite-plugin-file-sync/operation-queue";
 import { AutoConnectingRpcClient } from "@superblocksteam/vite-plugin-file-sync/server-rpc";
 import { SyncService } from "@superblocksteam/vite-plugin-file-sync/sync-service";
 
+import { devServerMetrics } from "../dev-utils/dev-server-metrics.mjs";
 import { createDevServer } from "../dev-utils/dev-server.mjs";
 import { AUTO_UPGRADE_EXIT_CODE } from "../index.js";
 import type {
@@ -54,11 +61,23 @@ import type {
   ApplicationConfigWithTokenConfigAndUserInfo,
   TokenConfig,
 } from "../types/index.js";
-import { checkVersionsAndWritePackageJson } from "./automatic-upgrades.js";
+import {
+  buildInstallEnv,
+  checkVersionsAndWritePackageJson,
+} from "./automatic-upgrades.js";
+import {
+  classifyInitialInstallError,
+  InitialInstallFailed,
+} from "./dependency-install-classifier.mjs";
 import {
   ensureRemoteHasDefaultBranch,
   getGitErrorFields,
 } from "./git-repo-setup.mjs";
+import {
+  superblocksLogsPath,
+  superblocksNpmrcPath,
+  syncHomeNpmrc,
+} from "./home-npmrc.mjs";
 import { normalizeWorkspaceProtocolForNpm } from "./normalize-workspace-protocol.js";
 import {
   didPackageJsonSnapshotChange,
@@ -69,8 +88,6 @@ import {
 } from "./package-json-snapshot.mjs";
 import { getCurrentCliVersion } from "./version-detection.js";
 
-const exec = promisify(child_process.exec);
-
 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.
@@ -246,7 +263,11 @@ async function normalizePackageJsonForNpm(cwd: string, logger: Logger) {
   }
 }
 
-async function installPackages(cwd: string, logger: Logger) {
+export async function installPackages(
+  cwd: string,
+  logger: Logger,
+  npmRegistryClient?: NpmRegistryClient,
+) {
   try {
     const pm = await detect({
       strategies: [
@@ -272,11 +293,41 @@ async function installPackages(cwd: string, logger: Logger) {
       await normalizePackageJsonForNpm(cwd, logger);
     }
 
-    const installCommand = resolveCommand(
-      pm.agent,
-      "install",
-      pm.agent === "npm" ? ["--fund=false", "--audit=false"] : [],
-    );
+    // Honor the per-org `allow_install_scripts` policy on the dev-server
+    // startup install just like AppShell does for agent-driven installs
+    // (see `shell.ts`). When the org has opted out (`allowInstallScripts ===
+    // false`), append `--ignore-scripts` so lifecycle scripts don't run
+    // during dev-server boot. `undefined` (LD flag off, server omitted the
+    // field, no client wired up, or the resolution itself failed) keeps
+    // today's behaviour. The client owns last-known-good / cross-outage
+    // policy preservation; we deliberately swallow resolution errors here
+    // so a transient registry-endpoint outage doesn't abort the user's
+    // startup install — the policy default is "scripts allowed" anyway.
+    let ignoreScripts = false;
+    if (npmRegistryClient) {
+      try {
+        const result = await npmRegistryClient.getConfig();
+        ignoreScripts = shouldIgnoreInstallScripts(result);
+      } catch (err) {
+        logger.warn(
+          "Could not resolve npm install-scripts policy; proceeding without --ignore-scripts",
+          getErrorMeta(err),
+        );
+      }
+    }
+
+    // `--json` makes npm channel the structured error envelope (code +
+    // summary + detail) onto stdout so a failure can be classified into a
+    // DependencyInstallError. Output-only: it does not change resolution,
+    // only how npm reports it. The success-path `logger.info(stdout)` below
+    // then logs JSON, which is acceptable.
+    const baseArgs =
+      pm.agent === "npm" ? ["--fund=false", "--audit=false", "--json"] : [];
+    const installArgs = ignoreScripts
+      ? [...baseArgs, "--ignore-scripts"]
+      : baseArgs;
+
+    const installCommand = resolveCommand(pm.agent, "install", installArgs);
 
     if (!installCommand) {
       logger.warn(
@@ -290,15 +341,117 @@ async function installPackages(cwd: string, logger: Logger) {
       `Running ${command} ${args.join(" ")} to install dependencies…`,
     );
 
+    // Pin both npm and pnpm to the Superblocks-owned userconfig via env
+    // overlay. `buildInstallEnv` (from `automatic-upgrades.ts`) sets
+    // both `NPM_CONFIG_USERCONFIG` (npm, pnpm <= 10) and
+    // `PNPM_CONFIG_USERCONFIG` (pnpm 11+) — pnpm 11 stopped honouring
+    // the `npm_config_*` env vars. CLI flags differ between agents
+    // (`--userconfig=` for npm, `--config.userconfig=` for pnpm), so
+    // the env overlay is the uniform mechanism. Without this, customer
+    // pods using a private registry would read default `~/.npmrc`
+    // (empty after the relocation) and fail to resolve private
+    // packages. Centralised in `buildInstallEnv` so this and the CLI
+    // auto-upgrade install stay in sync.
+    // Ensure the per-app log dir exists so npm's debug log (routed via
+    // `NPM_CONFIG_LOGS_DIR` in `buildInstallEnv`) lands in a predictable
+    // place. npm would create it on demand, but doing it up front means the
+    // folder exists even for pnpm runs (which ignore the var) and for any
+    // log-collection sidecar watching `<app>/.superblocks/logs`.
+    const logsDir = superblocksLogsPath(cwd);
+    await nodeFs.mkdir(logsDir, { recursive: true }).catch(() => undefined);
+
+    // Resolve the promisified `exec` at CALL time — not module scope — so a
+    // test's `vi.mock("node:child_process")` is always honoured regardless of
+    // when `dev.mjs` was first evaluated. A module-scope capture binds to
+    // whichever `child_process.exec` was live at first import; if a sibling
+    // test imports this module before installing its own mock (e.g.
+    // `dev-token-priming` / `dev.interception`, which don't mock
+    // `child_process`), that binding is the REAL npm and the classify test's
+    // mock silently never takes effect — the exact APPS-4450 CI failure
+    // (`category: "unknown"`, `npmErrorCode: undefined` from real npm against a
+    // missing `/tmp/app`).
+    const exec = promisify(child_process.exec);
     const { stdout } = await exec(`${command} ${args.join(" ")}`, {
       cwd,
+      env: buildInstallEnv(superblocksNpmrcPath(), logsDir),
     });
     logger.info("Package installation completed successfully");
     logger.info(stdout);
   } catch (error) {
     logger.error("Error during package installation", getErrorMeta(error));
-    throw error;
+    // `util.promisify(child_process.exec)` preserves `.stdout`/`.stderr` on
+    // the rejected error separately; with `--json`, the structured npm error
+    // envelope lands on `.stdout`. Classify it into a DependencyInstallError
+    // and throw the `InitialInstallFailed` marker so the `dev()` catch can
+    // degrade by origin rather than crash-looping the dev-server pod.
+    const ctx = await buildInstallParseContext(cwd, npmRegistryClient);
+    const f = error as { stdout?: string; stderr?: string; message?: string };
+    const serverError = classifyInitialInstallError(
+      { stdout: f.stdout, stderr: f.stderr, message: f.message },
+      ctx,
+    );
+    throw new InitialInstallFailed(serverError);
+  }
+}
+
+/**
+ * Build the `ParseContext` the dependency-install classifier needs from the
+ * failing install's working directory + registry client:
+ *
+ *   - `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.
+ *
+ * Best-effort throughout: a missing/unparseable package.json or a registry
+ * outage must not mask the underlying install failure, so both lookups are
+ * caught and degrade to empty/undefined.
+ */
+async function buildInstallParseContext(
+  cwd: string,
+  npmRegistryClient?: NpmRegistryClient,
+): Promise<ParseContext> {
+  let requestedPackages: { name: string; version?: string }[] = [];
+  try {
+    const pkg = JSON.parse(
+      await nodeFs.readFile(path.join(cwd, "package.json"), "utf8"),
+    );
+    requestedPackages = Object.entries({
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+    }).map(([name, version]) => ({ name, version: String(version) }));
+  } catch {
+    /* 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 */
+    }
   }
+
+  return { requestedPackages, hasAnyRegistryConfigured };
 }
 
 export enum DevServerAutoUpgradeMode {
@@ -314,6 +467,67 @@ export enum DevServerAutoUpgradeMode {
   SKIP_CLI_ONLY = "skip-cli-only",
 }
 
+/**
+ * Seed `tokenManager` with the initial token the CLI received from auth.json
+ * (standalone dev) or `/_sb_activate` (SABS live-edit pod activation), so the
+ * `NpmRegistryClient`'s JWT source has a usable bearer credential on cold
+ * boot.
+ *
+ * Without this seeding, `TokenManager.updateToken` is only ever called by
+ * `AuthHotReloadServer` (`auth-hot-reload.mts`) — and that socket is
+ * explicitly disabled on live-edit pods (`sabs/entrypoint-local.sh` sets
+ * `SUPERBLOCKS_AUTH_HOT_RELOAD=false`), so `NpmRegistryClient.getConfig()`
+ * cannot authenticate its server fetch on cold boot. The result is
+ * `source: "unreachable"`, `syncHomeNpmrc` skips with `~/.npmrc` left
+ * untouched, and the CLI auto-upgrade that fires moments later resolves
+ * `npm install -g @superblocksteam/cli@…` through public npm instead of the
+ * customer's configured private registry.
+ *
+ * Call-site ordering is intentionally NOT load-bearing: `TokenManager`
+ * retains the current token as state and `AiService` reads
+ * `tokenManager.getCurrentToken()` synchronously at construction time, so
+ * the prime call works whether it runs before or after consumer
+ * construction. The `tokenUpdated` event stream stays as the refresh
+ * channel for future rotations (hot-reload pushes, JWT renewal), so this
+ * seed is purely additive.
+ */
+export function primeTokenManagerWithInitialToken(
+  tokenManager: TokenManager,
+  token: string,
+): void {
+  if (token) {
+    tokenManager.updateToken(token);
+  }
+}
+
+export interface DevServerStatus {
+  serverErrors: ServerError[];
+}
+
+/** 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. */
+export function handleStartupError(
+  error: unknown,
+  status: DevServerStatus,
+  logger: Logger,
+): "degrade" | "exit" {
+  if (error instanceof InitialInstallFailed) {
+    status.serverErrors.push(error.serverError);
+    logger.error(
+      "[dev-server] initial dependency install failed; keeping dev server up",
+      getErrorMeta(error),
+    );
+    devServerMetrics.recordInitialInstallFailure({
+      category: error.serverError.category,
+      npmErrorCode: error.serverError.npmErrorCode,
+      hasAnyRegistryConfigured: error.serverError.hasAnyRegistryConfigured,
+    });
+    return "degrade";
+  }
+  return "exit";
+}
+
 export async function dev(options: {
   /* cwd is required */
   cwd: string;
@@ -380,6 +594,15 @@ export async function dev(options: {
     sdk,
   } = options;
 
+  // Seed the tokenManager with the initial CLI token so downstream consumers
+  // (AiService, AutoConnectingRpcClient, syncHomeNpmrc) have a usable
+  // bearer credential without waiting on the AuthHotReloadServer push
+  // refresh (which is disabled on live-edit pods). Order-independent: the
+  // manager retains state and AiService reads it synchronously during
+  // construction. See `primeTokenManagerWithInitialToken` for the
+  // cold-boot rationale.
+  primeTokenManagerWithInitialToken(tokenManager, tokenConfig.token);
+
   // May be overridden by a pending snapshot restore
   let { downloadFirst, uploadFirst } = options;
 
@@ -391,17 +614,40 @@ export async function dev(options: {
   let snapshotManager: SnapshotManager | undefined;
   let gitUserName: string | undefined;
   let gitUserEmail: string | undefined;
-  // In-flight install handle. We launch the install while the upload/restart
-  // decisions are still being evaluated and join at every gate that depends
-  // on post-install state. See the install block and `joinPackageInstall`.
+  // In-flight handles for the two background jobs we launch from sync.
+  // 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.
+  //
+  //   - 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)`.
+  //   - packageInstallPromise: the app's verification `npm install`.
+  //     Rejection MAY be the `InitialInstallFailed` marker, which
+  //     `handleStartupError` 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 install at any step that depends on a settled
-  // node_modules / lockfile state. Clears the handle so later joins are
-  // no-ops. The rejection (if any) propagates so the caller's step can
-  // abort cleanly. Defined at outer scope so the post-sync `createDevServer`
-  // gate and the abort handler can call it too.
+  // 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).
+  const joinPackageUpgrade = async (reason: string): Promise<void> => {
+    if (!packageUpgradePromise) {
+      return;
+    }
+    logger.info(`Waiting for background package upgrade (${reason})…`);
+    const promise = packageUpgradePromise;
+    packageUpgradePromise = undefined;
+    await promise;
+  };
+  // Joins the in-flight install. Rejection propagates so the caller's step
+  // can abort cleanly (handleStartupError degrades for InitialInstallFailed,
+  // exits otherwise).
   const joinPackageInstall = async (reason: string): Promise<void> => {
     if (!packageInstallPromise) {
       return;
@@ -411,12 +657,36 @@ export async function dev(options: {
     packageInstallPromise = undefined;
     await promise;
   };
+  // Settles the in-flight install WITHOUT throwing. Used on the CLI-restart
+  // path so an install failure doesn't preempt the restart (the new CLI's
+  // first boot re-runs install). Still waits for npm to finish so we don't
+  // SIGKILL it mid-rename.
+  const settlePackageInstall = async (reason: string): Promise<void> => {
+    if (!packageInstallPromise) {
+      return;
+    }
+    logger.info(`Settling background package install (${reason})…`);
+    const promise = packageInstallPromise;
+    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.
+  const joinUpgradeThenInstall = async (reason: string): Promise<void> => {
+    await joinPackageUpgrade(reason);
+    await joinPackageInstall(reason);
+  };
   const skipAutoUpgrade = autoUpgradeMode === DevServerAutoUpgradeMode.SKIP;
   const skipCliUpgrade =
     skipAutoUpgrade ||
     autoUpgradeMode === DevServerAutoUpgradeMode.SKIP_CLI_ONLY;
 
   await tracer.startActiveSpan("devServerStartup", async (startupSpan) => {
+    // Mutable startup status surfaced to the browser via createDevServer's
+    // /_sb_connect + /_sb_status. The startup catch records an app-install
+    // failure here (degrade path) so Vite still starts and serves the error.
+    const devServerStatus: DevServerStatus = { serverErrors: [] };
     try {
       // Add check for node_modules
       if (!fs.existsSync(path.join(cwd, "node_modules"))) {
@@ -830,16 +1100,44 @@ export async function dev(options: {
               logger.info("[dev-startup] Skipping download, already in sync");
             }
 
-            // Unconditional lockfile sanitation: strip cross-registry
-            // `resolved` URLs from any lockfile on disk regardless of whether
-            // install runs next. The lockfile here is whatever survived the
-            // DBFS path (downloadFirst overwrite, prior boot, brownfield
-            // import); npm honors `resolved` verbatim and would bypass the
-            // active registry. `integrity` is preserved, so genuine
-            // cross-registry tarball drift surfaces as EINTEGRITY. No-op when
-            // there's no lockfile or no `resolved` entries.
+            // Unconditional lockfile sanitation (APPS-4300): strip
+            // cross-registry `resolved` URLs from any lockfile on disk
+            // regardless of whether install runs next. The lockfile here is
+            // whatever survived the DBFS path (downloadFirst overwrite,
+            // prior boot, brownfield import); npm honors `resolved` verbatim
+            // and would bypass the active registry. `integrity` is
+            // preserved, so genuine cross-registry tarball drift surfaces as
+            // EINTEGRITY. No-op when there's no lockfile or no `resolved`
+            // entries.
             await stripResolvedFromLockfile(cwd);
 
+            // Materialise `~/.superblocks/npmrc` from the server-fetched
+            // per-org npm registry config BEFORE the global Superblocks CLI
+            // auto-upgrade fires. With the file in place, the auto-upgrade's
+            // `npm install -g @superblocksteam/cli@…` resolves through the
+            // customer's private registry instead of `registry.npmjs.org`.
+            await tracer.startActiveSpan("syncHomeNpmrc", async (span) => {
+              try {
+                if (!aiService) {
+                  logger.info(
+                    "[home-npmrc] skipped: AiService unavailable at startup",
+                  );
+                  return;
+                }
+                await syncHomeNpmrc({
+                  npmRegistryClient: aiService.getNpmRegistryClient(),
+                  logger,
+                });
+              } catch (error) {
+                logger.warn(
+                  "[home-npmrc] sync step failed unexpectedly; ~/.superblocks/npmrc left untouched",
+                  getErrorMeta(error),
+                );
+              } finally {
+                span.end();
+              }
+            });
+
             let hasCliUpdated = false;
             let upgradePromises: Promise<void>[] = [];
             const forceUpgrade =
@@ -871,6 +1169,9 @@ export async function dev(options: {
                       applicationConfigWithTokenConfigAndUserInfo,
                       forceUpgrade,
                       skipCliUpgrade,
+                      // Route the CLI-upgrade install's npm debug log into the
+                      // same `<app>/.superblocks/logs` as the startup install.
+                      cwd,
                     );
                     hasCliUpdated = result.cliUpdated;
                     upgradePromises = result.upgradePromises;
@@ -948,6 +1249,40 @@ export async function dev(options: {
               ),
             });
 
+            const installApplicationId = applicationConfig.id;
+
+            // 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.
+            if (upgradePromises.length > 0) {
+              logger.info("Starting package upgrade in background…");
+              const launchedUpgradeCount = upgradePromises.length;
+              packageUpgradePromise = tracer.startActiveSpan(
+                "packageUpgrades",
+                async (span) => {
+                  try {
+                    await Promise.all(upgradePromises);
+                  } finally {
+                    span.end();
+                  }
+                },
+              );
+              packageUpgradePromise.catch((err) => {
+                logger.error(
+                  `Background package upgrade failed [errorId=DEV_SERVER_BG_UPGRADE_FAILED applicationId=${installApplicationId} cwd=${cwd} upgradePromiseCount=${launchedUpgradeCount}]`,
+                  getErrorMeta(err),
+                );
+              });
+            }
+
+            // Run the verification install when EITHER the package.json
+            // requires it, or upgrades just modified package.json/lockfile
+            // (re-syncing node_modules), or the caller forced it. Mirrors
+            // the original launch condition.
             if (
               packageJsonRequiresInstall ||
               upgradePromises.length > 0 ||
@@ -964,29 +1299,23 @@ export async function dev(options: {
                 "installPackages",
                 async (span) => {
                   try {
-                    // Upgrade global CLI and local packages in parallel - improves performance
-                    await Promise.all([
-                      ...upgradePromises,
-                      installPackages(cwd, logger),
-                    ]);
+                    await installPackages(
+                      cwd,
+                      logger,
+                      aiService?.getNpmRegistryClient(),
+                    );
                   } finally {
                     span.end();
                   }
                 },
               );
-              // Backstop: assigning `.catch` to a separate (discarded) promise
-              // keeps `packageInstallPromise` itself rejecting, so the joins
-              // can still observe and abort. Without this, an install that
-              // fails before any join fires becomes an unhandled rejection.
-              const installApplicationId = applicationConfig.id;
-              const installUpgradeCount = upgradePromises.length;
               packageInstallPromise.catch((err) => {
                 logger.error(
                   // errorId is encoded into the message body because the
                   // logger.error contract limits structured attributes to
                   // `{ error: { kind, message, stack } }`. The id stays
                   // grep-able for Datadog/Sentry alert rules.
-                  `Background package install failed [errorId=DEV_SERVER_BG_INSTALL_FAILED applicationId=${installApplicationId} cwd=${cwd} upgradePromiseCount=${installUpgradeCount}]`,
+                  `Background package install failed [errorId=DEV_SERVER_BG_INSTALL_FAILED applicationId=${installApplicationId} cwd=${cwd}]`,
                   getErrorMeta(err),
                 );
               });
@@ -1000,25 +1329,57 @@ export async function dev(options: {
               hasPackageChanged || forcePackageInstall;
             if (shouldUploadPackageState || uploadFirst) {
               // Upload serializes the post-install lockfile + node_modules
-              // tree to DBFS, so it must observe a quiesced install.
-              await joinPackageInstall("before upload");
-              logger.info(
-                `Uploading local files to branch '${activeDbfsBranchName}' on server before starting`,
-              );
-              await tracer.startActiveSpan(
-                "uploadFirstOrPackageChanged",
-                async (span) => {
-                  await syncService!.uploadDirectory("cli:sdk");
-                  await syncService!.uploadDirectoryNowIfNeeded("cli:sdk");
-                  span.end();
-                },
-              );
+              // 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).
+              //
+              // BUT: if a successful CLI upgrade is pending restart
+              // (`hasCliUpdated`), the restart branch below MUST win over
+              // the install-failure degrade path. Otherwise the outer
+              // sync/setup catch routes `InitialInstallFailed` to "degrade"
+              // and skips the restart entirely — masking a successful CLI
+              // upgrade. Catch ONLY the join (not the upload body) so a
+              // post-join upload failure still propagates normally.
+              let skipStartupUploadForCliRestart = false;
+              try {
+                await joinUpgradeThenInstall("before upload");
+              } catch (joinError) {
+                if (
+                  hasCliUpdated &&
+                  joinError instanceof InitialInstallFailed
+                ) {
+                  logger.info(
+                    "Initial package install failed before startup upload, but CLI was updated; skipping upload and letting the restart proceed",
+                  );
+                  skipStartupUploadForCliRestart = true;
+                } else {
+                  throw joinError;
+                }
+              }
+              if (!skipStartupUploadForCliRestart) {
+                logger.info(
+                  `Uploading local files to branch '${activeDbfsBranchName}' on server before starting`,
+                );
+                await tracer.startActiveSpan(
+                  "uploadFirstOrPackageChanged",
+                  async (span) => {
+                    await syncService!.uploadDirectory("cli:sdk");
+                    await syncService!.uploadDirectoryNowIfNeeded("cli:sdk");
+                    span.end();
+                  },
+                );
+              }
             }
 
             if (hasCliUpdated) {
-              // Exiting mid-install would leave a half-written lockfile that
-              // the next boot would have to recover from.
-              await joinPackageInstall("before CLI restart");
+              // Restart must NOT be preempted by an app-install failure:
+              // the next boot re-runs install with the new CLI. Join the
+              // upgrade (it must succeed or we exit before restarting) and
+              // SETTLE the install (don't observe its rejection — but wait
+              // for npm to finish so the restart doesn't SIGKILL it
+              // mid-rename and leave a half-written lockfile).
+              await joinPackageUpgrade("before CLI restart");
+              await settlePackageInstall("before CLI restart");
               try {
                 logger.info("Releasing lock before restarting the dev server");
                 await aiService?.removeIntegrationCache();
@@ -1034,16 +1395,23 @@ export async function dev(options: {
             }
           });
         } catch (error: any) {
-          logger.error(
-            "[dev-server] Startup failed during sync/lock/setup (exiting with code 1)",
-            getErrorMeta(error),
-          );
-          try {
-            await aiService?.removeIntegrationCache();
-            await lockService?.shutdownAndExit();
-          } finally {
-            // this is redundant, but it's here to make sure the lock service is shutdown and the process exits
-            process.exit(1);
+          if (
+            handleStartupError(error, devServerStatus, logger) === "degrade"
+          ) {
+            // app-install failure: do NOT exit — fall through to Vite startup below.
+            // upload + CLI-restart were already skipped (the rejecting join threw first).
+          } else {
+            logger.error(
+              "[dev-server] Startup failed during sync/lock/setup (exiting with code 1)",
+              getErrorMeta(error),
+            );
+            try {
+              await aiService?.removeIntegrationCache();
+              await lockService?.shutdownAndExit();
+            } finally {
+              // this is redundant, but it's here to make sure the lock service is shutdown and the process exits
+              process.exit(1);
+            }
           }
         }
       } else {
@@ -1057,7 +1425,37 @@ export async function dev(options: {
       // cache embeds partial state that survives across reloads. Awaiting
       // here costs at most the install's remaining wall time — the upload
       // and CLI-restart joins above usually drain it first.
-      await joinPackageInstall("before Vite startup");
+      // 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.
+      // `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)`).
+      try {
+        await joinUpgradeThenInstall("before Vite startup");
+      } catch (error) {
+        if (handleStartupError(error, devServerStatus, logger) === "exit") {
+          logger.error(
+            "[dev-server] Startup failed during pre-Vite install join (exiting with code 1)",
+            getErrorMeta(error),
+          );
+          try {
+            await aiService?.removeIntegrationCache();
+            await lockService?.shutdownAndExit();
+          } finally {
+            // Redundant with `shutdownAndExit`; here so a thrown shutdown
+            // path can't leave the process hanging on a stuck handle.
+            process.exit(1);
+          }
+        }
+      }
 
       const activateRuntimeGitService = async (): Promise<
         GitService | undefined
@@ -1158,27 +1556,26 @@ export async function dev(options: {
       const httpServer = await tracer.startActiveSpan(
         "createDevServer",
         async (span) => {
-          const createDevServerOptions = {
-            root: options.cwd,
-            mode: "development",
-            port: port,
-            fsOperationQueue,
-            syncService: syncService,
-            lockService: lockService,
-            aiService: aiService,
-            gitService: gitService,
-            gitBootstrapFailed: devStartupGitOutcome === "bootstrap_failed",
-            activateGitService: activateRuntimeGitService,
-            snapshotManager: snapshotManager,
-            logger: options.logger,
-            sdk,
-            superblocksBaseUrl: tokenConfig.superblocksBaseUrl,
-            existingServer: options.existingServer,
-            warmActivationStart: options.warmActivationStart,
-            // TODO: Remove this cast — build the options object to match
-            // CreateDevServerOptions directly so new required fields cause a
-            // compile error instead of silently passing undefined.
-          } as unknown as Parameters<typeof createDevServer>[0];
+          const createDevServerOptions: Parameters<typeof createDevServer>[0] =
+            {
+              root: options.cwd,
+              mode: "development",
+              port: port,
+              fsOperationQueue,
+              syncService: syncService,
+              lockService: lockService,
+              aiService: aiService,
+              gitService: gitService,
+              gitBootstrapFailed: devStartupGitOutcome === "bootstrap_failed",
+              activateGitService: activateRuntimeGitService,
+              snapshotManager: snapshotManager,
+              logger: options.logger,
+              sdk,
+              superblocksBaseUrl: tokenConfig.superblocksBaseUrl,
+              existingServer: options.existingServer,
+              warmActivationStart: options.warmActivationStart,
+              devServerStatus,
+            };
           const result = await createDevServer(createDevServerOptions);
           span.end();
           return result;
@@ -1194,13 +1591,19 @@ export async function dev(options: {
             logger.warn(`Error stopping auth hot-reload server: ${error}`);
           });
         }
-        // Drain any straggler install before tear-down. By this point the
-        // pre-Vite join has already run on the success path, so usually
-        // `packageInstallPromise` is undefined and this is a no-op; if abort
+        // Drain any straggler upgrade/install before tear-down. By this
+        // point the pre-Vite join has already run on the success path, so
+        // usually both promises are undefined and this is a no-op; if abort
         // races createDevServer (or fires during the inner sync block on
-        // some error path), draining here keeps the spawned npm child from
-        // being SIGKILL'd mid-rename. Errors only get logged — we are tearing
-        // down anyway.
+        // some error path), draining here keeps the spawned npm children
+        // from being SIGKILL'd mid-rename. Errors only get logged — we are
+        // tearing down anyway.
+        joinPackageUpgrade("during abort").catch((error: unknown) => {
+          logger.warn(
+            "Error draining background upgrade during abort",
+            getErrorMeta(error),
+          );
+        });
         joinPackageInstall("during abort").catch((error: unknown) => {
           logger.warn(
             "Error draining background install during abort",