fraim-framework 2.0.127 → 2.0.129

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

@@ -1,9 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirstRunSessionService = void 0;
+exports.FIRST_RUN_ROW_IDS = exports.FirstRunSessionService = void 0;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
@@ -15,7 +48,17 @@ 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; } });
 const install_state_1 = require("./install-state");
+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') {
+        return explicit;
+    }
+    return 'default';
+}
 function commandExists(command) {
     const executable = process.platform === 'win32' ? 'cmd.exe' : command;
     const args = process.platform === 'win32'
@@ -28,6 +71,20 @@ function commandExists(command) {
     });
     return result.status === 0;
 }
+function commandVersion(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',
+        timeout: 5000,
+    });
+    if (result.status !== 0)
+        return null;
+    const text = `${result.stdout || ''}${result.stderr || ''}`.split(/\r?\n/)[0]?.trim() || null;
+    return text;
+}
 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 });
@@ -42,261 +99,675 @@ function appendInstallLog(line) {
     ensureOutputDirs();
     fs_1.default.appendFileSync(getInstallLogPath(), `[${new Date().toISOString()}] ${line}${os_1.default.EOL}`);
 }
-function getLaunchInstruction(agentId, projectRoot) {
-    const cwd = projectRoot || process.cwd();
-    switch (agentId) {
-        case 'claude-code':
-            return `cd "${cwd}" && claude`;
-        case 'codex':
-            return `cd "${cwd}" && codex`;
-        case 'gemini-cli':
-            return `cd "${cwd}" && gemini`;
-        default:
-            return `cd "${cwd}"`;
-    }
-}
-function maybeLaunchInteractiveShell(agentId, projectRoot) {
-    const commandLine = getLaunchInstruction(agentId, projectRoot);
-    try {
-        if (process.platform === 'win32') {
-            (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" cmd /k ${commandLine}`], {
-                detached: true,
-                stdio: 'ignore',
-            }).unref();
-            return true;
-        }
-        if (process.platform === 'darwin') {
-            (0, child_process_1.spawn)('open', ['-a', 'Terminal', projectRoot], {
-                detached: true,
-                stdio: 'ignore',
-            }).unref();
-            return true;
-        }
-        (0, child_process_1.spawn)('x-terminal-emulator', ['-e', 'bash', '-lc', commandLine], {
-            detached: true,
-            stdio: 'ignore',
-        }).unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
+function findAgentOption(agentId) {
+    return types_1.FIRST_RUN_AGENT_OPTIONS.find((option) => option.id === agentId);
 }
-function probeCodex(projectRoot) {
-    const result = (0, child_process_1.spawnSync)('codex', ['exec', '--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox'], {
-        cwd: projectRoot,
-        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 };
-}
-function probeClaude(projectRoot) {
-    const result = (0, child_process_1.spawnSync)('claude', ['-p', '--verbose', '--output-format', 'stream-json', '--dangerously-skip-permissions'], {
-        cwd: projectRoot,
-        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 };
-}
-function probeGemini(projectRoot) {
-    const result = (0, child_process_1.spawnSync)('gemini', ['--help'], {
-        cwd: projectRoot,
-        encoding: 'utf8',
-        timeout: 30000,
-    });
-    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-    return {
-        ok: result.status === 0,
-        output: output || 'Gemini CLI responded to --help; runtime FRAIM probe still requires manual confirmation.',
-    };
+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}`;
 }
 class FirstRunSessionService {
     constructor(options) {
         this.key = options.key;
         this.headless = options.headless === true;
-        this.fakeMode = process.env.FRAIM_FIRST_RUN_FAKE === '1';
+        this.fakeMode = getFakeStateMode();
+        this.fakeStderr =
+            process.env.FRAIM_FIRST_RUN_FAKE_STDERR ??
+                ['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);
         if (options.projectRoot) {
             this.state.workspacePath = path_1.default.resolve(options.projectRoot);
-            this.state.stepStates.project = 'running';
             (0, install_state_1.saveFirstRunState)(this.state);
         }
     }
     persist() {
         (0, install_state_1.saveFirstRunState)(this.state);
     }
-    markStep(step, status) {
-        this.state.stepStates[step] = status;
-        this.persist();
+    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`);
+        }
+        return row;
+    }
+    clearRowError(row) {
+        delete row.errorFrame;
+        delete row.streamOutput;
+    }
+    setRowError(row, whatTried, whatHappened, actions, hint) {
+        row.status = 'error';
+        row.verb = 'failed — see below';
+        row.errorFrame = { whatTried, whatHappened, actions, ...(hint ? { hint } : {}) };
     }
