fraim-framework 2.0.151 → 2.0.153

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/core/config-writer.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFraimConfigRaw = readFraimConfigRaw;
+exports.mergeFraimConfig = mergeFraimConfig;
+exports.writeFraimConfigUpdate = writeFraimConfigUpdate;
+exports.writeFraimConfig = writeFraimConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_loader_1 = require("./config-loader");
+const types_1 = require("./types");
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepMerge(baseValue, updateValue) {
+    if (updateValue === undefined) {
+        return baseValue;
+    }
+    if (Array.isArray(updateValue)) {
+        return [...updateValue];
+    }
+    if (!isPlainObject(updateValue)) {
+        return updateValue;
+    }
+    const baseObject = isPlainObject(baseValue) ? baseValue : {};
+    const merged = { ...baseObject };
+    for (const [key, value] of Object.entries(updateValue)) {
+        merged[key] = deepMerge(baseObject[key], value);
+    }
+    return merged;
+}
+function ensureWritableFraimConfigShape(rawConfig) {
+    const config = { ...rawConfig };
+    if (typeof config.version !== 'string' || config.version.trim().length === 0) {
+        config.version = types_1.DEFAULT_FRAIM_CONFIG.version;
+    }
+    const projectConfig = isPlainObject(config.project) ? config.project : {};
+    config.project = {
+        ...types_1.DEFAULT_FRAIM_CONFIG.project,
+        ...projectConfig
+    };
+    const customizationsConfig = isPlainObject(config.customizations) ? config.customizations : {};
+    config.customizations = {
+        ...types_1.DEFAULT_FRAIM_CONFIG.customizations,
+        ...customizationsConfig
+    };
+    return config;
+}
+function readFraimConfigRaw(configPath) {
+    if (!(0, fs_1.existsSync)(configPath)) {
+        return {};
+    }
+    const parsed = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    if (!isPlainObject(parsed)) {
+        throw new Error('FRAIM config must contain a JSON object at the top level.');
+    }
+    return parsed;
+}
+function mergeFraimConfig(existingRawConfig, update) {
+    const rawConfig = ensureWritableFraimConfigShape(deepMerge(existingRawConfig, update));
+    return {
+        config: (0, config_loader_1.normalizeFraimConfig)(rawConfig),
+        created: Object.keys(existingRawConfig).length === 0,
+        rawConfig
+    };
+}
+function writeFraimConfigUpdate(configPath, update) {
+    const existingRawConfig = readFraimConfigRaw(configPath);
+    const result = mergeFraimConfig(existingRawConfig, update);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(configPath), { recursive: true });
+    (0, fs_1.writeFileSync)(configPath, JSON.stringify(result.rawConfig, null, 2));
+    return result;
+}
+function writeFraimConfig(configPath, config) {
+    return writeFraimConfigUpdate(configPath, config);
+}

package/dist/src/core/utils/job-aliases.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPRECATED_FRAIM_JOB_NAMES = void 0;
+exports.resolveFraimJobName = resolveFraimJobName;
+exports.isListableFraimJob = isListableFraimJob;
+const DEPRECATED_TO_CANONICAL_JOB_MAP = {
+    'learn-and-scale': 'upskill-employee',
+    'model-behavior': 'upskill-employee',
+    'promote-learning': 'upskill-employee',
+    'refine-jobs': 'upskill-employee',
+    'refine-skills': 'upskill-employee'
+};
+const DIRECT_JOB_ALIASES = {
+    'sleep on learnings': 'sleep-on-learnings'
+};
+exports.DEPRECATED_FRAIM_JOB_NAMES = new Set(Object.keys(DEPRECATED_TO_CANONICAL_JOB_MAP));
+function normalizeJobLookupInput(input) {
+    return input.trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+function resolveFraimJobName(input) {
+    const normalizedJobName = normalizeJobLookupInput(input);
+    const directAliasTarget = DIRECT_JOB_ALIASES[input.trim().toLowerCase()];
+    if (directAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: directAliasTarget
+        };
+    }
+    const deprecatedAliasTarget = DEPRECATED_TO_CANONICAL_JOB_MAP[normalizedJobName];
+    if (deprecatedAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: deprecatedAliasTarget,
+            deprecatedAliasTarget
+        };
+    }
+    return {
+        requestedJobName: input,
+        normalizedJobName,
+        canonicalJobName: normalizedJobName
+    };
+}
+function isListableFraimJob(jobName) {
+    return !exports.DEPRECATED_FRAIM_JOB_NAMES.has(normalizeJobLookupInput(jobName));
+}

