@cats-inc/cats-platform 0.1.21 → 0.3.4

package/build/desktop/main.js

@@ -1,5 +1,5 @@
 import { dirname, join } from 'node:path';
-import { app, BrowserWindow, dialog, 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,13 @@ 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 { resolveDesktopUpdateDialog } from './updateDialog.js';
-import { resolveDefaultSetupAuditAction } from './setupAudit.js';
+import { runDesktopUpdateDialog } from './updateDialog.js';
+import { isDesktopPrerequisiteHelper, resolveSelectedSetupAuditActions } from './setupAudit.js';
+import { DesktopPrerequisiteChecks } from './setupPrerequisites.js';
+import { pauseSelectedSetupHelpers, retryPendingSetupOperationReleases, targetsForSetupHelper, withSelectedSetupTargets } from './providerSelection.js';
+import { DesktopProviderManager } from './providerManager.js';
 import { buildDesktopCliInventoryFromRuntime, probeContradictsCachedBootstrapState, } from './cliInventoryProbe.js';
 import { createDesktopTrayController, } from './tray.js';
 import { buildDesktopTrayMenuState as buildElectronTrayMenuState, buildDesktopTrayQuittingMenuState, } from './trayMenu.js';
@@ -27,7 +30,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';
@@ -73,6 +75,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;
@@ -133,8 +136,16 @@ 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.state?.status === 'error') {
+        runtimeCliInventoryScanPending = false;
+        latestCliInventoryError = createCliInventoryScanFailedError();
+        return false;
+    }
+    if (probe.selection?.state !== 'selected' || (probe.scan && !isRuntimeCliInventoryScanActive(probe))) {
         runtimeCliInventoryScanPending = false;
         clearCliInventoryError();
         return true;
@@ -753,58 +764,28 @@ function buildTrayControllerOptions() {
             if (shuttingDown || !updateManager) {
                 return;
             }
-            await runDesktopUpdateDialog(updateManager.getSnapshot());
+            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;
+                },
+            });
         },
     };
 }
-/**
- * Shows the update dialog for the current state and carries out whatever the
- * user confirmed, re-entering once when the state it described was "nothing
- * asked yet" and the answer needed a check first.
- */
-async function runDesktopUpdateDialog(snapshot, allowRecheck = true) {
-    if (!updateManager) {
-        return;
-    }
-    const dialogSpec = resolveDesktopUpdateDialog({
-        snapshot,
-        platform: process.platform,
-        locale: app.getLocale(),
-    });
-    // An idle host has nothing to report yet. Run the check first and answer
-    // with its result, so one click produces one dialog rather than a dialog
-    // saying "about to look" followed by silence.
-    if (dialogSpec.action === 'check' && allowRecheck) {
-        const checked = await refreshUpdateState('tray');
-        if (checked && !shuttingDown) {
-            await runDesktopUpdateDialog(checked, false);
-        }
-        return;
-    }
-    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,
-    });
-    if (choice.response !== 0 || dialogSpec.action === 'none' || shuttingDown) {
-        return;
-    }
-    if (dialogSpec.action === 'update') {
-        const downloaded = await updateManager.downloadUpdate();
-        if (downloaded.status !== 'downloaded' || shuttingDown) {
-            // The dialog is closed and the tray never held the answer, so a failed
-            // download has to be carried to the user rather than left to be found.
-            await announceDesktopUpdateResult('tray', downloaded);
-            return;
-        }
-    }
-    await updateManager.restartAndInstall();
-}
 async function syncTrayController() {
     if (shuttingDown) {
         trayController?.updateMenu(buildDesktopTrayQuittingMenuState(app.getLocale()));
@@ -856,11 +837,63 @@ 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).catch(() => null);
+    snapshot.helpers = snapshot.helpers.filter((helper) => {
+        if (isDesktopPrerequisiteHelper(helper.id))
+            return true;
+        if (!probe?.selection)
+            return false;
+        try {
+            return targetsForSetupHelper(helper.id, probe.selection).length > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    snapshot.prerequisiteChecks = desktopPrerequisites.read();
+    if (snapshot.resumeAction && !snapshot.helpers.some((helper) => helper.id === snapshot.resumeAction.helperId)) {
+        snapshot.resumeAction = null;
+    }
+    return snapshot;
+}
+let providerManager = null;
+const desktopPrerequisites = new DesktopPrerequisiteChecks(process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux');
+let holdProviderOnboarding = false;
+function getProviderManager() {
+    if (!hostConfig)
+        throw new Error('Desktop host is not initialized.');
+    providerManager ??= new DesktopProviderManager({
+        platform: process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux',
+        prerequisites: () => desktopPrerequisites.read(),
+        request: async (path, init = {}) => {
+            const response = await fetchWithTimeout(`${hostConfig.runtimeBaseUrl}${path}`, init, RUNTIME_SETUP_STATE_TIMEOUT_MS);
+            if (!response.ok) {
+                const result = await response.json().catch(() => null);
+                throw new Error(result?.error || `Runtime provider request failed (${response.status}).`);
+            }
+            return response.json();
+        },
+        helpers: async () => (await buildDesktopSetupSnapshot({ config: hostConfig,
+            packaging: resolveCurrentPackagingPlan(hostConfig), state: setupState ?? createEmptyDesktopSetupState() })).helpers,
+        helper: async (helperId, mode, dryRun, expectedRevision) => {
+            const snapshot = await runSetupAction({ helperId, mode, dryRun }, { refreshInventory: false, expectedRevision });
+            if (!snapshot.state.lastAction)
+                throw new Error('Installer did not return a result.');
+            return snapshot.state.lastAction;
+        },
+        changed: async (runtime) => {
+            rememberRuntimeCliInventoryProbe(runtime);
+            latestProviderDiagnosticsPayload = null;
+            const snapshot = await refreshBootstrapSnapshot();
+            publishSnapshot(snapshot);
+        },
+    });
+    return providerManager;
 }
 async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -890,86 +923,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;
-    // A forced rescan is a user pressing Detect, and it has to reach the runtime
-    // even when the runtime says a scan is already running. `scanning` is
-    // persisted state: a runtime killed mid-scan -- which the packaged update
-    // handoff does deliberately when it drains the sidecars -- leaves it set for
-    // every launch that follows. Backing off on the strength of that flag turned
-    // Detect into a button that could never do anything again.
-    const shouldReadSetupStateFirst = !options.forceRescan;
-    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);
     }
-    // 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".
+    catch {
+        return null;
+    }
+    // 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, expectedRevision: probe.selection.revision }),
+        }, 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.');
@@ -992,6 +978,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,
     });
