@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

package/dist/cli-replacement/dev.mjs

@@ -13,19 +13,22 @@ import { maskUnixSignals } from "@superblocksteam/util";
 import { AiService, AiServiceFeatureFlags, SnapshotManager, isSdkApiTemplate, stripResolvedFromLockfile, } from "@superblocksteam/vite-plugin-file-sync/ai-service";
 import { createGitService } from "@superblocksteam/vite-plugin-file-sync/git-service";
 import { LockService, LockType, } from "@superblocksteam/vite-plugin-file-sync/lock-service";
+import { 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 { getTracer } from "../telemetry/index.js";
 import { getErrorMeta, getLogger } from "../telemetry/logging.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, packageJsonSnapshot, packageJsonSnapshotDiagnostic, restoreManagedPackageDependencies, } from "./package-json-snapshot.mjs";
 import { getCurrentCliVersion } from "./version-detection.js";
-const exec = promisify(child_process.exec);
 const passErrorToVSCode = (message, 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.
@@ -160,7 +163,7 @@ async function normalizePackageJsonForNpm(cwd, logger) {
         throw new Error(`Failed to write normalized package.json at ${packageJsonPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-async function installPackages(cwd, logger) {
+export async function installPackages(cwd, logger, npmRegistryClient) {
     try {
         const pm = await detect({
             strategies: [
@@ -181,23 +184,144 @@ async function installPackages(cwd, logger) {
             // resolve a published version instead.
             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(`Could not determine install command for ${pm.agent}, skipping package installation`);
             return;
         }
         const { command, args } = installCommand;
         logger.info(`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;
+        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, npmRegistryClient) {
+    let requestedPackages = [];
+    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;
+    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 var DevServerAutoUpgradeMode;
 (function (DevServerAutoUpgradeMode) {
@@ -212,8 +336,61 @@ export var DevServerAutoUpgradeMode;
      */
     DevServerAutoUpgradeMode["SKIP_CLI_ONLY"] = "skip-cli-only";
 })(DevServerAutoUpgradeMode || (DevServerAutoUpgradeMode = {}));
+/**
+ * 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, token) {
+    if (token) {
+        tokenManager.updateToken(token);
+    }
+}
+/** 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, status, logger) {
+    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) {
     const { cwd, tokenConfig, devServerPort, skipSync, applicationConfig, autoUpgradeMode, tokenManager, authHotReloadServer, 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;
     // Services that will be created
@@ -224,17 +401,40 @@ export async function dev(options) {
     let snapshotManager;
     let gitUserName;
     let gitUserEmail;
-    // 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;
     let packageInstallPromise;
     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) => {
+        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) => {
         if (!packageInstallPromise) {
             return;
@@ -244,10 +444,34 @@ 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) => {
+        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) => {
+        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 = { serverErrors: [] };
         try {
             // Add check for node_modules
             if (!fs.existsSync(path.join(cwd, "node_modules"))) {
@@ -536,15 +760,39 @@ export async function dev(options) {
                         else if (downloadFirst && isSynced) {
                             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 = [];
                         const forceUpgrade = options.autoUpgradeMode === DevServerAutoUpgradeMode.FORCE;
@@ -565,7 +813,10 @@ export async function dev(options) {
                                         organizationId: currentUser.user.currentOrganizationId,
                                         featureFlags: sdk.getFeatureFlagsForUser(currentUser),
                                     };
-                                    const result = await checkVersionsAndWritePackageJson(lockService, applicationConfigWithTokenConfigAndUserInfo, forceUpgrade, skipCliUpgrade);
+                                    const result = await checkVersionsAndWritePackageJson(lockService, 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;
                                 }
@@ -622,6 +873,33 @@ export async function dev(options) {
                             packageJsonInstallBaselineSnapshot: packageJsonSnapshotDiagnostic(packageJsonInstallBaselineSnapshot),
                             packageJsonSnapshotAfter: packageJsonSnapshotDiagnostic(packageJsonSnapshotAfter),
                         });
+                        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 ||
                             forcePackageInstall) {
@@ -634,29 +912,19 @@ export async function dev(options) {
                             logger.info("Starting package install in background…");
                             packageInstallPromise = tracer.startActiveSpan("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}]`, getErrorMeta(err));
+                                `Background package install failed [errorId=DEV_SERVER_BG_INSTALL_FAILED applicationId=${installApplicationId} cwd=${cwd}]`, getErrorMeta(err));
                             });
                         }
                         else {
@@ -665,19 +933,49 @@ export async function dev(options) {
                         const shouldUploadPackageState = 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();
@@ -692,14 +990,20 @@ export async function dev(options) {
                     });
                 }
                 catch (error) {
-                    logger.error("[dev-server] Startup failed during sync/lock/setup (exiting with code 1)", getErrorMeta(error));
-                    try {
-                        await aiService?.removeIntegrationCache();
-                        await lockService?.shutdownAndExit();
+                    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).
                     }
-                    finally {
-                        // this is redundant, but it's here to make sure the lock service is shutdown and the process exits
-                        process.exit(1);
+                    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);
+                        }
                     }
                 }
             }
@@ -713,7 +1017,36 @@ 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 () => {
                 if (gitService) {
                     const hasGit = await nodeFs.access(path.join(cwd, ".git")).then(() => true, () => false);
@@ -816,9 +1149,7 @@ export async function dev(options) {
                     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.
+                    devServerStatus,
                 };
                 const result = await createDevServer(createDevServerOptions);
                 span.end();
@@ -833,13 +1164,16 @@ 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) => {
+                    logger.warn("Error draining background upgrade during abort", getErrorMeta(error));
+                });
                 joinPackageInstall("during abort").catch((error) => {
                     logger.warn("Error draining background install during abort", getErrorMeta(error));
                 });