@cats-inc/cats-platform 0.1.10 → 0.2.8

package/build/desktop/main.js

@@ -1,5 +1,5 @@
 import { dirname, join } from 'node:path';
-import { app, BrowserWindow, ipcMain, Notification, session, shell, systemPreferences, } from 'electron';
+import { app, BrowserWindow, dialog, ipcMain, session, shell, systemPreferences, } from 'electron';
 import { buildDesktopBootstrapPage } from './bootstrapPage.js';
 import { resolveDesktopBootstrapNavigation, shouldRevealDesktopBootstrapRecovery, shouldNavigateDesktopBootstrap, resolveDesktopWindowRevealNavigation, shouldAllowDesktopBootstrapWindowNavigation, } from './bootstrapNavigation.js';
 import { resolveCatsHomeDir, resolveDesktopHostConfig, resolveDesktopUserDataDir, } from './config.js';
@@ -12,10 +12,12 @@ import { buildDesktopBootstrapSnapshot, fetchJson, } from './readiness.js';
 import { isDesktopAppOriginUrl, isDesktopHostActionId, resolveDesktopBrowserHandoffUrl, validateDesktopUrl, } from './security.js';
 import { assertMainWindowIpcSender } from './ipcSecurity.js';
 import { readPersistedSetupCompletionState, } from './persistedSetupState.js';
-import { buildDesktopSetupSnapshot, createEmptyDesktopSetupState, runDesktopSetupHelper, shouldAutoRunSetupAudit, } from './setupBridge.js';
+import { buildDesktopSetupSnapshot, createEmptyDesktopSetupState, runDesktopSetupHelper, } from './setupBridge.js';
 import { isDesktopBootstrapLoadingPhase, resolveDesktopBootstrapError, shouldAttemptDesktopLateReadyRecovery, } from './startupRecovery.js';
-import { resolveDefaultSetupAuditAction } from './setupAudit.js';
-import { buildDesktopCliInventoryFromRuntime, } from './cliInventoryProbe.js';
+import { runDesktopUpdateDialog } from './updateDialog.js';
+import { resolveSelectedSetupAuditActions } from './setupAudit.js';
+import { pauseSelectedSetupHelpers, retryPendingSetupOperationReleases, targetsForSetupHelper, withSelectedSetupTargets } from './providerSelection.js';
+import { buildDesktopCliInventoryFromRuntime, probeContradictsCachedBootstrapState, } from './cliInventoryProbe.js';
 import { createDesktopTrayController, } from './tray.js';
 import { buildDesktopTrayMenuState as buildElectronTrayMenuState, buildDesktopTrayQuittingMenuState, } from './trayMenu.js';
 import { applyDesktopHostPlatformShellUpdate, normalizePlatformShellSetupState, parseDesktopHostPlatformShellUpdate, } from './platformShellUpdate.js';
