fraim-framework 2.0.126 → 2.0.128

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

@@ -0,0 +1,746 @@
+"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.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"));
+const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
+const ide_detector_1 = require("../cli/setup/ide-detector");
+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; } });
+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'
+        ? ['/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) {
+    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 });
+}
+function getNextPromptPath() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install', 'next-prompt.txt');
+}
+function getInstallLogPath() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'install-log.txt');
+}
+function appendInstallLog(line) {
+    ensureOutputDirs();
+    fs_1.default.appendFileSync(getInstallLogPath(), `[${new Date().toISOString()}] ${line}${os_1.default.EOL}`);
+}
+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}`;
+}
+class FirstRunSessionService {
+    constructor(options) {
+        this.key = options.key;
+        this.headless = options.headless === true;
+        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);
+            (0, install_state_1.saveFirstRunState)(this.state);
+        }
+    }
+    persist() {
+        (0, install_state_1.saveFirstRunState)(this.state);
+    }
+    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) {
+        row.status = 'error';
+        row.verb = 'failed — see below';
+        row.errorFrame = { whatTried, whatHappened, actions };
+    }
+    detectRowsOnLoad() {
+        if (this.fakeMode) {
+            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() {
+        this.detectRowsOnLoad();
+        this.persist();
+        return {
+            state: this.state,
+            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,
+        };
+    }
+    respond(message, ok) {
+        return {
+            ok,
+            message,
+            state: this.state,
+            rows: this.state.rows,
+            primaryButtonLabel: (0, types_1.derivePrimaryButtonLabel)(this.state.rows),
+        };
+    }
+    /**
+     * 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);
+        }
+        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);
+            }
+        }
+        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 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 });
+        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);
+            }
+        }
+        this.state.workspacePath = resolvedPath;
+        row.status = 'ok';
+        row.verb = resolvedPath;
+        this.persist();
+        appendInstallLog(`project-initialized ${resolvedPath}`);
+        return this.respond(`Initialized FRAIM in ${resolvedPath}.`, true);
+    }
+    /**
+     * 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);
+        }
+        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;
+            }
+            // 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.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.persist();
+        appendInstallLog('finish prompt-written');
+        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') {
+                (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" "${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;