fraim-framework 2.0.152 → 2.0.154

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

@@ -16,6 +16,7 @@ const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 // Parse a single line of host stdout looking for a seekMentoring tool-use
 // signal. Returns null if the line does not contain one. Supports both
 // hosts FRAIM ships against today:
@@ -239,6 +240,7 @@ const availableByVersionProbe = (command) => {
     const invocation = resolveHostInvocation({ command, args: ['--version'] });
     const result = (0, child_process_1.spawnSync)(invocation.command, invocation.args, {
         encoding: 'utf8',
+        env: { ...process.env, PATH: (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH) },
     });
     return result.status === 0;
 };
@@ -496,14 +498,14 @@ class FakeHostRuntime {
         return this.employees;
     }
     startRun(hostId, _projectPath, message, handlers) {
-        return this.fakeProcess(hostId, `Started ${hostId}: ${message}`, handlers);
+        return this.fakeProcess(hostId, this.fakeEmployeeReply('start', message), handlers);
     }
     continueRun(hostId, _projectPath, sessionId, message, handlers) {
-        return this.fakeProcess(hostId, `Resumed ${hostId} session ${sessionId}: ${message}`, handlers);
+        return this.fakeProcess(hostId, this.fakeEmployeeReply('continue', message), handlers);
     }
     fakeProcess(_hostId, text, handlers) {
-        handlers.onEvent({ sessionId: (0, crypto_1.randomUUID)(), raw: 'fake-session-start' }, 'system');
-        handlers.onEvent({ message: text, raw: text }, 'stdout');
+        handlers.onEvent({ sessionId: (0, crypto_1.randomUUID)() }, 'system');
+        handlers.onEvent({ message: text }, 'stdout');
         setTimeout(() => handlers.onExit(0), 25);
         return {
             stdout: process.stdout,
@@ -537,6 +539,20 @@ class FakeHostRuntime {
             ref: () => undefined,
         };
     }
+    fakeEmployeeReply(kind, message) {
+        const parsed = parseFraimInvocation(message);
+        const label = parsed?.jobId
+            ? parsed.jobId.split('-').map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ')
+            : null;
+        if (kind === 'continue') {
+            return label
+                ? `Understood. I'm taking another pass with ${label}.`
+                : 'Understood. I am incorporating your coaching now.';
+        }
+        return label
+            ? `Understood. I'm starting ${label} now.`
+            : 'Understood. I am working on that now.';
+    }
 }
 exports.FakeHostRuntime = FakeHostRuntime;
 // Issue #347 — test-only host that lets a test inject seekMentoring

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

@@ -41,6 +41,7 @@ const catalog_1 = require("./catalog");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
 const preferences_1 = require("./preferences");
+const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 function loadPersonaCapabilityModule() {
     try {
         // Server deployments include the persona catalog. The npm client package
@@ -319,12 +320,18 @@ function hubAgentOption(hubId) {
     const frId = HUB_TO_FIRST_RUN_ID[hubId];
     return frId ? types_1.FIRST_RUN_AGENT_OPTIONS.find((o) => o.id === frId) : undefined;
 }
-function hubCommandVersion(command) {
+function hubCommandVersion(command, extraBinDirs) {
     const executable = process.platform === 'win32' ? 'cmd.exe' : command;
     const args = process.platform === 'win32'
         ? ['/d', '/s', '/c', `${command} --version`]
         : ['--version'];
-    const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000 });
+    const env = extraBinDirs && extraBinDirs.length > 0
+        ? {
+            ...process.env,
+            PATH: [...new Set([...extraBinDirs, ...(process.env.PATH || '').split(path_1.default.delimiter).filter(Boolean)])].join(path_1.default.delimiter),
+        }
+        : undefined;
+    const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000, ...(env ? { env } : {}) });
     if (result.status !== 0 || result.error)
         return null;
     const raw = (result.stdout || result.stderr || '').trim();