@@ -1016,7 +1004,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
@@ -1071,6 +1059,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,
     });
@@ -1082,28 +1072,32 @@ 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 prerequisites = desktopPrerequisites.read();
+        if (prerequisites.some((entry) => entry.helperId === action.helperId && entry.result))
+            continue;
+        if (action.helperId.endsWith('-npm-prefix-helper') && !prerequisites.some((entry) => entry.helperId.endsWith('-node-host-installer') && entry.result?.status === 'ready'))
+            continue;
+        const key = `${isDesktopPrerequisiteHelper(action.helperId) ? 'desktop' : selection?.revision}:${action.helperId}`;
+        if (auditedSetupHelpers.has(key))
+            continue;
+        auditedSetupHelpers.add(key);
+        try {
+            await runSetupAction({ helperId: action.helperId, mode: 'check' }, {
+                publishMode: 'bootstrap-only', refreshBootstrap: false,
+            });
+        }
+        catch (error) {
+            // Each failed prerequisite remains retryable in its card; do not let one
+            // missing host tool prevent the other environment checks from finishing.
+            process.stderr.write(`Desktop setup check failed (${action.helperId}): ${String(error)}\n`);
+        }
     }
-    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) {
@@ -1134,7 +1128,7 @@ async function pollRuntimeCliInventory(options) {
     if (!hostConfig)
         return;
     const probe = await fetchRuntimeCliInventoryProbe(hostConfig.runtimeBaseUrl, {
-        triggerScanIfMissing: !runtimeCliInventoryScanPending,
+        triggerScanIfMissing: false,
         scanTimeoutMs: options.setupCompleted
             ? RUNTIME_SETUP_SCAN_TIMEOUT_MS
             : RUNTIME_BOOTSTRAP_SETUP_SCAN_TIMEOUT_MS,
@@ -1199,7 +1193,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,
         });
@@ -1228,22 +1222,12 @@ 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.
+    // Always check Desktop prerequisites; provider/local-model probes remain scoped.
     scheduleBackgroundSetupAudit(snapshot, persistedSetup);
-    // CLI inventory is the only source the onboarding cards can read, so it has
-    // to be probed before setup as well — otherwise a machine with every CLI
-    // already installed shows a grid of "not detected yet" until the user clicks
-    // Detect. This is background work on its own pre-setup timeout budget
-    // (RUNTIME_BOOTSTRAP_SETUP_SCAN_TIMEOUT_MS) and, outside the legacy
-    // cli_inventory_gate policy, is display-only: buildDesktopBootstrapSnapshot
-    // gates every phase decision that reads cliInventory on that mode, so a scan
-    // landing here can never move the phase or navigate the window away from
-    // onboarding.
+    // Inventory observes the saved selection; missing/invalid/empty selections
+    // never launch a provider scan. Availability does not gate product onboarding.
     void retryCliInventoryScanInBackground({
-        forceRescan: setupCompleted,
+        forceRescan: false,
         setupCompleted,
     }).catch((error) => {
         process.stderr.write(`Background CLI inventory rescan failed: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -1257,6 +1241,8 @@ function scheduleBackgroundBootstrapWork(snapshot, persistedSetup) {
     }
 }
 async function maybeOpenApp(snapshot) {
+    if (holdProviderOnboarding && snapshot.phase !== 'failed')
+        return;
     if (!mainWindow || !hostConfig) {
         return;
     }
@@ -1378,7 +1364,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 () => {
@@ -1409,77 +1405,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.');
@@ -1487,7 +1412,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;
@@ -1523,6 +1450,7 @@ async function bootstrapDesktopHost(restartServices = false) {
         const snapshot = publishSnapshot(buildSnapshot());
         return maybeOpenApp(snapshot).then(() => snapshot);
     }).finally(() => {
+        helperPause?.resume();
         bootstrapPromise = null;
     });
     return bootstrapPromise;
@@ -1552,18 +1480,18 @@ async function runHostAction(actionId) {
         return latestSnapshot ?? buildSnapshot(null);
     }
     if (actionId === 'open_setup') {
-        const snapshot = latestSnapshot ?? await refreshBootstrapSnapshot();
-        if (isCliMissingBootstrapSnapshot(snapshot)) {
+        const snapshot = await refreshBootstrapSnapshot();
+        if (!latestCliInventoryProbe?.selection || ['missing', 'invalid'].includes(latestCliInventoryProbe.selection.state))
             return snapshot;
-        }
+        holdProviderOnboarding = false;
         await showMainWindow(`${hostConfig.appBaseUrl}/setup`);
         return snapshot;
     }
     if (actionId === 'open_chat') {
-        const snapshot = latestSnapshot ?? await refreshBootstrapSnapshot();
-        if (isCliMissingBootstrapSnapshot(snapshot)) {
+        const snapshot = await refreshBootstrapSnapshot();
+        if (!latestCliInventoryProbe?.selection || ['missing', 'invalid'].includes(latestCliInventoryProbe.selection.state))
             return snapshot;
-        }
+        holdProviderOnboarding = false;
         await showMainWindow(`${hostConfig.appBaseUrl}${snapshot.app.entryPath}`);
         return snapshot;
     }
@@ -1578,11 +1506,11 @@ 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 desktopPrerequisites.run(action.helperId, () => withSelectedSetupTargets({
+        baseUrl: hostConfig.runtimeBaseUrl, helperId: action.helperId,
+        expectedRevision: options.expectedRevision,
+        run: () => runDesktopSetupHelper({ config: hostConfig, packaging, action }),
+    }));
     packagingState = packaging;
     setupState = {
         lastAction: result,
@@ -1620,9 +1548,8 @@ 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');
-    if (shouldRefreshCliInventory) {
+        && shouldRefreshCliInventoryAfterSetupAction(action.helperId);
+    if (shouldRefreshCliInventory && options.refreshInventory !== false) {
         const refreshedProbe = await fetchRuntimeCliInventoryProbe(hostConfig.runtimeBaseUrl, {
             forceRescan: true,
         });
@@ -1644,7 +1571,8 @@ async function runSetupAction(action, options = {}) {
             publishSnapshot(snapshot);
         }
     }
-    return await getSetupSnapshot();
+    const snapshot = await getSetupSnapshot();
+    return { ...snapshot, state: { ...snapshot.state, lastAction: result } };
 }
 function shouldRefreshCliInventoryAfterSetupAction(helperId) {
     return helperId.endsWith('-native-installer')
@@ -1750,6 +1678,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)
@@ -1773,8 +1704,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;
@@ -1819,11 +1752,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);
     }
@@ -1939,7 +1869,26 @@ async function main() {
         }
         return await runHostAction(actionId);
     });
-    ipcMain.handle('cats-host:run-setup-helper', async (_event, payload) => {
+    ipcMain.handle('cats-host:provider-setup-read', async (event, context) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Provider setup is only available to the main Cats window.');
+        if (context !== 'onboarding' && context !== 'settings')
+            throw new Error('Invalid provider setup context.');
+        if (context === 'onboarding')
+            holdProviderOnboarding = true;
+        return await getProviderManager().read();
+    });
+    ipcMain.handle('cats-host:provider-setup-apply', async (event, payload) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Provider setup is only available to the main Cats window.');
+        await retryPendingSetupOperationReleases();
+        return await getProviderManager().apply(payload);
+    });
+    ipcMain.handle('cats-host:provider-setup-run', async (event, payload) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Provider setup is only available to the main Cats window.');
+        await retryPendingSetupOperationReleases();
+        return await getProviderManager().run(payload);
+    });
+    ipcMain.handle('cats-host:run-setup-helper', async (event, payload) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Setup helpers are only available to the main Cats window.');
         if (typeof payload !== 'object'
             || payload === null
             || typeof payload.helperId !== 'string'
@@ -2135,7 +2084,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) => {