fraim-hub 2.0.329 → 2.0.333

package/dist/src/ai-hub/background-command.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killBackgroundProcessTree = killBackgroundProcessTree;
+exports.runBackgroundCommand = runBackgroundCommand;
+const child_process_1 = require("child_process");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const node_path_1 = __importDefault(require("node:path"));
+const hub_main_diagnostics_1 = require("./hub-main-diagnostics");
+function killBackgroundProcessTree(pid, signal = 'SIGTERM', callback = () => undefined) {
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) {
+        callback(new Error('Refusing invalid or current process termination'));
+        return;
+    }
+    if (process.platform === 'win32') {
+        (0, child_process_1.execFile)('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, callback);
+    }
+    else
+        (0, tree_kill_1.default)(pid, signal, callback);
+}
+/** Captured, bounded infrastructure work. Completion follows child close, including timeout cleanup. */
+function runBackgroundCommand(command, args, options = {}) {
+    const started = performance.now();
+    // Log only an allowlisted executable category, never paths, arguments or output.
+    const executable = node_path_1.default.basename(command).toLowerCase().replace(/\.(exe|cmd|bat)$/, '');
+    const category = ['node', 'electron', 'npm', 'cmd', 'powershell', 'pwsh', 'reg', 'certutil', 'security'].includes(executable)
+        ? executable : 'other';
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(command, args, {
+            env: options.env ?? process.env, windowsHide: true,
+            windowsVerbatimArguments: options.windowsVerbatimArguments,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let error;
+        let outcome;
+        let termination;
+        const terminate = () => {
+            if (termination || !child.pid || child.exitCode !== null)
+                return;
+            const pid = child.pid;
+            termination = new Promise((done) => {
+                const ended = (failure) => {
+                    if (failure && child.exitCode === null) {
+                        error = failure;
+                        child.kill('SIGKILL');
+                    }
+                    done();
+                };
+                killBackgroundProcessTree(pid, 'SIGKILL', ended);
+            });
+        };
+        const timer = setTimeout(() => {
+            outcome = 'timeout';
+            error = new Error(`Background command exceeded ${options.timeoutMs ?? 15000}ms deadline`);
+            terminate();
+        }, options.timeoutMs ?? 15000);
+        const capture = (chunk, stream) => {
+            if (stream === 'stdout')
+                stdout += chunk.toString();
+            else
+                stderr += chunk.toString();
+            if (stdout.length + stderr.length > 1024 * 1024) {
+                outcome = 'output-limit';
+                stdout = stdout.slice(0, 512 * 1024);
+                stderr = stderr.slice(0, 512 * 1024);
+                error = new Error('Background command exceeded output limit');
+                terminate();
+            }
+        };
+        child.stdout.on('data', chunk => capture(chunk, 'stdout'));
+        child.stderr.on('data', chunk => capture(chunk, 'stderr'));
+        child.on('error', failure => { error = failure; outcome = 'spawn-error'; });
+        child.on('close', async (status, signal) => {
+            clearTimeout(timer);
+            await termination;
+            (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.background_command', {
+                category, outcome: outcome ?? (status === 0 ? 'success' : signal ? 'terminated' : 'nonzero-exit'),
+                exitCode: status, signal, durationMs: performance.now() - started,
+            });
+            resolve({ status: error ? null : status, stdout, stderr, error });
+        });
+    });
+}

package/dist/src/ai-hub/cert-store.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._internal = void 0;
+exports.isCertTrustedAsync = isCertTrustedAsync;
+exports.trustCertAsync = trustCertAsync;
 exports.certPaths = certPaths;
 exports.loadOrCreateCert = loadOrCreateCert;
 exports.trustCert = trustCert;
@@ -15,6 +17,29 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const crypto_1 = __importDefault(require("crypto"));
 const child_process_1 = require("child_process");
