fraim 2.0.128 → 2.0.130

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

@@ -43,9 +43,9 @@ const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
 const child_process_1 = require("child_process");
 const ide_detector_1 = require("../cli/setup/ide-detector");
+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 init_project_1 = require("../cli/commands/init-project");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const types_1 = require("./types");
 Object.defineProperty(exports, "FIRST_RUN_ROW_IDS", { enumerable: true, get: function () { return types_1.FIRST_RUN_ROW_IDS; } });
@@ -54,31 +54,23 @@ function getFakeStateMode() {
     if (process.env.FRAIM_FIRST_RUN_FAKE !== '1')
         return null;
     const explicit = process.env.FRAIM_FIRST_RUN_FAKE_STATE;
-    if (explicit === 'all-pending' || explicit === 'all-detected' || explicit === 'agent-install-fails') {
+    if (explicit === 'all-pending' || explicit === 'all-detected' || explicit === 'agent-install-fails' || explicit === 'no-agents') {
         return explicit;
     }
     return 'default';
 }
-function commandExists(command) {
-    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',
-        stdio: ['ignore', 'ignore', 'ignore'],
-        shell: false,
-    });
-    return result.status === 0;
-}
-function commandVersion(command) {
+function commandVersion(command, extraBinDir) {
     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 || ''}` }
+        : undefined;
     const result = (0, child_process_1.spawnSync)(executable, args, {
         encoding: 'utf8',
         timeout: 5000,
+        ...(env ? { env } : {}),
     });
     if (result.status !== 0)
         return null;
@@ -89,6 +81,78 @@ 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}`;
+    }
+})();
+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 psCmd = [
+            `$bin = '${escapedBin}'`,
+            `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+            `if ($cur -notlike "*$bin*") { [Environment]::SetEnvironmentVariable('PATH', "$bin;$cur", 'User') }`,
+        ].join('; ');
+        (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8' });
+        return;
+    }
+    const profiles = [
+        path_1.default.join(os_1.default.homedir(), '.zshrc'),
+        path_1.default.join(os_1.default.homedir(), '.bash_profile'),
+        path_1.default.join(os_1.default.homedir(), '.bashrc'),
+    ];
+    // macOS defaults to zsh since Catalina — create .zshrc if it doesn't exist.
+    if (process.platform === 'darwin' && !fs_1.default.existsSync(profiles[0])) {
+        fs_1.default.writeFileSync(profiles[0], stanza, 'utf8');
+    }
+    for (const profile of profiles) {
+        try {
+            if (!fs_1.default.existsSync(profile))
+                continue;
+            const content = fs_1.default.readFileSync(profile, 'utf8');
+            if (content.includes(marker))
+                continue;
+            fs_1.default.appendFileSync(profile, stanza, 'utf8');
+        }
+        catch {
+            // Ignore unreadable or missing profiles.
+        }
+    }
+}
 function getNextPromptPath() {
     return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install', 'next-prompt.txt');
 }
@@ -99,16 +163,46 @@ function appendInstallLog(line) {
     ensureOutputDirs();
     fs_1.default.appendFileSync(getInstallLogPath(), `[${new Date().toISOString()}] ${line}${os_1.default.EOL}`);
 }
+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, {
+            env: { ...process.env, ...(env || {}) },
+            shell: false,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            reject(new Error(`${command} ${args.join(' ')} failed with code ${code}\n${stdout}${stderr}`.trim()));
+        });
+    });
+}
 function findAgentOption(agentId) {
     return types_1.FIRST_RUN_AGENT_OPTIONS.find((option) => option.id === agentId);
 }
-function pendingVerbForAgent(agentId) {
-    const option = findAgentOption(agentId);
-    if (!option)
-        return "we'll set up the recommended agent";
-    if (agentId === 'claude-code')
-        return "we'll set up Claude Code (recommended)";
-    return `we'll set up ${option.label}`;
+function normalizeRows(rows) {
+    const existingById = new Map(rows.map((row) => [row.id, row]));
+    return (0, types_1.createInitialRows)().map((canonical) => ({
+        ...canonical,
+        ...(existingById.get(canonical.id) || {}),
+    }));
+}
+function buildConfiguredSurfaces() {
+    const ides = (0, ide_detector_1.detectInstalledIDEs)();
+    const hints = (0, ide_global_integration_1.describeOnboardingInvocationSurfaces)(ides);
+    return ides.map((ide, index) => ({
+        id: ide.configType,
+        name: ide.name,
+        invocationHint: hints[index] || '/fraim onboard this project',
+        status: 'configured',
+    }));
 }
 class FirstRunSessionService {
     constructor(options) {
@@ -120,6 +214,7 @@ class FirstRunSessionService {
                 ['npm error code EACCES', 'npm error syscall mkdir'].join('\n');
         this.requestToken = crypto_1.default.randomUUID();
         this.state = options.resume ? (0, install_state_1.loadFirstRunState)() || (0, install_state_1.createInitialFirstRunState)(options.key) : (0, install_state_1.createInitialFirstRunState)(options.key);
+        this.state.rows = normalizeRows(this.state.rows);
         if (options.projectRoot) {
             this.state.workspacePath = path_1.default.resolve(options.projectRoot);
             (0, install_state_1.saveFirstRunState)(this.state);
@@ -131,7 +226,7 @@ class FirstRunSessionService {
     getRow(rowId) {
         const row = this.state.rows.find((r) => r.id === rowId);
         if (!row) {
-            throw new Error(`Row ${rowId} not found in state — initial rows must include all canonical IDs`);
+            throw new Error(`Row ${rowId} not found in state — initial rows must include all canonical IDs`);
         }
         return row;
     }
@@ -139,17 +234,40 @@ class FirstRunSessionService {
         delete row.errorFrame;
         delete row.streamOutput;
     }
-    setRowError(row, whatTried, whatHappened, actions) {
+    setRowError(row, whatTried, whatHappened, actions, hint) {
         row.status = 'error';
-        row.verb = 'failed — see below';
-        row.errorFrame = { whatTried, whatHappened, actions };
+        row.verb = 'failed — see below';
+        row.errorFrame = { whatTried, whatHappened, actions, ...(hint ? { hint } : {}) };
+    }
+    /**
+     * Classify a thrown init/sync error into a non-tech-friendly hint.
+     * The verbatim stderr is preserved separately in `whatHappened` per
+     * R6.3 — the hint is additive context, not a replacement.
+     */
+    classifyInitError(detail) {
+        if (/status code 401|Unauthorized|401\b/i.test(detail)) {
+            return "Your FRAIM install key was rejected by the registry. If your key expired, get a new one from your account page and re-run setup with the new key. If you're testing locally, set `FRAIM_LOCAL_SYNC=1` so the project row syncs from your local FRAIM server instead of the production registry.";
+        }
+        if (/status code 403|Forbidden/i.test(detail)) {
+            return "The FRAIM registry refused this key for this project. Check that your install key has access to the registry you're syncing from.";
+        }
+        if (/status code 5\d\d/i.test(detail) || /5\d\d\b/.test(detail)) {
+            return 'The FRAIM registry returned a server error. This is usually transient — wait a minute and click Retry. If it keeps failing, the registry may be down.';
+        }
+        if (/ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|getaddrinfo|network/i.test(detail)) {
+            return "Couldn't reach the FRAIM registry. Check your internet connection (or if you're testing locally, that the local FRAIM server is running) and click Retry.";
+        }
+        if (/Global FRAIM setup not found/i.test(detail)) {
+            return 'FRAIM\'s global config is missing. This usually means the agent step didn\'t complete cleanly — go back and re-run the AI agent row.';
+        }
+        return undefined;
     }
     detectRowsOnLoad() {
         if (this.fakeMode) {
             this.applyFakeStateOnLoad(this.fakeMode);
             return;
         }
-        // Real detection — populate row statuses from `command -v` style probes.
+        // Real detection — populate row statuses from `command -v` style probes.
         const nodeRow = this.getRow('node');
         const nodeVer = commandVersion('node');
         if (nodeVer) {
@@ -170,53 +288,38 @@ class FirstRunSessionService {
             gitRow.status = 'pending';
             gitRow.verb = "we'll install";
         }
-        const agentRow = this.getRow('agent');
-        const detected = this.detectAnyKnownAgent();
-        if (detected) {
-            this.state.agentId = detected.id;
-            agentRow.status = 'ok';
-            agentRow.verb = `${detected.label} detected`;
-            agentRow.detail = detected.versionLine ?? undefined;
-        }
-        else {
-            agentRow.status = 'pending';
-            agentRow.verb = pendingVerbForAgent(this.state.agentId);
-        }
-        const loginRow = this.getRow('agent-login');
-        if (agentRow.status === 'ok' && this.probeAgentReady(this.state.agentId).ok) {
-            loginRow.status = 'ok';
-            loginRow.verb = 'Signed in (verified)';
-        }
-        else {
-            loginRow.status = 'pending';
-            loginRow.verb = "you'll sign in after install";
-        }
-        const projectRow = this.getRow('project');
-        if (this.state.workspacePath && fs_1.default.existsSync(this.state.workspacePath)) {
-            projectRow.status = 'ok';
-            projectRow.verb = this.state.workspacePath;
+        const fraimRow = this.getRow('fraim');
+        if (commandVersion('npx') !== null) {
+            fraimRow.status = 'ok';
+            fraimRow.verb = 'ready';
+            persistShellPath();
         }
         else {
-            projectRow.status = 'manual-required';
-            projectRow.verb = 'pick a folder where FRAIM should work';
+            fraimRow.status = 'pending';
+            fraimRow.verb = "we'll set up FRAIM";
         }
+        this.updateAgentSummaryRow();
     }
-    detectAnyKnownAgent() {
-        // Priority order matches FIRST_RUN_AGENT_OPTIONS ordering.
-        for (const option of types_1.FIRST_RUN_AGENT_OPTIONS) {
-            if (commandExists(option.launchCommand)) {
-                return { id: option.id, label: option.label, versionLine: commandVersion(option.launchCommand) };
-            }
-        }
-        // Also accept matches via the IDE detector for desktop variants.
-        const ides = (0, ide_detector_1.detectInstalledIDEs)();
-        for (const option of types_1.FIRST_RUN_AGENT_OPTIONS) {
-            const ide = ides.find((entry) => entry.aliases?.some((a) => option.detectAliases.includes(a)));
-            if (ide) {
-                return { id: option.id, label: option.label, versionLine: null };
-            }
+    updateAgentSummaryRow() {
+        const agentRow = this.getRow('agent');
+        const surfaces = this.fakeMode === 'no-agents' ? [] : buildConfiguredSurfaces();
+        if (surfaces.length > 0) {
+            agentRow.status = 'ok';
+            agentRow.verb = `${surfaces.length} AI Employee${surfaces.length === 1 ? '' : 's'} ready`;
+            agentRow.detail = surfaces.map((surface) => surface.name).join(', ');
         }
-        return null;
+        else {
+            agentRow.status = 'manual-required';
+            agentRow.verb = "let's recruit AI Employees";
+            delete agentRow.detail;
+        }
+        this.state.setupResult = {
+            mode: 'conversational',
+            configuredSurfaces: surfaces,
+            failedSurfaces: [],
+            detectedSurfaceCount: surfaces.length,
+            completedAt: new Date().toISOString(),
+        };
     }
     applyFakeStateOnLoad(mode) {
         const setStatus = (rowId, status, verb, detail) => {
@@ -229,33 +332,63 @@ class FirstRunSessionService {
         if (mode === 'all-pending') {
             setStatus('node', 'pending', "we'll install");
             setStatus('git', 'pending', "we'll install");
-            setStatus('agent', 'pending', pendingVerbForAgent(this.state.agentId));
-            setStatus('agent-login', 'pending', "you'll sign in after install");
-            setStatus('project', 'manual-required', 'pick a folder where FRAIM should work');
+            setStatus('fraim', 'pending', "we'll install");
+            setStatus('agent', 'pending', "we'll check for AI Employees");
+            delete this.state.setupResult;
             return;
         }
         if (mode === 'all-detected') {
             setStatus('node', 'ok', 'v20.11.1 detected');
             setStatus('git', 'ok', 'git version 2.45 detected');
-            setStatus('agent', 'ok', 'Claude Code v1.4.2 detected');
-            setStatus('agent-login', 'ok', 'Signed in (verified by claude -p probe)');
-            setStatus('project', 'manual-required', 'pick a folder where FRAIM should work');
+            setStatus('fraim', 'ok', 'fraim-framework detected');
+            setStatus('agent', 'ok', '1 AI Employee ready', 'Claude Code');
+            this.state.setupResult = {
+                mode: 'conversational',
+                configuredSurfaces: [
+                    { id: 'claude-code', name: 'Claude Code', invocationHint: 'Claude Code: /fraim onboard this project', status: 'configured' },
+                ],
+                failedSurfaces: [],
+                detectedSurfaceCount: 1,
+                completedAt: new Date().toISOString(),
+            };
+            return;
+        }
+        if (mode === 'no-agents') {
+            setStatus('node', 'ok', 'v20.11.1 detected');
+            setStatus('git', 'ok', 'git version 2.45 detected');
+            setStatus('fraim', 'ok', 'fraim-framework detected');
+            setStatus('agent', 'manual-required', "let's recruit AI Employees");
+            this.state.setupResult = {
+                mode: 'conversational',
+                configuredSurfaces: [],
+                failedSurfaces: [],
+                detectedSurfaceCount: 0,
+                completedAt: new Date().toISOString(),
+            };
             return;
         }
         if (mode === 'agent-install-fails') {
             setStatus('node', 'ok', 'v20.11.1 installed');
             setStatus('git', 'ok', '2.45 installed');
-            setStatus('agent', 'pending', pendingVerbForAgent(this.state.agentId));
-            setStatus('agent-login', 'pending', "you'll sign in after install");
-            setStatus('project', 'manual-required', 'pick a folder where FRAIM should work');
+            setStatus('fraim', 'ok', 'fraim-framework installed');
+            setStatus('agent', 'pending', "we'll check for AI Employees");
+            delete this.state.setupResult;
             return;
         }
-        // 'default' fake mode — everything ok, project still requires a pick.
+        // 'default' fake mode — infra rows all ok.
         setStatus('node', 'ok', 'v20.11.1 detected');
         setStatus('git', 'ok', 'git version 2.45 detected');
-        setStatus('agent', 'ok', 'fake-mode agent detected');
-        setStatus('agent-login', 'ok', 'fake-mode signed in');
-        setStatus('project', 'manual-required', 'pick a folder where FRAIM should work');
+        setStatus('fraim', 'ok', 'fake-mode fraim installed');
+        setStatus('agent', 'ok', 'fake-mode AI Employee ready', 'Claude Code');
+        this.state.setupResult = {
+            mode: 'conversational',
+            configuredSurfaces: [
+                { id: 'claude-code', name: 'Claude Code', invocationHint: 'Claude Code: /fraim onboard this project', status: 'configured' },
+            ],
+            failedSurfaces: [],
+            detectedSurfaceCount: 1,
+            completedAt: new Date().toISOString(),
+        };
     }
     getRequestToken() {
         return this.requestToken;
@@ -303,16 +436,14 @@ class FirstRunSessionService {
                     return await this.runNodeRow();
                 case 'git':
                     return await this.runGitRow();
+                case 'fraim':
+                    return await this.runFraimRow();
                 case 'agent':
                     return await this.runAgentRow(request);
-                case 'agent-login':
-                    return await this.runAgentLoginRow(request);
-                case 'project':
-                    return await this.runProjectRow(request);
             }
         }
         catch (error) {
-            // Last-ditch safety net — every row's runner is supposed to surface
+            // Last-ditch safety net — every row's runner is supposed to surface
             // its own R6 frame via setRowError before throwing, but if anything
             // slips past (e.g. a sync layer that calls process.exit and we narrowly
             // converted it to throw), we still surface a frame here rather than
@@ -320,7 +451,7 @@ class FirstRunSessionService {
             // user is never wedged on a non-recoverable failure of one row.
             const message = error instanceof Error ? error.message : 'Unknown error';
             row.status = 'error';
-            row.verb = 'failed — see below';
+            row.verb = 'failed — see below';
             row.errorFrame = {
                 whatTried: `Running ${row.label} step`,
                 whatHappened: message,
@@ -373,250 +504,80 @@ class FirstRunSessionService {
         this.persist();
         return this.respond('git not detected.', false);
     }
-    async runAgentRow(request) {
-        const row = this.getRow('agent');
-        // If the user picked an alternative through the error frame, switch and continue.
-        if (request.errorActionId === 'alternative' && request.alternativeAgentId) {
-            this.state.agentId = request.alternativeAgentId;
-            row.verb = pendingVerbForAgent(this.state.agentId);
-        }
-        if (request.errorActionId === 'skip') {
-            row.status = 'manual-required';
-            row.verb = 'you said you\'ll set up the agent yourself';
-            // If the user skipped agent install, sign-in is also their problem —
-            // there's no agent to sign into. Mark agent-login manual-required so
-            // the auto-progress loop doesn't try to probe a nonexistent CLI on
-            // the next Continue click.
-            const loginRow = this.getRow('agent-login');
-            if (loginRow.status !== 'ok') {
-                loginRow.status = 'manual-required';
-                loginRow.verb = "you'll handle sign-in when you set up the agent";
-            }
-            this.persist();
-            return this.respond('Agent setup deferred.', true);
-        }
-        const option = findAgentOption(this.state.agentId);
-        if (!option) {
-            this.setRowError(row, 'Looking up the AI agent install command', `Unknown agent id: ${this.state.agentId}`, [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
-            this.persist();
-            return this.respond('Unknown agent.', false);
-        }
-        // Fake mode short-circuit — never call real OS commands. The whole point
-        // of fake mode is hermetic, deterministic test rendering.
-        if (this.fakeMode === 'agent-install-fails') {
-            this.setRowError(row, `Installing ${option.label} via npm install -g ${option.installPackage}`, this.fakeStderr, this.buildAgentInstallActions(this.state.agentId));
-            this.persist();
-            return this.respond('Fake-mode agent install failed.', false);
-        }
+    async runFraimRow() {
+        const row = this.getRow('fraim');
         if (this.fakeMode) {
             row.status = 'ok';
-            row.verb = `${option.label} installed (fake-mode)`;
+            row.verb = 'FRAIM ready (fake-mode)';
             this.persist();
-            return this.respond('Fake-mode agent installed.', true);
+            return this.respond('Fake-mode fraim ok.', true);
         }
-        // Real path: detect first — if already installed we skip install entirely.
-        const existingVer = commandVersion(option.launchCommand);
-        if (existingVer) {
+        try {
+            if (!commandVersion('fraim')) {
+                const prefix = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
+                fs_1.default.mkdirSync(prefix, { recursive: true });
+                row.streamOutput = 'Installing FRAIM on this machine...';
+                this.persist();
+                await runProcess('npm', ['install', '-g', 'fraim-framework@latest'], { npm_config_prefix: prefix });
+            }
+            persistShellPath();
+            (0, setup_1.saveGlobalConfig)(this.key, 'conversational', {}, {});
+            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), {});
+            }
+            const { syncUserLevelArtifacts } = await Promise.resolve().then(() => __importStar(require('../cli/setup/user-level-sync')));
+            await syncUserLevelArtifacts();
+            const { installSlashCommands, installGlobalRules } = await Promise.resolve().then(() => __importStar(require('../cli/setup/ide-global-integration')));
+            await installSlashCommands();
+            await installGlobalRules();
             row.status = 'ok';
-            row.verb = `${option.label} ${existingVer} detected`;
-            row.detail = existingVer;
+            row.verb = 'Ready.';
+            delete row.streamOutput;
             this.persist();
-            return this.respond(`${option.label} already installed.`, true);
+            return this.respond('FRAIM is ready.', true);
         }
-        // Real install — npm install -g <package>. Stream output into row.streamOutput.
-        const result = (0, child_process_1.spawnSync)('npm', ['install', '-g', option.installPackage], {
-            encoding: 'utf8',
-            timeout: 300000,
-        });
-        const combined = `${result.stdout || ''}${result.stderr || ''}`.trim();
-        row.streamOutput = combined.slice(-4000);
-        if (result.status === 0) {
-            const ver = commandVersion(option.launchCommand) ?? 'installed';
-            row.status = 'ok';
-            row.verb = `${option.label} ${ver}`;
-            row.detail = ver;
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'Unknown error';
+            this.setRowError(row, 'Setting up FRAIM on this machine', detail, [
+                { id: 'retry', label: 'Retry', variant: 'primary' },
+                { id: 'skip', label: 'Skip and continue', variant: 'ghost' },
+            ]);
             this.persist();
-            return this.respond(`${option.label} installed.`, true);
+            return this.respond('FRAIM setup failed.', false);
         }
-        this.setRowError(row, `Installing ${option.label} via npm install -g ${option.installPackage}`, combined || `npm install -g ${option.installPackage} exited ${result.status}`, this.buildAgentInstallActions(this.state.agentId));
-        this.persist();
-        return this.respond(`${option.label} install failed.`, false);
     }
-    buildAgentInstallActions(currentAgentId) {
-        const others = types_1.FIRST_RUN_AGENT_OPTIONS.filter((option) => option.id !== currentAgentId);
-        const actions = [
-            { id: 'retry', label: 'Retry', variant: 'primary' },
-        ];
-        if (others.length > 0) {
-            actions.push({
-                id: 'alternative',
-                label: `Try ${others[0].label} instead`,
-                variant: 'secondary',
-                alternativeAgentId: others[0].id,
-            });
-        }
-        actions.push({ id: 'skip', label: 'Skip and continue', variant: 'ghost' });
-        return actions;
-    }
-    async runAgentLoginRow(request) {
-        const row = this.getRow('agent-login');
-        if (request.errorActionId === 'skip') {
-            row.status = 'manual-required';
-            row.verb = "you'll sign in later from the Hub";
-            this.persist();
-            return this.respond('Agent login deferred.', true);
-        }
-        const option = findAgentOption(this.state.agentId);
-        if (!option) {
-            this.setRowError(row, 'Resolving agent login command', `Unknown agent id: ${this.state.agentId}`, [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
-            this.persist();
-            return this.respond('Unknown agent for login.', false);
-        }
-        if (this.fakeMode) {
-            row.status = 'ok';
-            row.verb = 'Signed in (fake-mode)';
-            this.persist();
-            return this.respond('Fake-mode signed in.', true);
-        }
-        // First, see whether the agent is already authenticated.
-        const probe = this.probeAgentReady(this.state.agentId);
-        if (probe.ok) {
-            row.status = 'ok';
-            row.verb = 'Signed in (verified)';
-            this.persist();
-            return this.respond(`${option.label} signed in.`, true);
-        }
-        // Not authenticated yet — surface as manual-required with a clear message.
-        // We do NOT auto-spawn `claude login` from here because OAuth flows differ
-        // by agent and need the user's actual browser. The client renders a
-        // "Sign in to Claude in the new tab" prompt and polls back via Retry.
-        row.status = 'manual-required';
-        row.verb = `Sign in to ${option.label} (then click Retry)`;
-        row.manualMessage = `Open a terminal and run \`${option.loginCommand}\`. We'll detect when you're signed in.`;
-        this.persist();
-        return this.respond(`Awaiting ${option.label} login.`, true);
-    }
-    probeAgentReady(agentId) {
-        if (this.fakeMode)
-            return { ok: this.fakeMode !== 'agent-install-fails', output: 'fake' };
-        const option = findAgentOption(agentId);
-        if (!option)
-            return { ok: false, output: 'unknown agent' };
-        if (agentId === 'codex') {
-            const result = (0, child_process_1.spawnSync)('codex', ['exec', '--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox'], {
-                cwd: this.state.workspacePath || process.cwd(),
-                input: 'Reply exactly "FRAIM_READY" if FRAIM is available in this workspace. Otherwise reply exactly "NOT_READY".',
-                encoding: 'utf8',
-                timeout: 60000,
-            });
-            const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-            return { ok: result.status === 0 && output.toUpperCase().includes('FRAIM'), output };
-        }
-        if (agentId === 'claude-code') {
-            const result = (0, child_process_1.spawnSync)('claude', ['-p', '--verbose', '--output-format', 'stream-json', '--dangerously-skip-permissions'], {
-                cwd: this.state.workspacePath || process.cwd(),
-                input: 'Reply exactly "FRAIM_READY" if FRAIM is available in this workspace. Otherwise reply exactly "NOT_READY".',
-                encoding: 'utf8',
-                timeout: 60000,
-            });
-            const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-            return { ok: result.status === 0 && output.toUpperCase().includes('FRAIM'), output };
-        }
-        // Gemini probe is `--help` based until Gemini ships a stronger non-interactive path.
-        const result = (0, child_process_1.spawnSync)('gemini', ['--help'], {
-            cwd: this.state.workspacePath || process.cwd(),
-            encoding: 'utf8',
-            timeout: 30000,
-        });
-        return { ok: result.status === 0, output: `${result.stdout || ''}${result.stderr || ''}`.trim() };
-    }
-    async runProjectRow(request) {
-        const row = this.getRow('project');
-        // Skip-and-continue contract: a user who explicitly skips this row chose
-        // to set the project up themselves later. Mark manual-required so the
-        // primary-button derivation can route to Open Hub via the skip-path rule.
+    async runAgentRow(request) {
+        const row = this.getRow('agent');
         if (request.errorActionId === 'skip') {
             row.status = 'manual-required';
-            row.verb = "you'll pick a project folder later";
-            this.clearRowError(row);
-            this.persist();
-            return this.respond('Project deferred.', true);
-        }
-        const projectPath = request.projectPath ?? this.state.workspacePath;
-        if (!projectPath) {
-            row.status = 'manual-required';
-            row.verb = 'pick a folder where FRAIM should work';
+            row.verb = "let's recruit AI Employees";
+            this.state.setupResult = {
+                mode: 'conversational',
+                configuredSurfaces: [],
+                failedSurfaces: [],
+                detectedSurfaceCount: 0,
+                completedAt: new Date().toISOString(),
+            };
             this.persist();
-            return this.respond('Project path required.', false);
-        }
-        const resolvedPath = path_1.default.resolve(projectPath);
-        fs_1.default.mkdirSync(resolvedPath, { recursive: true });
-        if (commandExists('git')) {
-            try {
-                (0, child_process_1.execSync)('git rev-parse --git-dir', { cwd: resolvedPath, stdio: 'ignore' });
-            }
-            catch {
-                try {
-                    (0, child_process_1.execSync)('git init', { cwd: resolvedPath, stdio: 'ignore' });
-                }
-                catch (gitError) {
-                    // Surface but don't fail the row — init-project will still work.
-                    appendInstallLog(`git init failed at ${resolvedPath}: ${gitError instanceof Error ? gitError.message : 'unknown'}`);
-                }
-            }
-        }
-        if (!this.fakeMode) {
-            // Configure FRAIM globals + agent MCP wiring before init-project runs.
-            (0, setup_1.saveGlobalConfig)(this.key, 'conversational', {}, {});
-            const selectedAgent = (0, ide_detector_1.findIDEByName)(this.state.agentId);
-            const targetNames = selectedAgent ? [selectedAgent.name] : undefined;
-            try {
-                await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, {}, targetNames, {});
-            }
-            catch (mcpError) {
-                appendInstallLog(`autoConfigureMCP non-fatal error: ${mcpError instanceof Error ? mcpError.message : 'unknown'}`);
-            }
-            // Pass failHard:'throw' so a sync 401 / network error / missing-key
-            // bubbles back here instead of calling process.exit(1) and killing the
-            // FRE server. The catch below converts it into the R6 error frame.
-            try {
-                await (0, init_project_1.runInitProject)({ projectRoot: resolvedPath, failHard: 'throw' });
-            }
-            catch (initError) {
-                const detail = initError instanceof Error ? initError.message : 'Unknown init error';
-                // Skip is intentionally omitted on the project row — without a
-                // project there is no Hub to open, so deferring this row would
-                // leave the user wedged. Retry is always offered; if the failure
-                // is a 401 from remote sync, the verbatim message tells the user
-                // their API key is the problem and they need to re-run with a
-                // valid key.
-                this.setRowError(row, `Initializing FRAIM in ${resolvedPath}`, detail, [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
-                appendInstallLog(`project-init-failed ${resolvedPath}: ${detail}`);
-                this.persist();
-                return this.respond(`Initialization failed: ${detail}`, false);
-            }
+            return this.respond('AI Employee recruiting deferred.', true);
         }
-        this.state.workspacePath = resolvedPath;
-        row.status = 'ok';
-        row.verb = resolvedPath;
+        this.updateAgentSummaryRow();
         this.persist();
-        appendInstallLog(`project-initialized ${resolvedPath}`);
-        return this.respond(`Initialized FRAIM in ${resolvedPath}.`, true);
+        const count = this.state.setupResult?.detectedSurfaceCount || 0;
+        return this.respond(count > 0 ? 'AI Employees are ready.' : 'No AI Employees found.', true);
     }
     /**
-     * Update the current agent selection (inline `Change…` picker). Recomputes
-     * the agent and agent-login row verbs but does not run any installs.
+     * Update the current agent selection (inline `Change…` picker).
+     * Records the preference for future recruiting workflows; does not run any installs.
      */
     changeAgent(req) {
         if (req.customAgent) {
             this.state.customAgent = { name: req.customAgent.name, invocationPrefix: req.customAgent.invocationPrefix };
             const agentRow = this.getRow('agent');
-            const loginRow = this.getRow('agent-login');
-            agentRow.status = 'ok';
+            agentRow.status = 'manual-required';
             agentRow.verb = `Custom CLI recorded: ${req.customAgent.name}`;
-            agentRow.detail = `(advanced — Hub will not auto-invoke unknown CLIs in v1)`;
-            loginRow.status = 'manual-required';
-            loginRow.verb = `Sign in to ${req.customAgent.name} yourself`;
+            agentRow.detail = 'Run npx fraim add-ide after installing it.';
             this.persist();
             appendInstallLog(`custom-agent recorded ${req.customAgent.name}`);
             return this.respond(`Custom agent "${req.customAgent.name}" recorded.`, true);
@@ -628,53 +589,9 @@ class FirstRunSessionService {
         if (!option) {
             return this.respond(`Unknown agent: ${req.agentId}`, false);
         }
-        const previousAgentId = this.state.agentId;
         this.state.agentId = req.agentId;
         delete this.state.customAgent;
-        const agentRow = this.getRow('agent');
-        const loginRow = this.getRow('agent-login');
-        // If the user actually switched to a different agent, the row state from
-        // the previous agent is now stale — even if it was `ok`. The new agent
-        // has not been detected, installed, verified, or signed in. Re-detect
-        // the new agent and reset both rows so the next run executes against
-        // the new selection rather than silently keeping the previous verbs.
-        if (previousAgentId !== req.agentId) {
-            this.clearRowError(agentRow);
-            const detectedVer = this.fakeMode ? null : commandVersion(option.launchCommand);
-            if (detectedVer) {
-                agentRow.status = 'ok';
-                agentRow.verb = `${option.label} ${detectedVer} detected`;
-                agentRow.detail = detectedVer;
-            }
-            else {
-                agentRow.status = 'pending';
-                agentRow.verb = pendingVerbForAgent(req.agentId);
-                delete agentRow.detail;
-            }
-            // Login state never carries across agents.
-            this.clearRowError(loginRow);
-            const loginReady = agentRow.status === 'ok' && this.probeAgentReady(req.agentId).ok;
-            if (loginReady) {
-                loginRow.status = 'ok';
-                loginRow.verb = 'Signed in (verified)';
-            }
-            else {
-                loginRow.status = 'pending';
-                loginRow.verb = "you'll sign in after install";
-            }
-        }
-        else {
-            // Same agent re-selected — only normalize verbs if rows were not yet ok.
-            if (agentRow.status !== 'ok') {
-                agentRow.verb = pendingVerbForAgent(req.agentId);
-                this.clearRowError(agentRow);
-                agentRow.status = 'pending';
-            }
-            if (loginRow.status !== 'ok') {
-                loginRow.verb = "you'll sign in after install";
-                loginRow.status = 'pending';
-            }
-        }
+        this.updateAgentSummaryRow();
         this.persist();
         appendInstallLog(`agent-changed ${req.agentId}`);
         return this.respond(`Selected ${option.label}.`, true);
@@ -690,29 +607,26 @@ class FirstRunSessionService {
     /**
      * Start the Hub server for the chosen project and open the user's browser
      * to it. Returns the Hub URL so the client can show a clear "we're at <url>"
-     * message instead of a CLI hand-off — the whole point of v1 is to never
+     * message instead of a CLI hand-off — the whole point of v1 is to never
      * leave the user typing a command. The single-file launcher binary in v2
      * (#355) replaces this in-process spawn with a durable tray-icon launcher.
      */
     async openHub() {
-        if (!this.state.workspacePath) {
-            return { ok: false, message: 'Pick a project folder before opening the Hub.' };
-        }
         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/' };
+            // 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' };
         }
         try {
             const { AiHubServer, findAvailablePort } = await Promise.resolve().then(() => __importStar(require('../ai-hub/server')));
             const port = await findAvailablePort(43091);
             const hubServer = new AiHubServer({ projectPath: this.state.workspacePath });
             await hubServer.start(port);
-            const hubUrl = `http://127.0.0.1:${port}/ai-hub/`;
+            const hubUrl = `http://127.0.0.1:${port}/ai-hub/?firstRun=true`;
             this.openBrowser(hubUrl);
             appendInstallLog(`hub-opened ${hubUrl}`);
             return {
                 ok: true,
-                message: `Hub is open at ${hubUrl}. From now on, run \`npx fraim-framework@latest hub --browser\` to launch it again — the standalone launcher binary ships in v2 (#355).`,
+                message: `Hub is open at ${hubUrl}. From now on, run \`npx fraim-framework@latest hub --browser\` to launch it again — the standalone launcher binary ships in v2 (#355).`,
                 hubUrl,
             };
         }
@@ -728,7 +642,11 @@ class FirstRunSessionService {
     openBrowser(url) {
         try {
             if (process.platform === 'win32') {
-                (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" "${url}"`], { detached: true, stdio: 'ignore' }).unref();
+                // `cmd.exe /c start "" "<url>"` mis-parses on some Windows hosts
+                // (cmd interprets the URL's `//` as a UNC path -> "Windows cannot
+                // find" popup). rundll32 + url.dll,FileProtocolHandler is the
+                // documented protocol-handler entry point and bypasses cmd entirely.
+                (0, child_process_1.spawn)('rundll32', ['url.dll,FileProtocolHandler', url], { detached: true, stdio: 'ignore' }).unref();
                 return;
             }
             if (process.platform === 'darwin') {
@@ -738,7 +656,7 @@ class FirstRunSessionService {
             (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
         }
         catch {
-            // Best-effort — fall through; the URL is already in the response so the
+            // Best-effort — fall through; the URL is already in the response so the
             // client surfaces it for the user.
         }
     }