@@ -26,7 +28,6 @@ import { createDesktopUpdateCapability, createDesktopUpdateManager, createUnavai
 import { configureElectronUpdater, createElectronUpdaterAdapter, resolveAutoUpdaterExport, } from './updaterAdapter.js';
 import { createDesktopUpdateIpcHandlers, createDesktopUpdateSnapshotBroadcast, } from './updateIpc.js';
 import { withDesktopInstallHandoff } from './updateInstallHandoff.js';
-import { DESKTOP_UPDATE_SETTINGS_PATH, resolveDesktopUpdateAnnouncement, } from './updateNotifications.js';
 import { applyDesktopWindowChrome, resolveDesktopWindowChromeOptions, } from './windowChrome.js';
 import { resolveDesktopWindowIconPath } from './windowIcon.js';
 import { readDesktopStartupPreferences, resolveDesktopStartupLaunchContext, syncDesktopStartupPreferences, updateDesktopStartupPreferences, DESKTOP_LAUNCH_AT_LOGIN_ARG, } from './desktopStartup.js';
@@ -72,6 +73,7 @@ let runtimeCliInventoryPollTimer = null;
 let runtimeCliInventoryScanPending = false;
 let shuttingDown = false;
 let shutdownPromise = null;
+let setupHelperDrain = null;
 let exitingAfterShutdown = false;
 let trayController = null;
 let stateStore = null;
@@ -118,12 +120,25 @@ function isRuntimeCliInventoryScanActive(probe) {
 function isRuntimeCliInventoryScanErrored(probe) {
     return probe?.state?.status === 'error';
 }
+// Refreshing only when the probe and the cached health payload disagree keeps
+// this off the steady-state path: it fires once, on the transition that
+// actually happened, rather than putting GET /health on a timer.
+function probeContradictsCachedRuntimeHealth(probe) {
+    if (!latestRuntimeHealthPayload) {
+        return false;
+    }
+    const cached = normalizeRuntimeHealthPayload(latestRuntimeHealthPayload);
+    return probeContradictsCachedBootstrapState(probe, cached.readiness?.bootstrapRequired === true || cached.startup?.bootstrapRequired === true);
+}
 function rememberRuntimeCliInventoryProbe(probe) {
     if (!probe) {
         return false;
     }
-    if (probe.scan) {
-        latestCliInventoryProbe = probe;
+    if (latestCliInventoryProbe?.selection?.revision !== probe.selection?.revision) {
+        latestProviderDiagnosticsPayload = null;
+    }
+    latestCliInventoryProbe = probe;
+    if (probe.selection?.state !== 'selected' || (probe.scan && !isRuntimeCliInventoryScanActive(probe))) {
         runtimeCliInventoryScanPending = false;
         clearCliInventoryError();
         return true;
@@ -736,13 +751,31 @@ function buildTrayControllerOptions() {
             void shutdownHost();
         },
         canInteract: () => !shuttingDown,
-        onCheckForUpdates: async () => {
-            if (shuttingDown) {
+        // One item, one handler, whatever state the host is in. The tray closes on
+        // click, so the dialog is where every answer lives -- progress included.
+        onOpenUpdateDialog: async () => {
+            if (shuttingDown || !updateManager) {
                 return;
             }
-            // The menu closes on click, so this result has to reach the user through
-            // a notification or by opening Settings.
-            await refreshUpdateState('tray');
+            await runDesktopUpdateDialog({
+                manager: updateManager,
+                platform: process.platform,
+                locale: app.getLocale(),
+                isShuttingDown: () => shuttingDown,
+                showDialog: async (dialogSpec) => {
+                    const choice = await dialog.showMessageBox({
+                        type: dialogSpec.action === 'none' ? 'info' : 'question',
+                        title: dialogSpec.title,
+                        message: dialogSpec.message,
+                        detail: dialogSpec.detail,
+                        buttons: dialogSpec.buttons,
+                        defaultId: 0,
+                        cancelId: dialogSpec.buttons.length - 1,
+                        noLink: true,
+                    });
+                    return choice.response;
+                },
+            });
         },
     };
 }
@@ -797,11 +830,26 @@ async function getSetupSnapshot() {
     if (!hostConfig) {
         throw new Error('Desktop host is not initialized.');
     }
-    return await buildDesktopSetupSnapshot({
+    const snapshot = await buildDesktopSetupSnapshot({
         config: hostConfig,
         packaging: resolveCurrentPackagingPlan(hostConfig),
         state: setupState ?? createEmptyDesktopSetupState(),
     });
+    const probe = await fetchRuntimeCliInventoryProbe(hostConfig.runtimeBaseUrl);
+    snapshot.helpers = snapshot.helpers.filter((helper) => {
+        if (!probe?.selection)
+            return false;
+        try {
+            return targetsForSetupHelper(helper.id, probe.selection).length > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (snapshot.resumeAction && !snapshot.helpers.some((helper) => helper.id === snapshot.resumeAction.helperId)) {
+        snapshot.resumeAction = null;
+    }
+    return snapshot;
 }
 async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -831,80 +879,39 @@ async function fetchJsonWithTimeout(url, init, timeoutMs) {
     }
     return await response.json();
 }
-function shouldRefreshRuntimeCliInventoryProbe(probe, options) {
-    if (options.triggerScanIfMissing !== true) {
-        return false;
-    }
-    if (runtimeCliInventoryScanPending || isRuntimeCliInventoryScanActive(probe)) {
-        return false;
-    }
-    if (!probe?.scan) {
-        return true;
-    }
-    return !probe.scan.providers.some((provider) => provider.available === true);
-}
 async function fetchRuntimeCliInventoryProbe(baseUrl, options = {}) {
-    const setupStateTimeoutMs = options.setupStateTimeoutMs ?? RUNTIME_SETUP_STATE_TIMEOUT_MS;
-    const scanTimeoutMs = options.scanTimeoutMs ?? RUNTIME_SETUP_SCAN_TIMEOUT_MS;
-    let probe = null;
-    const shouldReadSetupStateFirst = !options.forceRescan || runtimeCliInventoryScanPending;
-    if (shouldReadSetupStateFirst) {
-        try {
-            probe = await fetchJsonWithTimeout(`${baseUrl}/setup-state`, {
-                method: 'GET',
-            }, setupStateTimeoutMs);
-        }
-        catch {
-            if (options.triggerScanIfMissing !== true) {
-                return null;
-            }
-        }
-        if (probe?.scan || isRuntimeCliInventoryScanActive(probe)) {
-            return probe;
-        }
-        if (runtimeCliInventoryScanPending) {
-            return probe;
-        }
-        if (!options.forceRescan && !shouldRefreshRuntimeCliInventoryProbe(probe, options)) {
-            return probe;
-        }
+    await retryPendingSetupOperationReleases();
+    const timeout = options.setupStateTimeoutMs ?? RUNTIME_SETUP_STATE_TIMEOUT_MS;
+    let probe;
+    try {
+        probe = await fetchJsonWithTimeout(`${baseUrl}/setup-state`, { method: 'GET' }, timeout);
+    }
+    catch {
+        return null;
     }
-    // Trigger a fresh scan (none cached before setup, cached zero CLIs, or caller
-    // forced rescan after install/uninstall). The runtime exposes scan progress
-    // through /setup-state, so a host-side HTTP timeout means "poll later", not
-    // "startup failed".
+    // A forced scan still needs a current, nonempty declared selection.
+    if (probe.selection?.state !== 'selected')
+        return probe;
+    if (runtimeCliInventoryScanPending || isRuntimeCliInventoryScanActive(probe))
+        return probe;
+    if (!options.forceRescan && (probe.scan || !options.triggerScanIfMissing))
+        return probe;
     try {
         runtimeCliInventoryScanPending = true;
-        const scanResponse = await fetchWithTimeout(`${baseUrl}/setup-scan`, {
+        const response = await fetchWithTimeout(`${baseUrl}/setup-scan`, {
             method: 'POST',
             headers: { 'content-type': 'application/json', accept: 'application/json' },
-            body: JSON.stringify({ manual: false }),
-        }, scanTimeoutMs);
-        if (!scanResponse.ok) {
+            body: JSON.stringify({ manual: options.forceRescan === true, targets: probe.selection.targets }),
+        }, options.scanTimeoutMs ?? RUNTIME_SETUP_SCAN_TIMEOUT_MS);
+        if (!response.ok)
             runtimeCliInventoryScanPending = false;
-            return probe;
-        }
-    }
-    catch {
-        return probe;
-    }
-    try {
-        return await fetchJsonWithTimeout(`${baseUrl}/setup-state`, {
-            method: 'GET',
-        }, setupStateTimeoutMs);
+        return await fetchJsonWithTimeout(`${baseUrl}/setup-state`, { method: 'GET' }, timeout);
     }
     catch {
+        runtimeCliInventoryScanPending = false;
         return probe;
     }
 }
-function isCliMissingBootstrapSnapshot(snapshot) {
-    if (hostConfig?.bootstrap.onboardingMode !== 'cli_inventory_gate') {
-        return false;
-    }
-    return Boolean(snapshot.phase === 'needs_prerequisites'
-        && snapshot.prerequisites?.cliInventory?.source === 'runtime'
-        && snapshot.prerequisites.cliInventory.total === 0);
-}
 function buildSnapshot(lastError) {
     if (!hostConfig || !supervisor) {
         throw new Error('Desktop host is not initialized.');
@@ -927,6 +934,8 @@ function buildSnapshot(lastError) {
         packaging: packagingState ?? undefined,
         setup: setupState ?? undefined,
         hostStatePath: hostConfig.paths.hostStatePath,
+        providerSelection: latestCliInventoryProbe?.selection ?? null,
+        providerCatalog: latestCliInventoryProbe?.universe ?? [],
         cliInventory: resolveSnapshotCliInventory(),
         cliInventoryError: latestCliInventoryError,
     });
@@ -951,7 +960,7 @@ async function refreshBootstrapSnapshot(persistedSetup = null) {
         ?? await readPersistedSetupCompletionState(hostConfig.paths.appStatePath);
     latestPersistedSetupState = effectivePersistedSetup;
     const setupCompleted = Boolean(effectivePersistedSetup.setupCompleteAt || effectivePersistedSetup.productSetupCompleted);
-    const shouldReadCliInventory = setupCompleted || hostConfig.bootstrap.onboardingMode === 'cli_inventory_gate';
+    const shouldReadCliInventory = true;
     // /diagnostics/providers is intentionally NOT fetched on the boot critical
     // path — it's not authoritative for any phase decision before setup, and
     // for setup-complete users we kick it off in the background (see
@@ -1006,6 +1015,8 @@ async function refreshBootstrapSnapshot(persistedSetup = null) {
         packaging: packagingState ?? undefined,
         setup: setupState ?? undefined,
         hostStatePath: hostConfig.paths.hostStatePath,
+        providerSelection: latestCliInventoryProbe?.selection ?? null,
+        providerCatalog: latestCliInventoryProbe?.universe ?? [],
         cliInventory: resolveSnapshotCliInventory(),
         cliInventoryError: latestCliInventoryError,
     });
@@ -1017,28 +1028,20 @@ function hasPersistedProductSetupCompletion(persistedSetup = null) {
     const productEvents = diagnosticsState?.product?.events ?? [];
     return productEvents.some((event) => event.kind === 'setup_completed' && event.status === 'ok');
 }
-async function maybePrimeSetupAudit(snapshot, persistedSetup = null) {
-    if (!hostConfig) {
-        return;
-    }
-    if (!shouldAutoRunSetupAudit(setupState, {
-        setupCompleteAt: snapshot.app.setupCompleteAt ?? persistedSetup?.setupCompleteAt ?? null,
-        productSetupCompleted: hasPersistedProductSetupCompletion(persistedSetup),
-    })) {
-        return;
-    }
-    const setupAuditAction = resolveDefaultSetupAuditAction(hostConfig);
-    if (!setupAuditAction) {
+const auditedSetupHelpers = new Set();
+async function maybePrimeSetupAudit(_snapshot, _persistedSetup = null) {
+    if (!hostConfig)
         return;
+    const selection = latestCliInventoryProbe?.selection ?? null;
+    for (const action of resolveSelectedSetupAuditActions(selection)) {
+        const key = `${selection.revision}:${action.helperId}`;
+        if (auditedSetupHelpers.has(key))
+            continue;
+        auditedSetupHelpers.add(key);
+        await runSetupAction({ helperId: action.helperId, mode: 'check' }, {
+            publishMode: 'bootstrap-only', refreshBootstrap: false,
+        });
     }
-    await runSetupAction({
-        helperId: setupAuditAction.helperId,
-        mode: 'check',
-        extraArguments: setupAuditAction.extraArguments,
-    }, {
-        publishMode: 'bootstrap-only',
-        refreshBootstrap: false,
-    });
 }
 function scheduleBackgroundSetupAudit(snapshot, persistedSetup = null) {
     if (isDesktopBootstrapLoadingPhase(snapshot.phase) || backgroundSetupAuditPromise) {
@@ -1074,8 +1077,9 @@ async function pollRuntimeCliInventory(options) {
             ? RUNTIME_SETUP_SCAN_TIMEOUT_MS
             : RUNTIME_BOOTSTRAP_SETUP_SCAN_TIMEOUT_MS,
     });
+    const staleRuntimeHealth = probeContradictsCachedRuntimeHealth(probe);
     if (rememberRuntimeCliInventoryProbe(probe)) {
-        const snapshot = publishSnapshot(buildSnapshot());
+        const snapshot = publishSnapshot(staleRuntimeHealth ? await refreshBootstrapSnapshot() : buildSnapshot());
         scheduleBackgroundSetupAudit(snapshot, latestPersistedSetupState);
         await maybeOpenApp(snapshot);
         return;
@@ -1086,6 +1090,13 @@ async function pollRuntimeCliInventory(options) {
         scheduleBackgroundSetupAudit(snapshot, latestPersistedSetupState);
         return;
     }
+    if (staleRuntimeHealth) {
+        // No scan snapshot to publish, but the runtime has still moved on. Pick the
+        // change up rather than republishing a phase built from the stale payload.
+        // Deliberately falls through to the reschedule below: this branch is the
+        // one that keeps waiting for a scan, and it must not stop doing that.
+        publishSnapshot(await refreshBootstrapSnapshot());
+    }
     scheduleRuntimeCliInventoryPoll(options);
 }
 async function retryCliInventoryScanInBackground(options) {
@@ -1107,9 +1118,12 @@ async function retryCliInventoryScanInBackground(options) {
         catch {
             probe = null;
         }
+        const staleRuntimeHealth = probeContradictsCachedRuntimeHealth(probe);
         if (rememberRuntimeCliInventoryProbe(probe)) {
             try {
-                const snapshot = publishSnapshot(buildSnapshot());
+                // This path returns without scheduling a poll, so a stale cached health
+                // payload would survive here until the app restarts.
+                const snapshot = publishSnapshot(staleRuntimeHealth ? await refreshBootstrapSnapshot() : buildSnapshot());
                 scheduleBackgroundSetupAudit(snapshot, latestPersistedSetupState);
                 await maybeOpenApp(snapshot);
             }
@@ -1123,7 +1137,7 @@ async function retryCliInventoryScanInBackground(options) {
             await new Promise((resolve) => setTimeout(resolve, wait));
         }
     }
-    if (!options.setupCompleted && latestSnapshot && isDesktopBootstrapLoadingPhase(latestSnapshot.phase)) {
+    if (runtimeCliInventoryScanPending || isRuntimeCliInventoryScanActive(latestCliInventoryProbe)) {
         scheduleRuntimeCliInventoryPoll({
             setupCompleted: options.setupCompleted,
         });
@@ -1152,21 +1166,16 @@ function scheduleBackgroundBootstrapWork(snapshot, persistedSetup) {
     const setupCompleted = Boolean(snapshot.app.setupCompleteAt
         ?? persistedSetup?.setupCompleteAt
         ?? persistedSetup?.productSetupCompleted);
-    // Prerequisite audit — Node / GitHub CLI / npm prefix detection lives in
-    // the packaged readiness audit, not in cats-runtime's CLI inventory probe.
-    // Fresh users without Node need this signal so the recovery panel can
-    // surface install_node_lts before they fail an Install action.
+    // Run shared Node and local-model checks only for eligible selected targets.
     scheduleBackgroundSetupAudit(snapshot, persistedSetup);
-    // CLI inventory is not part of the default first-run gate. We only probe it
-    // before setup when the legacy env policy explicitly asks for that gate.
-    if (setupCompleted || hostConfig?.bootstrap.onboardingMode === 'cli_inventory_gate') {
-        void retryCliInventoryScanInBackground({
-            forceRescan: setupCompleted,
-            setupCompleted,
-        }).catch((error) => {
-            process.stderr.write(`Background CLI inventory rescan failed: ${error instanceof Error ? error.message : String(error)}\n`);
-        });
-    }
+    // Inventory observes the saved selection; missing/invalid/empty selections
+    // never launch a provider scan. Availability does not gate product onboarding.
+    void retryCliInventoryScanInBackground({
+        forceRescan: false,
+        setupCompleted,
+    }).catch((error) => {
+        process.stderr.write(`Background CLI inventory rescan failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
     // Provider diagnostics — only meaningful after setup is applied. Best
     // effort, single-shot; failures fall back to "Cats can still open".
     if (setupCompleted) {
@@ -1297,7 +1306,17 @@ async function createUpdateManagerForLaunch(config, initialLastCheckedAt = null)
                     // supervisor-lifetime environment snapshot populated during the first
                     // bootstrap, including the Desktop-provisioned platform auth secret.
                     exitingAfterShutdown = false;
-                    await supervisor?.startAll();
+                    try {
+                        await supervisor?.startAll();
+                    }
+                    finally {
+                        // A failed recovery leaves Runtime unavailable, not helper admission
+                        // permanently paused after a later successful Retry.
+                        if (!shuttingDown) {
+                            setupHelperDrain?.resume();
+                            setupHelperDrain = null;
+                        }
+                    }
                     await syncTrayController();
                 },
                 exitAfterUncertainHandoff: async () => {
@@ -1328,77 +1347,6 @@ async function createUpdateManagerForLaunch(config, initialLastCheckedAt = null)
         },
     });
 }
-async function openDesktopUpdateSettings() {
-    if (shuttingDown || !hostConfig) {
-        return;
-    }
-    await showMainWindow(`${hostConfig.appBaseUrl}${DESKTOP_UPDATE_SETTINGS_PATH}`);
-}
-/**
- * Shows a native notification, reporting whether the user will actually see it.
- *
- * A false return sends the caller to the navigation fallback. Notifying is not
- * worth failing a check over, so a throwing platform is treated the same as one
- * without notification support.
- */
-function showDesktopUpdateNotification(notification) {
-    try {
-        const native = new Notification({
-            title: notification.title,
-            body: notification.body,
-        });
-        native.on('click', () => {
-            void openDesktopUpdateSettings();
-        });
-        native.show();
-        return true;
-    }
-    catch (error) {
-        process.stderr.write('[desktop-update] native notification unavailable: '
-            + `${error instanceof Error ? error.message : String(error)}\n`);
-        return false;
-    }
-}
-function areNativeNotificationsSupported() {
-    try {
-        return Notification.isSupported();
-    }
-    catch {
-        return false;
-    }
-}
-async function announceDesktopUpdateResult(origin, snapshot) {
-    if (!snapshot || shuttingDown) {
-        return;
-    }
-    const announcement = resolveDesktopUpdateAnnouncement({
-        origin,
-        snapshot,
-        locale: app.getLocale(),
-        notificationsSupported: areNativeNotificationsSupported(),
-    });
-    if (announcement.notification && showDesktopUpdateNotification(announcement.notification)) {
-        return;
-    }
-    if (announcement.fallbackNavigatePath) {
-        await openDesktopUpdateSettings();
-    }
-}
-/**
- * Runs a check and reports its result to whoever asked for it.
- *
- * The origin is required rather than defaulted: it decides whether the result
- * is announced at all, and a new caller silently inheriting another surface's
- * policy is the failure this signature exists to prevent.
- */
-async function refreshUpdateState(origin) {
-    if (!updateManager) {
-        return null;
-    }
-    updateState = await updateManager.checkForUpdates();
-    await announceDesktopUpdateResult(origin, updateState);
-    return updateState;
-}
 async function bootstrapDesktopHost(restartServices = false) {
     if (!hostConfig || !supervisor) {
         throw new Error('Desktop host is not initialized.');
@@ -1406,7 +1354,9 @@ async function bootstrapDesktopHost(restartServices = false) {
     if (bootstrapPromise) {
         return bootstrapPromise;
     }
+    const helperPause = restartServices ? pauseSelectedSetupHelpers() : null;
     bootstrapPromise = (async () => {
+        await helperPause?.drained;
         latestBootstrapError = null;
         latestCliInventoryError = null;
         runtimeCliInventoryScanPending = false;
@@ -1442,6 +1392,7 @@ async function bootstrapDesktopHost(restartServices = false) {
         const snapshot = publishSnapshot(buildSnapshot());
         return maybeOpenApp(snapshot).then(() => snapshot);
     }).finally(() => {
+        helperPause?.resume();
         bootstrapPromise = null;
     });
     return bootstrapPromise;
@@ -1472,17 +1423,15 @@ async function runHostAction(actionId) {
     }
     if (actionId === 'open_setup') {
         const snapshot = latestSnapshot ?? await refreshBootstrapSnapshot();
-        if (isCliMissingBootstrapSnapshot(snapshot)) {
+        if (!latestCliInventoryProbe?.selection || ['missing', 'invalid'].includes(latestCliInventoryProbe.selection.state))
             return snapshot;
-        }
         await showMainWindow(`${hostConfig.appBaseUrl}/setup`);
         return snapshot;
     }
     if (actionId === 'open_chat') {
         const snapshot = latestSnapshot ?? await refreshBootstrapSnapshot();
-        if (isCliMissingBootstrapSnapshot(snapshot)) {
+        if (!latestCliInventoryProbe?.selection || ['missing', 'invalid'].includes(latestCliInventoryProbe.selection.state))
             return snapshot;
-        }
         await showMainWindow(`${hostConfig.appBaseUrl}${snapshot.app.entryPath}`);
         return snapshot;
     }
@@ -1497,10 +1446,9 @@ async function runSetupAction(action, options = {}) {
         throw new Error('Desktop host is not initialized.');
     }
     const packaging = resolveCurrentPackagingPlan(hostConfig);
-    const result = await runDesktopSetupHelper({
-        config: hostConfig,
-        packaging,
-        action,
+    const result = await withSelectedSetupTargets({
+        baseUrl: hostConfig.runtimeBaseUrl, helperId: action.helperId,
+        run: () => runDesktopSetupHelper({ config: hostConfig, packaging, action }),
     });
     packagingState = packaging;
     setupState = {
@@ -1539,8 +1487,7 @@ async function runSetupAction(action, options = {}) {
     // depend on the helper's runState — the rescan itself is authoritative.
     const setupCompleted = hasPersistedSetupCompletion();
     const shouldRefreshCliInventory = action.mode !== 'check'
-        && shouldRefreshCliInventoryAfterSetupAction(action.helperId)
-        && (setupCompleted || hostConfig.bootstrap.onboardingMode === 'cli_inventory_gate');
+        && shouldRefreshCliInventoryAfterSetupAction(action.helperId);
     if (shouldRefreshCliInventory) {
         const refreshedProbe = await fetchRuntimeCliInventoryProbe(hostConfig.runtimeBaseUrl, {
             forceRescan: true,
@@ -1669,6 +1616,9 @@ function waitForShutdownDeadline(ms) {
  * surviving sidecar may still hold.
  */
 async function drainManagedServices() {
+    setupHelperDrain ??= pauseSelectedSetupHelpers();
+    // Installer completion is outside the sidecar shutdown watchdog budget.
+    await setupHelperDrain.drained;
     const drain = supervisor?.stopAll() ?? Promise.resolve();
     const shutdownWatchdogMs = hostConfig
         ? resolveShutdownWatchdogMs(hostConfig, supervisor?.getManagedServiceCount() ?? 0)
@@ -1692,8 +1642,10 @@ async function shutdownHost() {
         return shutdownPromise;
     }
     shuttingDown = true;
+    setupHelperDrain ??= pauseSelectedSetupHelpers();
     clearRuntimeCliInventoryPoll();
     shutdownPromise = (async () => {
+        await setupHelperDrain.drained;
         let shutdownExitCode = 0;
         let forcedStopAttempted = false;
         const activeTrayController = trayController;
@@ -1738,11 +1690,8 @@ async function main() {
         return;
     }
     app.setPath('userData', resolveDesktopUserDataDir(app.getPath('appData')));
-    // Windows routes a notification through the Start Menu shortcut whose
-    // Application User Model ID matches the running process. The installer writes
-    // that shortcut with the electron-builder appId, so claiming it here is what
-    // makes update notifications visible at all. Unpackaged runs have no such
-    // shortcut, so the claim would buy nothing.
+    // Keep the packaged process identity aligned with the installer-created
+    // Windows shortcuts and taskbar grouping.
     if (process.platform === 'win32' && app.isPackaged && DESKTOP_APP_USER_MODEL_ID) {
         app.setAppUserModelId(DESKTOP_APP_USER_MODEL_ID);
     }
@@ -1858,6 +1807,33 @@ async function main() {
         }
         return await runHostAction(actionId);
     });
+    ipcMain.handle('cats-host:save-provider-selection', async (event, payload) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Provider selection is only available to the main Cats window.');
+        if (!hostConfig || !payload || typeof payload !== 'object')
+            throw new Error('Invalid provider selection.');
+        const body = payload;
+        if ((!Array.isArray(body.targets) && body.reload !== true) || typeof body.expectedRevision !== 'string') {
+            throw new Error('Invalid provider selection.');
+        }
+        await retryPendingSetupOperationReleases();
+        const response = await fetchWithTimeout(`${hostConfig.runtimeBaseUrl}/setup-selection${body.reload === true ? '/reload' : ''}`, {
+            method: body.reload === true ? 'POST' : 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ targets: body.targets, expectedRevision: body.expectedRevision }),
+        }, RUNTIME_SETUP_STATE_TIMEOUT_MS);
+        if (!response.ok) {
+            const result = await response.json();
+            throw new Error(result.error || 'Could not save provider selection.');
+        }
+        latestProviderDiagnosticsPayload = null;
+        latestCliInventoryError = null;
+        runtimeCliInventoryScanPending = false;
+        const snapshot = await refreshBootstrapSnapshot();
+        publishSnapshot(snapshot);
+        scheduleBackgroundBootstrapWork(snapshot, latestPersistedSetupState);
+        await maybeOpenApp(snapshot);
+        return snapshot;
+    });
     ipcMain.handle('cats-host:run-setup-helper', async (_event, payload) => {
         if (typeof payload !== 'object'
             || payload === null
@@ -2054,7 +2030,7 @@ async function main() {
     // SPEC-111 section 6: at most one silent check per launch, and only when the
     // build actually has update capability.
     if (hostConfig.update.checkOnStartup && updateManager?.getSnapshot().capability.canCheck) {
-        void refreshUpdateState('startup');
+        void updateManager.checkForUpdates();
     }
 }
 void main().catch((error) => {