+const background_command_1 = require("./background-command");
+async function isCertTrustedAsync(certPath) {
+    if (!fs_1.default.existsSync(certPath))
+        return false;
+    const fingerprint = computeCertFingerprint(fs_1.default.readFileSync(certPath, 'utf8'));
+    const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+    if (process.platform !== 'win32' && process.platform !== 'darwin')
+        return false;
+    const result = process.platform === 'win32'
+        ? await exports._internal.runBackgroundCommand('certutil', ['-store', '-user', 'Root'])
+        : await exports._internal.runBackgroundCommand('security', ['find-certificate', '-a', '-c', 'localhost', '-Z', keychain]);
+    return result.status === 0 && result.stdout.toLowerCase().replace(/:/g, '').includes(fingerprint);
+}
+async function trustCertAsync(certPath) {
+    if (process.platform !== 'win32' && process.platform !== 'darwin')
+        return;
+    const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+    const result = process.platform === 'win32'
+        ? await exports._internal.runBackgroundCommand('certutil', ['-addstore', '-user', 'Root', certPath], { timeoutMs: 120000 })
+        : await exports._internal.runBackgroundCommand('security', ['add-trusted-cert', '-r', 'trustRoot', '-k', keychain, certPath], { timeoutMs: 120000 });
+    if (result.status !== 0)
+        throw result.error ?? new Error(result.stderr || 'Certificate trust failed');
+}
 function certDir() {
     const base = process.env.APPDATA ||
         (process.platform === 'darwin'
@@ -58,7 +83,7 @@ async function loadOrCreateCert() {
  * Swapping the export on Node's built-in `child_process` module itself is not reliable for
  * this (confirmed empirically while fixing this issue) - this repo-owned seam is.
  */
-exports._internal = { spawnSync: child_process_1.spawnSync };
+exports._internal = { spawnSync: child_process_1.spawnSync, runBackgroundCommand: background_command_1.runBackgroundCommand };
 /**
  * Installs the cert as a trusted root CA in the user's OS certificate store.
  * ONLY call this for explicit Word-Online support — it prompts a Windows security
@@ -69,7 +94,7 @@ exports._internal = { spawnSync: child_process_1.spawnSync };
  */
 function trustCert(certPath) {
     if (process.platform === 'win32') {
-        const result = exports._internal.spawnSync('certutil', ['-addstore', '-user', 'Root', certPath], { encoding: 'utf8' });
+        const result = exports._internal.spawnSync('certutil', ['-addstore', '-user', 'Root', certPath], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
         if (result.status !== 0) {
             console.warn('[fraim] could not trust localhost certificate:', result.stderr || result.stdout);
         }
@@ -83,7 +108,7 @@ function trustCert(certPath) {
 /** Removes a specific cert from the trust store, by fingerprint. Test-only helper. */
 function untrustCert(fingerprint) {
     if (process.platform === 'win32') {
-        exports._internal.spawnSync('certutil', ['-delstore', '-user', 'Root', fingerprint], { encoding: 'utf8' });
+        exports._internal.spawnSync('certutil', ['-delstore', '-user', 'Root', fingerprint], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
         return;
     }
     if (process.platform === 'darwin') {
@@ -116,14 +141,14 @@ function isCertTrusted(certPath) {
         return false;
     const fingerprint = computeCertFingerprint(fs_1.default.readFileSync(certPath, 'utf8'));
     if (process.platform === 'win32') {
-        const result = (0, child_process_1.spawnSync)('certutil', ['-store', '-user', 'Root'], { encoding: 'utf8' });
+        const result = (0, child_process_1.spawnSync)('certutil', ['-store', '-user', 'Root'], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
         if (result.status !== 0)
             return false;
         return result.stdout.toLowerCase().includes(fingerprint);
     }
     if (process.platform === 'darwin') {
         const keychain = path_1.default.join(os_1.default.homedir(), 'Library', 'Keychains', 'login.keychain-db');
-        const result = (0, child_process_1.spawnSync)('security', ['find-certificate', '-a', '-c', 'localhost', '-Z', keychain], { encoding: 'utf8' });
+        const result = (0, child_process_1.spawnSync)('security', ['find-certificate', '-a', '-c', 'localhost', '-Z', keychain], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
         if (result.status !== 0)
             return false;
         return result.stdout.toLowerCase().replace(/:/g, '').includes(fingerprint);

package/dist/src/ai-hub/cli.js

@@ -90,6 +90,7 @@ async function openDesktopWindow(projectPath, preferredPort, runtimeId) {
         args.push('--hub-runtime-id', runtimeId);
     }
     const child = (0, child_process_1.spawn)(electron.binaryPath, args, {
+        windowsHide: true,
         detached: true,
         stdio: 'ignore',
     });
@@ -97,7 +98,7 @@ async function openDesktopWindow(projectPath, preferredPort, runtimeId) {
 }
 function openBrowser(url) {
     if (process.platform === 'win32') {
-        const child = (0, child_process_1.spawn)('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' });
+        const child = (0, child_process_1.spawn)('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true });
         child.unref();
         return;
     }

package/dist/src/ai-hub/configured-agent-command.js

@@ -5,10 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseConfiguredCommand = parseConfiguredCommand;
 exports.describeConfiguredCommandInvocationProblem = describeConfiguredCommandInvocationProblem;
+exports.__setCommandResolutionProbeForTests = __setCommandResolutionProbeForTests;
+exports.probeCommandResolvesNonInteractively = probeCommandResolvesNonInteractively;
 exports.commandContainsLiteralSecret = commandContainsLiteralSecret;
 exports.decorateHostPlanWithConfiguredAgent = decorateHostPlanWithConfiguredAgent;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const BASH_ENV_PREFIX = /^([A-Za-z_][A-Za-z0-9_]*)=(?:\$\([^)]*\)|"[^"]*"|'[^']*'|\S*)\s+/;
 // The value may be a parenthesized PowerShell expression followed by a
@@ -51,6 +54,55 @@ function describeConfiguredCommandInvocationProblem(parsed, baseHostId, agentLab
     }
     return null;
 }
+let commandResolutionProbeOverride = null;
+function __setCommandResolutionProbeForTests(stub) {
+    commandResolutionProbeOverride = stub;
+}
+const PROBE_CACHE_TTL_MS = 60_000;
+const NON_INTERACTIVE_PROBE_TIMEOUT_MS = 3_000;
+const probeCache = new Map();
+// Probes whether commandName is resolvable in the non-interactive shell context
+// that Hub actually uses to launch configured agents (bash --noprofile --norc,
+// or powershell -NoProfile). Commands defined only as profile functions or
+// aliases are unavailable in that context and would cause silent launch failure.
+// Results are cached for PROBE_CACHE_TTL_MS to avoid repeated spawnSync calls
+// on frequent availability checks.
+function probeCommandResolvesNonInteractively(runner, commandName) {
+    if (commandResolutionProbeOverride !== null)
+        return commandResolutionProbeOverride(runner, commandName);
+    const key = `${runner}\x00${commandName}`;
+    const cached = probeCache.get(key);
+    if (cached && Date.now() - cached.at < PROBE_CACHE_TTL_MS)
+        return cached.result;
+    let result;
+    if (runner === 'powershell') {
+        if (process.platform !== 'win32') {
+            result = null;
+        }
+        else {
+            const r = (0, child_process_1.spawnSync)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `Get-Command -Name ${JSON.stringify(commandName)} -ErrorAction Stop`], { encoding: 'utf8', timeout: NON_INTERACTIVE_PROBE_TIMEOUT_MS, windowsHide: true });
+            result = r.error || r.status !== 0
+                ? `Command '${commandName}' not found in non-interactive PowerShell (powershell -NoProfile). ` +
+                    `This command may be a PowerShell profile function or alias that is unavailable without a profile. ` +
+                    `Create a .cmd wrapper on PATH that calls the real executable directly.`
+                : null;
+        }
+    }
+    else {
+        const r = (0, child_process_1.spawnSync)('bash', ['--noprofile', '--norc', '-c', `command -v ${commandName}`], {
+            encoding: 'utf8',
+            timeout: NON_INTERACTIVE_PROBE_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        result = r.error || r.status !== 0
+            ? `Command '${commandName}' not found in non-interactive bash (bash --noprofile --norc). ` +
+                `This command may be defined only in a shell profile. ` +
+                `Add the command to a PATH location accessible without sourcing any profile.`
+            : null;
+    }
+    probeCache.set(key, { result, at: Date.now() });
+    return result;
+}
 function tokenizeShellLike(text) {
     const tokens = [];
     const re = /"([^"]*)"|'([^']*)'|(\S+)/g;

package/dist/src/ai-hub/configured-agents.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.describeConfiguredCommandInvocationProblem = exports.decorateHostPlanWithConfiguredAgent = exports.commandContainsLiteralSecret = exports.parseConfiguredCommand = exports.AiHubConfiguredAgentStore = void 0;
+exports.__setCommandResolutionProbeForTests = exports.probeCommandResolvesNonInteractively = exports.describeConfiguredCommandInvocationProblem = exports.decorateHostPlanWithConfiguredAgent = exports.commandContainsLiteralSecret = exports.parseConfiguredCommand = exports.AiHubConfiguredAgentStore = void 0;
 exports.synthesizeDefaultConfiguredAgents = synthesizeDefaultConfiguredAgents;
 exports.checkConfiguredAgentAvailability = checkConfiguredAgentAvailability;
 exports.checkConfiguredAgentReadiness = checkConfiguredAgentReadiness;
@@ -182,8 +182,14 @@ function checkConfiguredAgentAvailability(agent, hosts, env = process.env) {
             try {
                 const parsed = (0, configured_agent_command_1.parseConfiguredCommand)(agent.command.runner, agent.command.command);
                 const problem = (0, configured_agent_command_1.describeConfiguredCommandInvocationProblem)(parsed, agent.baseHostId, agent.label);
-                if (problem)
+                if (problem) {
                     reasons.push(problem);
+                }
+                else if (parsed.invocationHead) {
+                    const probeError = (0, configured_agent_command_1.probeCommandResolvesNonInteractively)(agent.command.runner, parsed.invocationHead);
+                    if (probeError)
+                        reasons.push(probeError);
+                }
             }
             catch (error) {
                 reasons.push(error instanceof Error ? error.message : 'Configured agent command could not be parsed.');
@@ -304,6 +310,7 @@ function runSetupScript(setupScript) {
                 ...args,
             ]];
     const result = (0, child_process_1.spawnSync)(invocation[0], invocation[1], {
+        windowsHide: true,
         encoding: 'utf8',
         timeout: setupScript.timeoutMs || 30_000,
         env: captureEnv,
@@ -348,3 +355,5 @@ Object.defineProperty(exports, "parseConfiguredCommand", { enumerable: true, get
 Object.defineProperty(exports, "commandContainsLiteralSecret", { enumerable: true, get: function () { return configured_agent_command_2.commandContainsLiteralSecret; } });
 Object.defineProperty(exports, "decorateHostPlanWithConfiguredAgent", { enumerable: true, get: function () { return configured_agent_command_2.decorateHostPlanWithConfiguredAgent; } });
 Object.defineProperty(exports, "describeConfiguredCommandInvocationProblem", { enumerable: true, get: function () { return configured_agent_command_2.describeConfiguredCommandInvocationProblem; } });
+Object.defineProperty(exports, "probeCommandResolvesNonInteractively", { enumerable: true, get: function () { return configured_agent_command_2.probeCommandResolvesNonInteractively; } });
+Object.defineProperty(exports, "__setCommandResolutionProbeForTests", { enumerable: true, get: function () { return configured_agent_command_2.__setCommandResolutionProbeForTests; } });

package/dist/src/ai-hub/desktop-admission.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.admitDesktopInstance = admitDesktopInstance;
+exports.attachDesktopFocusHandler = attachDesktopFocusHandler;
+const electron_1 = require("electron");
+const fs_1 = __importDefault(require("fs"));
+// A materialized payload has its own module cache. The process owns admission,
+// so both copies share it across the launcher-to-application handoff.
+const admissionKey = Symbol.for('fraim.desktop.admission');
+const processState = globalThis;
+function admitDesktopInstance() {
+    if (processState[admissionKey])
+        return processState[admissionKey].admitted;
+    const runtimeArg = process.argv.indexOf('--hub-runtime-id');
+    const runtimeId = (runtimeArg >= 0 ? process.argv[runtimeArg + 1] : undefined)
+        || process.env.FRAIM_HUB_RUNTIME_ID || 'hub';
+    electron_1.app.setName(process.env.FRAIM_HUB_DISPLAY_NAME || (runtimeId === 'hub2' ? 'FRAIM Hub 2' : 'FRAIM Hub'));
+    electron_1.app.setAppUserModelId('ai.fraim.hub');
+    const userDataDir = process.env.FRAIM_AI_HUB_USER_DATA_DIR;
+    if (userDataDir) {
+        fs_1.default.mkdirSync(userDataDir, { recursive: true });
+        electron_1.app.setPath('userData', userDataDir);
+    }
+    const state = {
+        admitted: process.env.FRAIM_AI_HUB_FAKE_HOST === '1' || electron_1.app.requestSingleInstanceLock(),
+        pendingFocus: false,
+    };
+    processState[admissionKey] = state;
+    if (!state.admitted) {
+        electron_1.app.quit();
+        return false;
+    }
+    electron_1.app.on('second-instance', () => {
+        if (state.focus)
+            state.focus();
+        else
+            state.pendingFocus = true;
+    });
+    return true;
+}
+function attachDesktopFocusHandler(focus) {
+    const state = processState[admissionKey];
+    if (!state?.admitted)
+        return;
+    state.focus = focus;
+    if (state.pendingFocus) {
+        state.pendingFocus = false;
+        focus();
+    }
+}

package/dist/src/ai-hub/desktop-auto-updater.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMandatoryDesktopUpdateCheck = runMandatoryDesktopUpdateCheck;
+function beforeDeadline(operation, timeoutMs, onTimeout) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Desktop update exceeded ${timeoutMs}ms deadline`));
+            onTimeout?.();
+        }, timeoutMs);
+        operation.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
 let updateCheckInFlight = null;
 function runMandatoryDesktopUpdateCheck(options) {
     if (!options.isPackaged)
@@ -17,7 +26,7 @@ async function runMandatoryDesktopUpdateCheckOnce(options) {
     const { updater, prompt, currentVersion, logger = console } = options;
     updater.autoDownload = false;
     updater.autoInstallOnAppQuit = false;
-    const checkResult = await checkForDesktopUpdate(updater, prompt, currentVersion, logger);
+    const checkResult = await checkForDesktopUpdate(updater, prompt, currentVersion, logger, options.checkTimeoutMs ?? 4000);
     if (checkResult.action === 'check-failed')
         return checkResult;
     if (!checkResult.update?.isUpdateAvailable) {
@@ -25,14 +34,11 @@ async function runMandatoryDesktopUpdateCheckOnce(options) {
         return { action: 'current', availableVersion: checkResult.update?.updateInfo?.version };
     }
     const availableVersion = checkResult.update.updateInfo?.version;
+    const cancellationToken = checkResult.update.cancellationToken
+        ?? new (require('builder-util-runtime').CancellationToken)();
     try {
         logger.info(`[fraim] desktop update ${availableVersion ?? 'unknown'} available; downloading`);
-        if (checkResult.update.downloadPromise) {
-            await checkResult.update.downloadPromise;
-        }
-        else {
-            await updater.downloadUpdate();
-        }
+        await beforeDeadline(checkResult.update.downloadPromise ?? updater.downloadUpdate(cancellationToken), options.downloadTimeoutMs ?? 120000, () => cancellationToken.cancel());
     }
     catch (error) {
         const message = errorMessage(error);
@@ -58,10 +64,10 @@ async function runMandatoryDesktopUpdateCheckOnce(options) {
         return { action: 'install-failed', availableVersion, error: message };
     }
 }
-async function checkForDesktopUpdate(updater, prompt, currentVersion, logger) {
+async function checkForDesktopUpdate(updater, prompt, currentVersion, logger, timeoutMs) {
     try {
         logger.info(`[fraim] checking for desktop update from ${currentVersion}`);
-        return { action: 'checked', update: await updater.checkForUpdates() };
+        return { action: 'checked', update: await beforeDeadline(updater.checkForUpdates(), timeoutMs) };
     }
     catch (error) {
         const message = errorMessage(error);

package/dist/src/ai-hub/desktop-installer-setup.js

@@ -3,18 +3,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDesktopRuntimeComplete = isDesktopRuntimeComplete;
 exports.readInstallerSetupApiKey = readInstallerSetupApiKey;
 exports.repairInstallerIdeMcpEntries = repairInstallerIdeMcpEntries;
+exports.runDesktopRuntimeSetup = runDesktopRuntimeSetup;
 exports.runDesktopInstallerSetup = runDesktopInstallerSetup;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const ide_detector_1 = require("../cli/setup/ide-detector");
 const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
-const win32_cmd_spawn_1 = require("../cli/utils/win32-cmd-spawn");
+const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const hub_app_materializer_1 = require("./hub-app-materializer");
+function isDesktopRuntimeComplete() {
+    if (![(0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)(), (0, fraim_mcp_latest_launcher_1.getFraimMcpLatestLauncherPath)()]
+        .every(file => fs_1.default.existsSync(file)))
+        return false;
+    const systemNpm = (0, managed_node_runtime_1.findExecutableOnPath)((0, managed_node_runtime_1.npmExecutableName)());
+    return (systemNpm !== null && (0, managed_node_runtime_1.hasWorkingNodeAndNpm)(path_1.default.dirname(systemNpm)))
+        || (0, managed_node_runtime_1.hasWorkingNodeAndNpm)((0, managed_agent_paths_1.getPortableNodeBinPath)());
+}
 function readInstallerSetupApiKey(configPath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'config.json')) {
     if (!fs_1.default.existsSync(configPath))
         return null;
@@ -58,22 +68,22 @@ async function repairInstallerIdeMcpEntries(options = {}) {
             process.env.FRAIM_NON_INTERACTIVE = previousNonInteractive;
     }
 }
-function warmInstallerCliCache() {
+async function warmInstallerCliCache() {
     const cliShim = (0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)();
-    const options = { env: process.env, encoding: 'utf8', stdio: 'inherit' };
-    const result = process.platform === 'win32'
-        ? (0, win32_cmd_spawn_1.spawnViaCmdExe)(cliShim, ['--version'], options)
-        : (0, child_process_1.spawnSync)(cliShim, ['--version'], options);
+    const result = await (0, hub_app_materializer_1.runNpmInstall)(cliShim, ['--version']);
     if (result.status !== 0) {
         throw new Error(`FRAIM CLI bootstrap exited with code ${result.status ?? 'unknown'}.`);
     }
 }
-async function runDesktopInstallerSetup(logger = console) {
+async function runDesktopRuntimeSetup(logger = console) {
     await (0, managed_node_runtime_1.ensureManagedNpm)({
         onProgress: (message) => logger.log(`[fraim-installer-setup] ${message}`),
     });
     (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
-    warmInstallerCliCache();
+    await warmInstallerCliCache();
+}
+async function runDesktopInstallerSetup(logger = console) {
+    await runDesktopRuntimeSetup(logger);
     await repairInstallerIdeMcpEntries({ logger });
     logger.log('[fraim-installer-setup] stable CLI and MCP launchers are ready');
 }

package/dist/src/ai-hub/desktop-launcher.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const electron_1 = require("electron");
 const path_1 = __importDefault(require("path"));
 const hub_app_materializer_1 = require("./hub-app-materializer");
+const desktop_admission_1 = require("./desktop-admission");
+const hub_main_diagnostics_1 = require("./hub-main-diagnostics");
 // Issue #1415: this is the packaged Electron `main` entry (see packages/fraim-hub/package.json
 // `"main"`). It is deliberately thin and changes rarely: its only job is to resolve which version
 // of the actual Hub application (the code in desktop-main.ts) to run — the latest published to
@@ -20,10 +22,16 @@ async function bootstrapFrom(entryPath) {
     await entry.bootstrap();
 }
 async function launch() {
-    if (process.argv.includes('--fraim-installer-setup')) {
+    if (process.argv.includes('--fraim-installer-setup') || process.argv.includes('--fraim-runtime-repair')) {
         await bootstrapFrom(BUNDLED_ENTRY_PATH);
         return;
     }
+    const admissionStarted = performance.now();
+    if (!(0, desktop_admission_1.admitDesktopInstance)())
+        return;
+    (0, hub_main_diagnostics_1.installHubMainConsoleTee)();
+    (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.startup_stage', { stage: 'admission', durationMs: performance.now() - admissionStarted });
+    const resolutionStarted = performance.now();
     // Issue #1415: deterministic escape hatch for integration testing — skips the real npm
     // resolution (and its dependence on whatever happens to be published at test time) so a test can
     // prove the Electron main-process boot chain itself (resolveHubAppEntry -> require -> bootstrap
@@ -42,8 +50,16 @@ async function launch() {
             return { entryPath: BUNDLED_ENTRY_PATH, source: 'bundled', version: electron_1.app.getVersion() };
         });
     console.log(`[fraim-hub-launcher] running FRAIM Hub ${resolved.version} (${resolved.source})`);
+    (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.startup_stage', {
+        stage: 'payload-resolution', durationMs: performance.now() - resolutionStarted,
+        selectedVersion: resolved.version, source: resolved.source,
+        outcome: resolved.materializationError ? 'fallback' : 'success',
+    });
+    let entry;
     try {
-        await bootstrapFrom(resolved.entryPath);
+        entry = require(resolved.entryPath);
+        if (typeof entry.bootstrap !== 'function')
+            throw new Error('Hub payload has no bootstrap entry');
     }
     catch (error) {
         if (resolved.entryPath === BUNDLED_ENTRY_PATH)
@@ -52,8 +68,11 @@ async function launch() {
         // dependency introduces) must not strand the user on a broken launch — fall back to the
         // build that shipped with this installer, which is always known-good for this Electron binary.
         console.error(`[fraim-hub-launcher] materialized FRAIM Hub ${resolved.version} failed to load; falling back to the bundled build:`, error);
-        await bootstrapFrom(BUNDLED_ENTRY_PATH);
+        entry = require(BUNDLED_ENTRY_PATH);
     }
+    // Once bootstrap starts it can own servers/windows. Do not start a second
+    // application over those resources if initialization subsequently fails.
+    await entry.bootstrap();
 }
 if (process.versions.electron && process.type !== 'renderer') {
     launch().catch((error) => {