package/dist/src/core/utils/workflow-parser.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowParser = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+class WorkflowParser {
+    static extractMetadataBlock(content) {
+        const frontmatterMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+        if (frontmatterMatch) {
+            try {
+                return {
+                    state: 'valid',
+                    metadata: JSON.parse(frontmatterMatch[1]),
+                    bodyStartIndex: frontmatterMatch[0].length
+                };
+            }
+            catch {
+                return { state: 'invalid' };
+            }
+        }
+        const trimmedStart = content.search(/\S/);
+        if (trimmedStart === -1 || content[trimmedStart] !== '{') {
+            return { state: 'none' };
+        }
+        let depth = 0;
+        let inString = false;
+        let escaping = false;
+        for (let i = trimmedStart; i < content.length; i++) {
+            const ch = content[i];
+            if (inString) {
+                if (escaping) {
+                    escaping = false;
+                }
+                else if (ch === '\\') {
+                    escaping = true;
+                }
+                else if (ch === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+                continue;
+            }
+            if (ch === '{') {
+                depth++;
+                continue;
+            }
+            if (ch === '}') {
+                depth--;
+                if (depth === 0) {
+                    const bodyStartIndex = i + 1;
+                    const remainder = content.slice(bodyStartIndex).trimStart();
+                    // `{...}\n---` is usually malformed frontmatter, not bare JSON metadata.
+                    if (remainder.startsWith('---')) {
+                        return { state: 'none' };
+                    }
+                    try {
+                        return {
+                            state: 'valid',
+                            metadata: JSON.parse(content.slice(trimmedStart, bodyStartIndex)),
+                            bodyStartIndex
+                        };
+                    }
+                    catch {
+                        return { state: 'invalid' };
+                    }
+                }
+            }
+        }
+        return { state: 'none' };
+    }
+    /**
+     * Parse a workflow markdown file into a structured definition
+     * Supports three formats:
+     * 1. Phase-based workflows with JSON frontmatter
+     * 2. Phase-based workflows with bare leading JSON metadata
+     * 3. Simple workflows without metadata
+     */
+    static parse(filePath) {
+        if (!(0, fs_1.existsSync)(filePath))
+            return null;
+        let content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        if (content.charCodeAt(0) === 0xfeff) {
+            content = content.slice(1);
+        }
+        const metadataBlock = this.extractMetadataBlock(content);
+        if (metadataBlock.state === 'invalid') {
+            return null;
+        }
+        if (metadataBlock.state === 'valid') {
+            return this.parsePhaseBasedWorkflow(filePath, content, metadataBlock.metadata, metadataBlock.bodyStartIndex);
+        }
+        return this.parseSimpleWorkflow(filePath, content);
+    }
+    static parsePhaseBasedWorkflow(filePath, content, metadata, bodyStartIndex) {
+        const contentAfterMetadata = content.substring(bodyStartIndex).trim();
+        const firstPhaseIndex = contentAfterMetadata.search(/^##\s+Phase:/m);
+        let overview = '';
+        let restOfContent = '';
+        if (firstPhaseIndex !== -1) {
+            overview = contentAfterMetadata.substring(0, firstPhaseIndex).trim();
+            restOfContent = contentAfterMetadata.substring(firstPhaseIndex);
+        }
+        else {
+            overview = contentAfterMetadata;
+        }
+        const phases = new Map();
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
+        if (!metadata.phases) {
+            metadata.phases = {};
+        }
+        for (let i = 1; i < phaseSections.length; i++) {
+            const section = phaseSections[i];
+            const sectionLines = section.split('\n');
+            const firstLine = sectionLines[0].trim();
+            const id = firstLine.split(/[ (]/)[0].trim().toLowerCase();
+            phases.set(id, `## Phase: ${section.trim()}`);
+        }
+        return {
+            metadata,
+            overview,
+            phases,
+            isSimple: false,
+            path: filePath
+        };
+    }
+    static parseSimpleWorkflow(filePath, content) {
+        const workflowName = (0, path_1.basename)(filePath, '.md');
+        const metadata = {
+            name: workflowName
+        };
+        return {
+            metadata,
+            overview: content.trim(),
+            phases: new Map(),
+            isSimple: true,
+            path: filePath
+        };
+    }
+    static parseContent(content, name, path) {
+        if (content.charCodeAt(0) === 0xfeff) {
+            content = content.slice(1);
+        }
+        const metadataBlock = this.extractMetadataBlock(content);
+        if (metadataBlock.state === 'invalid') {
+            return null;
+        }
+        if (metadataBlock.state === 'valid') {
+            return this.parsePhaseBasedWorkflow(path || `content:${name}`, content, metadataBlock.metadata, metadataBlock.bodyStartIndex);
+        }
+        return this.parseSimpleWorkflow(path || `content:${name}`, content);
+    }
+    static getOverviewFromContent(content, name) {
+        const wf = this.parseContent(content, name);
+        return wf ? wf.overview : null;
+    }
+    static getOverview(filePath) {
+        const wf = this.parse(filePath);
+        return wf ? wf.overview : null;
+    }
+    static extractDescription(filePath) {
+        const wf = this.parse(filePath);
+        if (!wf)
+            return '';
+        const intentMatch = wf.overview.match(/## Intent\s+([\s\S]+?)(?:\r?\n##|$)/);
+        if (intentMatch)
+            return intentMatch[1].trim().split(/\r?\n/)[0];
+        const firstPara = wf.overview.split(/\r?\n/).find(l => l.trim() !== '' && !l.startsWith('#'));
+        return firstPara ? firstPara.trim() : '';
+    }
+}
+exports.WorkflowParser = WorkflowParser;

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/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework - Smart Entry Point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.151",
+  "version": "2.0.153",
   "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",