-    detectAgents() {
+    /**
+     * 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) {
-            return types_1.FIRST_RUN_AGENT_OPTIONS.map((agent) => ({
-                id: agent.id,
-                label: agent.label,
-                detected: true,
-                detail: 'Fake test-mode agent available.',
-            }));
-        }
-        const detected = (0, ide_detector_1.detectInstalledIDEs)();
-        return types_1.FIRST_RUN_AGENT_OPTIONS.map((agent) => {
-            const ide = detected.find((entry) => entry.aliases?.some((alias) => agent.detectAliases.includes(alias)) ||
-                agent.detectAliases.some((alias) => entry.name.toLowerCase().includes(alias)));
-            return {
-                id: agent.id,
-                label: agent.label,
-                detected: Boolean(ide) || commandExists(agent.launchCommand),
-                detail: ide ? `Config path: ${ide.configPath}` : 'CLI/config not detected yet.',
-            };
-        });
+            this.applyFakeStateOnLoad(this.fakeMode);
+            return;
+        }
+        // Real detection — populate row statuses from `command -v` style probes.
+        const nodeRow = this.getRow('node');
+        const nodeVer = commandVersion('node');
+        if (nodeVer) {
+            nodeRow.status = 'ok';
+            nodeRow.verb = `${nodeVer} detected`;
+        }
+        else {
+            nodeRow.status = 'pending';
+            nodeRow.verb = "we'll install";
+        }
+        const gitRow = this.getRow('git');
+        const gitVer = commandVersion('git');
+        if (gitVer) {
+            gitRow.status = 'ok';
+            gitRow.verb = `${gitVer} detected`;
+        }
+        else {
+            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;
+        }
+        else {
+            projectRow.status = 'manual-required';
+            projectRow.verb = 'pick a folder where FRAIM should work';
+        }
+    }
+    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 };
+            }
+        }
+        return null;
+    }
+    applyFakeStateOnLoad(mode) {
+        const setStatus = (rowId, status, verb, detail) => {
+            const row = this.getRow(rowId);
+            row.status = status;
+            row.verb = verb;
+            if (detail !== undefined)
+                row.detail = detail;
+        };
+        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');
+            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');
+            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');
+            return;
+        }
+        // 'default' fake mode — everything ok, project still requires a pick.
+        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');
     }
     getRequestToken() {
         return this.requestToken;
     }
     getSession() {
-        const agents = this.detectAgents();
-        this.state.detectedAgents = agents.filter((agent) => agent.detected).map((agent) => agent.id);
+        this.detectRowsOnLoad();
         this.persist();
         return {
             state: this.state,
-            agents,
+            rows: this.state.rows,
+            primaryButtonLabel: (0, types_1.derivePrimaryButtonLabel)(this.state.rows),
             prompt: types_1.FIRST_RUN_PROMPT,
             headless: this.headless,
             requestToken: this.requestToken,
+            agentOptions: types_1.FIRST_RUN_AGENT_OPTIONS,
+            currentAgentId: this.state.agentId,
         };
     }
-    runPrereqChecks() {
-        this.markStep('prereqs', 'running');
-        const checks = [
-            { label: 'node', ok: commandExists('node') },
-            { label: 'npx', ok: commandExists('npx') },
-            { label: 'git', ok: commandExists('git') },
-        ];
-        const failures = checks.filter((check) => !check.ok).map((check) => check.label);
-        const message = failures.length === 0
-            ? 'Node.js, npx, and git are available.'
-            : `Missing prerequisites: ${failures.join(', ')}.`;
-        appendInstallLog(`prereq-check ${message}`);
-        this.markStep('prereqs', failures.length === 0 ? 'complete' : 'failed');
-        if (failures.length === 0) {
-            this.markStep('agent', 'running');
-        }
-        return { ok: failures.length === 0, message, state: this.state };
-    }
-    selectAgent(agentId) {
-        this.state.selectedAgentId = agentId;
-        this.markStep('agent', 'complete');
-        this.markStep('configure', 'running');
-        appendInstallLog(`agent-selected ${agentId}`);
+    respond(message, ok) {
         return {
-            ok: true,
-            message: `Selected ${types_1.FIRST_RUN_AGENT_OPTIONS.find((agent) => agent.id === agentId)?.label || agentId}.`,
+            ok,
+            message,
             state: this.state,
-            launchCommand: types_1.FIRST_RUN_AGENT_OPTIONS.find((agent) => agent.id === agentId)?.loginCommand,
+            rows: this.state.rows,
+            primaryButtonLabel: (0, types_1.derivePrimaryButtonLabel)(this.state.rows),
         };
     }
-    async configureFraim() {
-        this.markStep('configure', 'running');
-        (0, setup_1.saveGlobalConfig)(this.key, 'conversational', {}, {});
-        if (!this.fakeMode) {
-            const selectedAgent = this.state.selectedAgentId ? (0, ide_detector_1.findIDEByName)(this.state.selectedAgentId) : undefined;
-            const targetNames = selectedAgent ? [selectedAgent.name] : undefined;
-            await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, {}, targetNames, {});
-            this.state.configuredAgents = this.detectAgents().filter((agent) => agent.detected).map((agent) => agent.id);
+    /**
+     * Run a single row to completion (or to its next stable state). Idempotent.
+     * The client calls this for each row that is `pending`, in the canonical
+     * order, until every row is `ok` or surfaces an error.
+     */
+    async runRow(rowId, request = {}) {
+        const row = this.getRow(rowId);
+        if (row.status === 'ok') {
+            return this.respond(`${row.label} already ready.`, true);
         }
-        else {
-            this.state.configuredAgents = this.state.selectedAgentId ? [this.state.selectedAgentId] : [];
+        this.clearRowError(row);
+        row.status = 'in-progress';
+        this.persist();
+        appendInstallLog(`row-run start ${rowId} status=${row.status}`);
+        try {
+            switch (rowId) {
+                case 'node':
+                    return await this.runNodeRow();
+                case 'git':
+                    return await this.runGitRow();
+                case 'agent':
+                    return await this.runAgentRow(request);
+                case 'agent-login':
+                    return await this.runAgentLoginRow(request);
+                case 'project':
+                    return await this.runProjectRow(request);
+            }
         }
-        appendInstallLog(`configure configuredAgents=${this.state.configuredAgents.join(',')}`);
-        this.markStep('configure', 'complete');
-        this.markStep('project', 'running');
-        return {
-            ok: true,
-            message: 'Saved FRAIM global configuration and wrote agent config where available.',
-            state: this.state,
-        };
+        catch (error) {
+            // 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
+            // letting the request return an opaque 500. Skip is included so the
+            // 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.errorFrame = {
+                whatTried: `Running ${row.label} step`,
+                whatHappened: message,
+                actions: [
+                    { id: 'retry', label: 'Retry', variant: 'primary' },
+                    { id: 'skip', label: 'Skip and continue', variant: 'ghost' },
+                ],
+            };
+            this.persist();
+            return this.respond(`Row ${rowId} failed: ${message}`, false);
+        }
+    }
+    async runNodeRow() {
+        const row = this.getRow('node');
+        // Node is bootstrapped by the install template before the wizard starts.
+        // If node is missing here something is severely wrong; fall through to error.
+        const ver = commandVersion('node');
+        if (ver) {
+            row.status = 'ok';
+            row.verb = `${ver} installed`;
+            this.persist();
+            return this.respond(`Node detected (${ver}).`, true);
+        }
+        if (this.fakeMode) {
+            row.status = 'ok';
+            row.verb = 'v20.11.1 installed';
+            this.persist();
+            return this.respond('Fake-mode node ok.', true);
+        }
+        this.setRowError(row, 'Verifying Node.js installation', 'node --version returned a non-zero exit code or no output.\n\nThe installer template is expected to have bootstrapped Node before launching first-run.', [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
+        this.persist();
+        return this.respond('Node not detected.', false);
+    }
+    async runGitRow() {
+        const row = this.getRow('git');
+        const ver = commandVersion('git');
+        if (ver) {
+            row.status = 'ok';
+            row.verb = `${ver} installed`;
+            this.persist();
+            return this.respond(`git detected (${ver}).`, true);
+        }
+        if (this.fakeMode) {
+            row.status = 'ok';
+            row.verb = 'git version 2.45 installed';
+            this.persist();
+            return this.respond('Fake-mode git ok.', true);
+        }
+        this.setRowError(row, 'Verifying git installation', 'git --version returned a non-zero exit code or no output.\n\nOn macOS, run `xcode-select --install` to install the Command Line Developer Tools, then retry. On Windows, install Git for Windows from https://git-scm.com/download/win.', [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
+        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);
+        }
+        if (this.fakeMode) {
+            row.status = 'ok';
+            row.verb = `${option.label} installed (fake-mode)`;
+            this.persist();
+            return this.respond('Fake-mode agent installed.', true);
+        }
+        // Real path: detect first — if already installed we skip install entirely.
+        const existingVer = commandVersion(option.launchCommand);
+        if (existingVer) {
+            row.status = 'ok';
+            row.verb = `${option.label} ${existingVer} detected`;
+            row.detail = existingVer;
+            this.persist();
+            return this.respond(`${option.label} already installed.`, 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;
+            this.persist();
+            return this.respond(`${option.label} installed.`, true);
+        }
+        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 initializeProject(projectPath, initializeGit = true) {
+    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.
+        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';
+            this.persist();
+            return this.respond('Project path required.', false);
+        }
         const resolvedPath = path_1.default.resolve(projectPath);
         fs_1.default.mkdirSync(resolvedPath, { recursive: true });
-        this.markStep('project', 'running');
-        if (initializeGit && commandExists('git')) {
+        if (commandExists('git')) {
             try {
                 (0, child_process_1.execSync)('git rev-parse --git-dir', { cwd: resolvedPath, stdio: 'ignore' });
             }
             catch {
-                (0, child_process_1.execSync)('git init', { cwd: resolvedPath, stdio: 'ignore' });
+                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; the hint
+                // translates the verbatim error (e.g. "Request failed with
+                // status code 401") into something a non-tech user can act on.
+                const hint = this.classifyInitError(detail);
+                this.setRowError(row, `Initializing FRAIM in ${resolvedPath}`, detail, [{ id: 'retry', label: 'Retry', variant: 'primary' }], hint);
+                appendInstallLog(`project-init-failed ${resolvedPath}: ${detail}`);
+                this.persist();
+                return this.respond(`Initialization failed: ${detail}`, false);
             }
         }
-        await (0, init_project_1.runInitProject)({ projectRoot: resolvedPath });
         this.state.workspacePath = resolvedPath;
-        this.markStep('project', 'complete');
-        this.markStep('launch', 'running');
+        row.status = 'ok';
+        row.verb = resolvedPath;
+        this.persist();
         appendInstallLog(`project-initialized ${resolvedPath}`);
-        return {
-            ok: true,
-            message: `Initialized FRAIM in ${resolvedPath}.`,
-            state: this.state,
-        };
+        return this.respond(`Initialized FRAIM in ${resolvedPath}.`, true);
     }
-    launchAndProbe() {
-        const agentId = this.state.selectedAgentId;
-        const projectRoot = this.state.workspacePath;
-        if (!agentId || !projectRoot) {
-            this.markStep('launch', 'failed');
-            return {
-                ok: false,
-                message: 'Select an agent and project folder before launch.',
-                state: this.state,
-            };
+    /**
+     * Update the current agent selection (inline `Change…` picker). Recomputes
+     * the agent and agent-login row verbs but 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.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`;
+            this.persist();
+            appendInstallLog(`custom-agent recorded ${req.customAgent.name}`);
+            return this.respond(`Custom agent "${req.customAgent.name}" recorded.`, true);
         }
-        const launchCommand = getLaunchInstruction(agentId, projectRoot);
-        const opened = this.fakeMode ? true : maybeLaunchInteractiveShell(agentId, projectRoot);
-        let probeResult = { ok: true, output: 'Fake test-mode launch succeeded.' };
-        if (!this.fakeMode) {
-            if (agentId === 'codex') {
-                probeResult = probeCodex(projectRoot);
+        if (!req.agentId) {
+            return this.respond('agentId or customAgent required.', false);
+        }
+        const option = findAgentOption(req.agentId);
+        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;
             }
-            else if (agentId === 'claude-code') {
-                probeResult = probeClaude(projectRoot);
+            // 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 {
-                probeResult = probeGemini(projectRoot);
+                loginRow.status = 'pending';
+                loginRow.verb = "you'll sign in after install";
             }
         }
-        this.state.lastLaunchCommand = launchCommand;
-        this.state.lastProbeMessage = probeResult.output;
-        this.markStep('launch', probeResult.ok ? 'complete' : 'failed');
-        if (probeResult.ok) {
-            this.markStep('finish', 'running');
+        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';
+            }
         }
-        appendInstallLog(`launch agent=${agentId} opened=${opened} probeOk=${probeResult.ok}`);
-        return {
-            ok: probeResult.ok,
-            message: opened
-                ? 'Agent launch was attempted and the probe completed.'
-                : 'Agent launch could not be opened automatically; use the provided command and review the probe output.',
-            state: this.state,
-            launchCommand,
-            output: probeResult.output,
-        };
+        this.persist();
+        appendInstallLog(`agent-changed ${req.agentId}`);
+        return this.respond(`Selected ${option.label}.`, true);
     }
     finish() {
         ensureOutputDirs();
         fs_1.default.writeFileSync(getNextPromptPath(), `${types_1.FIRST_RUN_PROMPT}${os_1.default.EOL}`, 'utf8');
         this.state.nextPrompt = types_1.FIRST_RUN_PROMPT;
-        this.markStep('finish', 'complete');
+        this.persist();
         appendInstallLog('finish prompt-written');
-        return {
-            ok: true,
-            message: 'Wrote the next prompt artifact and completed first-run.',
-            state: this.state,
-        };
+        return this.respond('Wrote the next prompt artifact and completed first-run.', true);
+    }
+    /**
+     * 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
+     * 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/' };
+        }
+        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/`;
+            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).`,
+                hubUrl,
+            };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'Unknown error';
+            appendInstallLog(`hub-open-failed ${detail}`);
+            return {
+                ok: false,
+                message: `Could not open the Hub automatically: ${detail}. Run \`npx fraim-framework@latest hub --browser\` from a terminal to open it manually.`,
+            };
+        }
+    }
+    openBrowser(url) {
+        try {
+            if (process.platform === 'win32') {
+                // `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') {
+                (0, child_process_1.spawn)('open', [url], { detached: true, stdio: 'ignore' }).unref();
+                return;
+            }
+            (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
+            // client surfaces it for the user.
+        }
     }
 }
 exports.FirstRunSessionService = FirstRunSessionService;