@@ -376,6 +383,13 @@ function hubOpenTerminal(command) {
     }
     (0, child_process_1.spawn)('bash', ['-c', command], { detached: true, stdio: 'ignore' }).unref();
 }
+function buildManagedLoginCommand(command) {
+    const managedPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
+    if (process.platform === 'win32') {
+        return `set "PATH=${managedPath}" && ${command}`;
+    }
+    return `export PATH="${managedPath}"; ${command}`;
+}
 function getUserHubDir() {
     return path_1.default.join(os_1.default.homedir(), '.fraim');
 }
@@ -400,9 +414,11 @@ class AiHubServer {
         this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
         if (options.dbService !== undefined) {
             this.dbService = options.dbService;
+            this.ownsDbService = false;
         }
         else {
             this.dbService = createDefaultDbService();
+            this.ownsDbService = this.dbService !== undefined;
         }
         this.app.use(express_1.default.json());
         this.app.use('/ai-hub', express_1.default.static(resolveAiHubPublicDir()));
@@ -431,18 +447,22 @@ class AiHubServer {
         });
     }
     async stop() {
-        if (!this.httpServer)
-            return;
-        await new Promise((resolve, reject) => {
-            this.httpServer.close((error) => {
-                if (error) {
-                    reject(error);
-                    return;
-                }
-                resolve();
+        if (this.httpServer) {
+            await new Promise((resolve, reject) => {
+                this.httpServer.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
             });
-        });
-        this.httpServer = undefined;
+            this.httpServer = undefined;
+        }
+        if (this.ownsDbService && this.dbService) {
+            await this.dbService.close();
+            this.dbService = undefined;
+        }
     }
     async bootstrapResponse(projectPath, apiKey) {
         const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
@@ -563,9 +583,13 @@ class AiHubServer {
             if (!option)
                 return res.status(400).json({ error: `Unknown agent: ${hubId}` });
             try {
-                const prefix = path_1.default.join(getUserHubDir(), 'node');
+                const prefix = (0, managed_agent_paths_1.getManagedNodeRoot)();
                 fs_1.default.mkdirSync(prefix, { recursive: true });
                 await hubRunProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+                const ver = hubCommandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
+                if (!ver) {
+                    throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH.`);
+                }
                 return res.json({
                     ok: true,
                     message: `${option.label} installed successfully.`,
@@ -587,7 +611,7 @@ class AiHubServer {
             if (!option)
                 return res.status(400).json({ error: `Unknown agent: ${hubId}` });
             try {
-                hubOpenTerminal(option.loginCommand);
+                hubOpenTerminal(buildManagedLoginCommand(option.loginCommand));
                 return res.json({
                     ok: true,
                     message: `A terminal window opened with the ${option.label} sign-in command. Complete sign-in there, then return here.`,
@@ -608,7 +632,7 @@ class AiHubServer {
             const option = hubAgentOption(hubId);
             if (!option)
                 return res.status(400).json({ error: `Unknown agent: ${hubId}` });
-            const ver = hubCommandVersion(option.launchCommand);
+            const ver = hubCommandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
             if (ver) {
                 return res.json({ ok: true, ready: true, message: `${option.label} is ready.` });
             }

package/dist/src/cli/commands/init-project.js

@@ -256,14 +256,16 @@ const runInitProject = async (options = {}) => {
     else {
         result.warnings.push('Sync was skipped for this run.');
     }
-    const codexAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'codex');
+    const codexAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'codex') ||
+        (0, ide_detector_1.detectInstalledIDEs)('cli-runnable').some((ide) => ide.configType === 'codex');
     if (codexAvailable) {
         const codexLocalResult = (0, codex_local_config_1.ensureCodexLocalConfig)(projectRoot);
         const status = codexLocalResult.created ? 'Created' : codexLocalResult.updated ? 'Updated' : 'Verified';
         console.log(chalk_1.default.green(`${status} project Codex config at ${codexLocalResult.path}`));
     }
     // Enable token telemetry for Claude Code (user-level, applies to all projects)
-    const claudeCodeAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'claude-code');
+    const claudeCodeAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'claude-code') ||
+        (0, ide_detector_1.detectInstalledIDEs)('cli-runnable').some((ide) => ide.configType === 'claude-code');
     if (claudeCodeAvailable) {
         (0, claude_code_telemetry_1.ensureClaudeCodeTelemetryEnv)();
     }

package/dist/src/cli/setup/ide-detector.js

@@ -62,11 +62,23 @@ const detectWindsurf = () => {
     return checkMultiplePaths(paths);
 };
 const detectGeminiCli = () => {
-    // Require the binary to be in PATH. The ~/.gemini directory alone is not
-    // sufficient — it exists when only Antigravity or other Gemini-adjacent
-    // tools are installed, which would produce a false positive.
     return availableByVersionProbe('gemini');
 };
+const detectGeminiSurface = () => {
+    const paths = [
+        '~/.gemini',
+        '~/AppData/Roaming/gemini',
+        '~/.config/gemini'
+    ];
+    return checkMultiplePaths(paths);
+};
+const detectCodexSurface = () => {
+    const paths = [
+        '~/.codex',
+        '~/.codex/config.toml'
+    ];
+    return checkMultiplePaths(paths);
+};
 exports.IDE_CONFIGS = [
     {
         name: 'Claude Code',
@@ -109,7 +121,7 @@ exports.IDE_CONFIGS = [
         configFormat: 'json',
         configType: 'gemini-cli',
         invocationProfile: 'gemini-command',
-        detectMethod: detectGeminiCli,
+        detectMethod: detectGeminiSurface,
         supportsConfigBootstrap: true,
         aliases: ['gemini', 'gemini-cli', 'gemini cli'],
         alternativePaths: [
@@ -165,7 +177,7 @@ exports.IDE_CONFIGS = [
         configFormat: 'toml',
         configType: 'codex',
         invocationProfile: 'codex-skill',
-        detectMethod: () => availableByVersionProbe('codex'),
+        detectMethod: detectCodexSurface,
         description: 'Codex AI development environment'
     },
     {
@@ -184,11 +196,9 @@ exports.IDE_CONFIGS = [
     }
 ];
 const findBestConfigPath = (ide) => {
-    // First try the default path
     if (fs_1.default.existsSync(expandPath(ide.configPath))) {
         return ide.configPath;
     }
-    // Then try alternative paths
     if (ide.alternativePaths) {
         for (const altPath of ide.alternativePaths) {
             if (fs_1.default.existsSync(expandPath(altPath))) {
@@ -196,26 +206,44 @@ const findBestConfigPath = (ide) => {
             }
         }
     }
-    // Return default path if nothing found (will be created)
     return ide.configPath;
 };
-let _cachedIDEs = null;
-let _cacheTimestamp = 0;
-let _cacheHomeDir = '';
+const _cachedIDEs = new Map();
+const _cacheTimestamps = new Map();
+const _cacheHomeDirs = new Map();
 const DETECT_CACHE_TTL_MS = 5000;
-const detectInstalledIDEs = () => {
+const isDetectedForMode = (ide, mode) => {
+    if (mode === 'cli-runnable') {
+        switch (ide.configType) {
+            case 'claude-code':
+                return availableByVersionProbe('claude');
+            case 'codex':
+                return availableByVersionProbe('codex');
+            case 'gemini-cli':
+                return detectGeminiCli();
+            default:
+                return false;
+        }
+    }
+    return ide.detectMethod();
+};
+const detectInstalledIDEs = (mode = 'config-surface') => {
     const now = Date.now();
     const currentHome = os_1.default.homedir();
-    if (_cachedIDEs !== null && _cacheHomeDir === currentHome && (now - _cacheTimestamp) < DETECT_CACHE_TTL_MS) {
-        return _cachedIDEs;
+    const cached = _cachedIDEs.get(mode);
+    const cacheTimestamp = _cacheTimestamps.get(mode) || 0;
+    const cacheHomeDir = _cacheHomeDirs.get(mode) || '';
+    if (cached !== undefined && cacheHomeDir === currentHome && (now - cacheTimestamp) < DETECT_CACHE_TTL_MS) {
+        return cached;
     }
-    _cachedIDEs = exports.IDE_CONFIGS.filter(ide => ide.detectMethod()).map(ide => ({
+    const detected = exports.IDE_CONFIGS.filter((ide) => isDetectedForMode(ide, mode)).map(ide => ({
         ...ide,
         configPath: findBestConfigPath(ide)
     }));
-    _cacheTimestamp = now;
-    _cacheHomeDir = currentHome;
-    return _cachedIDEs;
+    _cachedIDEs.set(mode, detected);
+    _cacheTimestamps.set(mode, now);
+    _cacheHomeDirs.set(mode, currentHome);
+    return detected;
 };
 exports.detectInstalledIDEs = detectInstalledIDEs;
 const getAllSupportedIDEs = () => {

package/dist/src/cli/utils/managed-agent-paths.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getManagedNodeRoot = getManagedNodeRoot;
+exports.getPortableNodeBinPath = getPortableNodeBinPath;
+exports.getManagedAgentBinDirs = getManagedAgentBinDirs;
+exports.buildPathWithManagedAgentBins = buildPathWithManagedAgentBins;
+exports.prependManagedAgentBinDirsToProcessPath = prependManagedAgentBinDirsToProcessPath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const script_sync_utils_1 = require("./script-sync-utils");
+function getManagedNodeRoot() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
+}
+function getPortableNodeBinPath() {
+    const nodeRoot = getManagedNodeRoot();
+    if (process.platform === 'win32') {
+        if (fs_1.default.existsSync(nodeRoot)) {
+            const extractedDir = fs_1.default.readdirSync(nodeRoot, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('node-v'))
+                .sort((a, b) => b.name.localeCompare(a.name))[0];
+            if (extractedDir) {
+                return path_1.default.join(nodeRoot, extractedDir.name);
+            }
+        }
+        return nodeRoot;
+    }
+    return path_1.default.join(nodeRoot, 'bin');
+}
+function getManagedAgentBinDirs() {
+    const nodeRoot = getManagedNodeRoot();
+    const portableNodeBin = getPortableNodeBinPath();
+    const candidates = process.platform === 'win32'
+        ? [nodeRoot, portableNodeBin]
+        : [path_1.default.join(nodeRoot, 'bin'), portableNodeBin];
+    return [...new Set(candidates.filter(Boolean))];
+}
+function buildPathWithManagedAgentBins(basePath) {
+    const current = basePath ?? process.env.PATH ?? '';
+    const existing = current.split(path_1.default.delimiter).filter(Boolean);
+    const merged = [...getManagedAgentBinDirs(), ...existing];
+    return [...new Set(merged)].join(path_1.default.delimiter);
+}
+function prependManagedAgentBinDirsToProcessPath() {
+    process.env.PATH = buildPathWithManagedAgentBins(process.env.PATH);
+}

package/dist/src/first-run/session-service.js

@@ -47,6 +47,7 @@ const ide_global_integration_1 = require("../cli/setup/ide-global-integration");
 const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const setup_1 = require("../cli/commands/setup");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
+const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 const types_1 = require("./types");
 Object.defineProperty(exports, "FIRST_RUN_ROW_IDS", { enumerable: true, get: function () { return types_1.FIRST_RUN_ROW_IDS; } });
 const install_state_1 = require("./install-state");
@@ -59,13 +60,16 @@ function getFakeStateMode() {
     }
     return 'default';
 }
-function commandVersion(command, extraBinDir) {
+function commandVersion(command, extraBinDirs) {
     const executable = process.platform === 'win32' ? 'cmd.exe' : command;
     const args = process.platform === 'win32'
         ? ['/d', '/s', '/c', `${command} --version`]
         : ['--version'];
-    const env = extraBinDir
-        ? { ...process.env, PATH: `${extraBinDir}${path_1.default.delimiter}${process.env.PATH || ''}` }
+    const env = extraBinDirs && extraBinDirs.length > 0
+        ? {
+            ...process.env,
+            PATH: [...new Set([...extraBinDirs, ...(process.env.PATH || '').split(path_1.default.delimiter).filter(Boolean)])].join(path_1.default.delimiter),
+        }
         : undefined;
     const result = (0, child_process_1.spawnSync)(executable, args, {
         encoding: 'utf8',
@@ -81,51 +85,25 @@ function ensureOutputDirs() {
     fs_1.default.mkdirSync((0, script_sync_utils_1.getUserFraimDir)(), { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install'), { recursive: true });
 }
-/**
- * Returns the directory that contains node/npm/npx executables for FRAIM's
- * portable Node installation.
- *
- * - Mac/Linux: ~/.fraim/node/bin  (standard Unix layout)
- * - Windows: ~/.fraim/node/node-v<version>-win-x64/ if extracted, else
- *            ~/.fraim/node/ as fallback (executables live at the root on Windows)
- */
-function getFraimNodeBinPath() {
-    const nodeRoot = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
-    if (process.platform === 'win32') {
-        if (fs_1.default.existsSync(nodeRoot)) {
-            const extractedDir = fs_1.default.readdirSync(nodeRoot, { withFileTypes: true })
-                .filter((entry) => entry.isDirectory() && entry.name.startsWith('node-v'))
-                .sort((a, b) => b.name.localeCompare(a.name))[0];
-            if (extractedDir) {
-                return path_1.default.join(nodeRoot, extractedDir.name);
-            }
-        }
-        return nodeRoot;
-    }
-    return path_1.default.join(nodeRoot, 'bin');
-}
 // Prepend the portable Node bin dir to process PATH once at module load so
 // every spawnSync call (detection, login probe, change-agent) finds binaries
 // installed there without needing per-call path overrides.
 (function bootstrapFraimNodeBin() {
-    const fraimNodeBin = getFraimNodeBinPath();
-    const current = process.env.PATH || '';
-    if (!current.split(path_1.default.delimiter).includes(fraimNodeBin)) {
-        process.env.PATH = `${fraimNodeBin}${path_1.default.delimiter}${current}`;
-    }
+    (0, managed_agent_paths_1.prependManagedAgentBinDirsToProcessPath)();
 })();
 function persistShellPath() {
-    const fraimNodeBin = getFraimNodeBinPath();
     const marker = '# FRAIM managed binaries';
     const exportLine = 'export PATH="$HOME/.fraim/node/bin:$PATH"';
     const stanza = `\n${marker}\n${exportLine}\n`;
     if (process.platform === 'win32') {
-        const escapedBin = fraimNodeBin.replace(/'/g, "''");
-        // Guard pattern matches both the versioned subdirectory and the root fallback.
+        const bins = (0, managed_agent_paths_1.getManagedAgentBinDirs)();
+        const assignments = bins.map((entry, index) => `$bin${index} = '${entry.replace(/'/g, "''")}'`);
+        const updates = bins.map((_, index) => `if ($cur -notlike "*$bin${index}*") { $cur = "$bin${index};$cur" }`);
         const psCmd = [
-            `$bin = '${escapedBin}'`,
+            ...assignments,
             `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
-            `if ($cur -notlike "*$bin*") { [Environment]::SetEnvironmentVariable('PATH', "$bin;$cur", 'User') }`,
+            ...updates,
+            `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
         ].join('; ');
         (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8' });
         return;
@@ -165,8 +143,10 @@ function appendInstallLog(line) {
 }
 function runProcess(command, args, env) {
     return new Promise((resolve, reject) => {
-        const executable = process.platform === 'win32' && command === 'npm' ? 'npm.cmd' : command;
-        const child = (0, child_process_1.spawn)(executable, args, {
+        const [realCmd, realArgs] = process.platform === 'win32'
+            ? ['cmd.exe', ['/d', '/s', '/c', command, ...args]]
+            : [command, args];
+        const child = (0, child_process_1.spawn)(realCmd, realArgs, {
             env: { ...process.env, ...(env || {}) },
             shell: false,
         });
@@ -650,6 +630,10 @@ class FirstRunSessionService {
             const prefix = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
             fs_1.default.mkdirSync(prefix, { recursive: true });
             await runProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+            const ver = commandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
+            if (!ver) {
+                throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH.`);
+            }
             const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
             if (detectedIDEs.length > 0) {
                 await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, {}, detectedIDEs.map((ide) => ide.name), {});
@@ -678,7 +662,7 @@ class FirstRunSessionService {
             return { ok: true, message: `${option.label} login triggered (fake-mode).` };
         }
         try {
-            this.openTerminalWithCommand(option.loginCommand);
+            this.openTerminalWithCommand(this.buildManagedLoginCommand(option.loginCommand));
             appendInstallLog(`agent-login-triggered ${agentId}`);
             return {
                 ok: true,
@@ -701,7 +685,7 @@ class FirstRunSessionService {
         if (this.fakeMode) {
             return { ok: true, ready: true, message: `${option.label} is ready (fake-mode).` };
         }
-        const ver = commandVersion(option.launchCommand);
+        const ver = commandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
         if (ver) {
             this.updateAgentSummaryRow();
             this.persist();
@@ -736,20 +720,23 @@ class FirstRunSessionService {
             }
         }
     }
+    buildManagedLoginCommand(command) {
+        const managedPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
+        if (process.platform === 'win32') {
+            return `set "PATH=${managedPath}" && ${command}`;
+        }
+        return `export PATH="${managedPath}"; ${command}`;
+    }
     async openHub() {
         if (this.fakeMode) {
             // Tests don't actually want a Hub server running — just confirm intent.
             return { ok: true, message: 'Fake-mode Hub open requested.', hubUrl: 'http://127.0.0.1:0/ai-hub/?firstRun=true' };
         }
-        // Require at least one Hub-compatible CLI to be installed (binary on PATH)
-        // OR fully IDE-configured. Accept freshly-installed binaries even before
-        // their IDE config files exist (created on first run / login).
+        // Hub launches a real CLI process, so folder-only config surfaces are not
+        // enough here. Require a runnable command in the managed or ambient PATH.
         const hubCompatibleBinaries = ['claude', 'codex'];
-        const hubCompatibleIds = new Set(['claude-code', 'codex']);
-        const surfaces = buildConfiguredSurfaces();
-        const hasConfiguredCli = surfaces.some((s) => hubCompatibleIds.has(s.id));
-        const hasInstalledCli = hubCompatibleBinaries.some((cmd) => commandVersion(cmd) !== null);
-        if (!hasConfiguredCli && !hasInstalledCli) {
+        const hasInstalledCli = hubCompatibleBinaries.some((cmd) => commandVersion(cmd, (0, managed_agent_paths_1.getManagedAgentBinDirs)()) !== null);
+        if (!hasInstalledCli) {
             return {
                 ok: false,
                 needsAgentSetup: true,

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.152",
+  "version": "2.0.154",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
-  "bin": "./bin/fraim.js",
+  "bin": {
+    "fraim-framework": "bin/fraim.js"
+  },
   "scripts": {
     "dev": "tsx --watch src/fraim-mcp-server.ts > server.log 2>&1",
     "dev:prod": "npm run build && node dist/src/fraim-mcp-server.js > server.log 2>&1",