fraim 2.0.326 → 2.0.328

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

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installManagedAgent = installManagedAgent;
 const fs_1 = __importDefault(require("fs"));
+const persist_shell_path_1 = require("./persist-shell-path");
 const path_1 = __importDefault(require("path"));
 const managed_agent_paths_1 = require("./managed-agent-paths");
 function errorMessage(error) {
@@ -104,7 +105,9 @@ async function runInstallWithStaleCleanupRetry(option, prefix, runInstall) {
 // check before invoking this — it only covers the install-then-fallback path.
 async function installManagedAgent(option, systemPath, deps) {
     let standardInstallError = null;
-    const prefix = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    const portableBin = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    // npm writes Windows shims at the prefix root, but POSIX executables in prefix/bin.
+    const prefix = process.platform === 'win32' ? portableBin : path_1.default.dirname(portableBin);
     try {
         await deps.runProcess('npm', ['install', '-g', option.installPackage], {
             PATH: systemPath,
@@ -145,5 +148,6 @@ async function installManagedAgent(option, systemPath, deps) {
     if (!ver) {
         throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH. Standard install failure: ${standardInstallError}`);
     }
+    (0, persist_shell_path_1.persistShellPath)();
     return { outcome: 'managed' };
 }

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

@@ -36,12 +36,12 @@ Object.defineProperty(exports, "resolveMachinePathCached", { enumerable: true, g
 function getManagedNodeRoot() {
     return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
 }
-function getPortableNodeBinPath() {
+function getPortableNodeBinPath(platform = process.platform, arch = process.arch) {
     const nodeRoot = getManagedNodeRoot();
-    if (process.platform === 'win32') {
+    if (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'))
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('node-v') && !entry.name.includes('.staging-'))
                 .sort((a, b) => b.name.localeCompare(a.name))[0];
             if (extractedDir) {
                 return path_1.default.join(nodeRoot, extractedDir.name);
@@ -49,6 +49,17 @@ function getPortableNodeBinPath() {
         }
         return nodeRoot;
     }
+    if (fs_1.default.existsSync(nodeRoot)) {
+        const versioned = fs_1.default.readdirSync(nodeRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && /^node-v\d+\.\d+\.\d+-/.test(entry.name)
+            && entry.name.endsWith(`-${platform}-${arch}`))
+            .sort((a, b) => b.name.localeCompare(a.name, undefined, { numeric: true }));
+        for (const entry of versioned) {
+            const bin = path_1.default.join(nodeRoot, entry.name, 'bin');
+            if (fs_1.default.existsSync(path_1.default.join(bin, 'node')) && fs_1.default.existsSync(path_1.default.join(bin, 'npm')))
+                return bin;
+        }
+    }
     return path_1.default.join(nodeRoot, 'bin');
 }
 function getManagedAgentBinDirs() {

package/dist/src/cli/utils/managed-node-runtime.js

@@ -17,16 +17,11 @@ const path_1 = __importDefault(require("path"));
 const https_1 = __importDefault(require("https"));
 const crypto_1 = __importDefault(require("crypto"));
 const managed_agent_paths_1 = require("./managed-agent-paths");
-// Issue #1415 (extended): a genuinely GUI-only FRAIM Hub install — the native installer
-// downloaded from the website, never a CLI — has no working `npm`/`npx` anywhere. First-run's
-// `embeddedDesktop` branch (session-service.ts) deliberately skips installing one (it only needs
-// Electron's own bundled Node for FRAIM's own CLI/MCP shim, via ELECTRON_RUN_AS_NODE), and the
-// separate CLI installer's portable-Node bootstrap (scripts/installer/fraim-install-win.template.cmd)
-// never runs for a desktop-only user. That left two features silently unable to do their real job
-// on such a machine: `hub-app-materializer.ts`'s npm install (this issue), and agent-CLI
-// installation (`managed-agent-install.ts`), which also shells out to a bare `npm`.
+// Desktop-only users may have no working system npm/npx. Installer setup, Hub
+// materialization, first-run setup, and agent installation share this managed
+// runtime resolver so each can prepare or reuse standalone Node and npm.
 //
-// This module is the one place that guarantees a real, usable `npm`/`node` exists, for both
+// This module is the one place that guarantees a real, usable `npm`/`node` exists for its
 // consumers: prefer whatever is already on system PATH (common for technical users), then an
 // already-downloaded managed runtime (shared with the CLI installer's `~/.fraim/node/` convention
 // via `managed-agent-paths.ts` — reused, not duplicated, so a user who has ever run the `fraim` CLI
@@ -65,11 +60,14 @@ function findExecutableOnPath(name, pathValue = process.env.PATH) {
 function hasWorkingNodeAndNpm(dir, platform = process.platform) {
     return fs_1.default.existsSync(path_1.default.join(dir, npmExecutableName(platform))) && fs_1.default.existsSync(path_1.default.join(dir, nodeExecutableName(platform)));
 }
-/** Whether `dir` (a specific versioned bin dir) holds a complete extraction for exactly `version`. */
+function nodeBinDir(root, platform) {
+    return platform === 'win32' ? root : path_1.default.join(root, 'bin');
+}
+/** Whether `dir` (a versioned distribution root) holds a complete extraction for `version`. */
 function isManagedNodeVersionComplete(dir, version, platform = process.platform) {
     try {
         const recorded = fs_1.default.readFileSync(path_1.default.join(dir, 'fraim-managed-node-version'), 'utf8').trim();
-        return recorded === version && hasWorkingNodeAndNpm(dir, platform);
+        return recorded === version && hasWorkingNodeAndNpm(nodeBinDir(dir, platform), platform);
     }
     catch {
         return false;
@@ -99,6 +97,9 @@ function assertPathSafeNodeVersion(version) {
 }
 /** The exact folder name Node's own official archive extracts as — also this module's versioned subfolder name under the shared `~/.fraim/node/` root. */
 function nodeVersionedDirName(request) {
+    if (!/^[a-z0-9_]+$/.test(request.arch)) {
+        throw new Error('Refusing to use an invalid managed Node.js architecture.');
+    }
     return `node-v${assertPathSafeNodeVersion(request.version)}-${nodePlatformName(request.platform)}-${request.arch}`;
 }
 function nodeArchiveFileName(request) {
@@ -203,15 +204,16 @@ const defaultExtractNodeArchive = async (archivePath, destDir, request) => {
 async function downloadAndPromoteVersionedNodeDir(args) {
     const { nodeRoot, request, downloadArchive, extractArchive } = args;
     const destDir = path_1.default.join(nodeRoot, nodeVersionedDirName(request));
-    const stagingDir = `${destDir}.staging-${process.pid}`;
     fs_1.default.mkdirSync(nodeRoot, { recursive: true });
-    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
     const archivePath = await downloadArchive(request);
+    let stagingDir;
     try {
+        // tar requires an existing cwd. Each invocation owns a separate directory,
+        // including simultaneous requests within the same process.
+        stagingDir = fs_1.default.mkdtempSync(`${destDir}.staging-${process.pid}-`);
         await extractArchive(archivePath, stagingDir, request);
-        // The archive's own top-level folder (matching nodeVersionedDirName) may land either as the
-        // extraction root itself (tar) or as one nested level inside it (some zip extractors preserve
-        // the archive's internal folder) — handle both without assuming either.
+        // Official tar and ZIP archives preserve their top-level distribution folder.
+        // Also accept a flattened root from a supplied extractor.
         const nestedCandidate = path_1.default.join(stagingDir, nodeVersionedDirName(request));
         const extractedRoot = fs_1.default.existsSync(nestedCandidate) ? nestedCandidate : stagingDir;
         fs_1.default.writeFileSync(path_1.default.join(extractedRoot, 'fraim-managed-node-version'), request.version, 'utf8');
@@ -233,9 +235,10 @@ async function downloadAndPromoteVersionedNodeDir(args) {
     }
     finally {
         fs_1.default.rmSync(archivePath, { force: true });
-        fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+        if (stagingDir)
+            fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
     }
-    return destDir;
+    return nodeBinDir(destDir, request.platform);
 }
 /**
  * Resolve a working `npm` executable, preferring (in order): system PATH, an already-downloaded
@@ -252,7 +255,7 @@ async function ensureManagedNpm(options = {}) {
     if (systemNpm) {
         return { npmPath: systemNpm, binDir: path_1.default.dirname(systemNpm), source: 'system' };
     }
-    const existingBinDir = (0, managed_agent_paths_1.getPortableNodeBinPath)();
+    const existingBinDir = (0, managed_agent_paths_1.getPortableNodeBinPath)(platform, arch);
     if (hasWorkingNodeAndNpm(existingBinDir, platform)) {
         return { npmPath: path_1.default.join(existingBinDir, npmExecutableName(platform)), binDir: existingBinDir, source: 'managed-existing' };
     }

package/dist/src/cli/utils/persist-shell-path.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPersistShellPathWindowsCommand = buildPersistShellPathWindowsCommand;
+exports.persistShellPath = persistShellPath;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const script_sync_utils_1 = require("./script-sync-utils");
+const managed_agent_paths_1 = require("./managed-agent-paths");
+// Issue #1285: pure command-string builder extracted from persistShellPath()
+// so the generated PowerShell command's directory order (the current
+// versioned dir added before the legacy flat dir, per `bins`' own order —
+// see getManagedAgentBinDirs()) can be asserted directly, without mutating
+// the real registry-backed Windows User PATH in a test.
+function buildPersistShellPathWindowsCommand(bins) {
+    const assignments = bins.map((entry, index) => `$bin${index} = '${entry.replace(/'/g, "''")}'`);
+    const removals = bins.map((_, index) => `$parts = @($parts | Where-Object { $_ -ne $bin${index} })`);
+    const additions = bins.map((_, index) => `$parts += $bin${index}`);
+    return [
+        `$ErrorActionPreference = 'Stop'`,
+        ...assignments,
+        `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+        `$parts = @($cur -split ';' | Where-Object { $_ })`,
+        ...removals,
+        ...additions,
+        `$cur = ($parts | Select-Object -Unique) -join ';'`,
+        `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
+    ].join('; ');
+}
+function persistShellPath() {
+    const marker = '# FRAIM managed binaries';
+    const legacyExportLine = 'export PATH=”$HOME/.fraim/node/bin:$PATH”';
+    // The stable CLI shim must outrank old prefix installs already on inherited PATH.
+    // Agent bins still follow the user's PATH, preserving system-agent precedence.
+    const bins = [path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'bin'), ...(0, managed_agent_paths_1.getManagedAgentBinDirs)()];
+    const shellBins = bins.map(bin => {
+        const relative = path_1.default.relative((0, script_sync_utils_1.getUserFraimDir)(), bin).split(path_1.default.sep).join('/');
+        return '$HOME/.fraim/' + relative.replace(/[\\"$`]/g, '\\$&');
+    });
+    const exportLine = `export PATH="${shellBins[0]}:$PATH:${shellBins.slice(1).join(':')}"`;
+    // Guard against editor-autocorrect curly-quote regression (issue #1688):
+    // U+201C/201D/2018/2019 in exportLine would be written verbatim to shell
+    // profiles and break PATH resolution for all pre-existing PATH entries.
+    if (/[“”‘’]/.test(exportLine)) {
+        throw new Error(`persistShellPath: exportLine contains curly quotes. Writing this to a shell profile would corrupt PATH resolution. Check for editor autocorrect in persist-shell-path.ts. Line: ${JSON.stringify(exportLine)}`);
+    }
+    const stanza = `\n${marker}\n${exportLine}\n`;
+    if (process.platform === 'win32') {
+        const psCmd = buildPersistShellPathWindowsCommand(bins);
+        // Issue #1692: a sandboxed test run (row detection on load, node row
+        // success, fraim row success all reach this function) must never write
+        // its temp fake-home bin dirs into the real, registry-backed Windows
+        // User PATH. FRAIM_TEST_SANDBOX is already the canonical "this process
+        // is a sandboxed test run" signal set by every test runner (see
+        // getUserFraimDirPath() in project-fraim-paths.ts) rather than a
+        // dedicated flag for this call site.
+        if (process.env.FRAIM_TEST_SANDBOX !== '1') {
+            const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8', timeout: 10000 });
+            if (result.error || result.status !== 0) {
+                throw new Error(`Could not register managed binaries on the User PATH: ${result.error?.message || result.stderr}`);
+            }
+        }
+        // Fall through to write POSIX profile files for Git Bash (VS Code
+        // integrated terminal, Claude Code, etc.) which do not inherit the
+        // Windows user PATH written above.
+    }
+    // Test runners isolate FRAIM_USER_DIR but may leave os.homedir() unchanged.
+    const sandboxDir = process.env.FRAIM_USER_DIR ? path_1.default.resolve(process.env.FRAIM_USER_DIR) : null;
+    const profileHome = process.env.FRAIM_TEST_SANDBOX === '1'
+        ? (sandboxDir && (path_1.default.basename(sandboxDir) === '.fraim' ? path_1.default.dirname(sandboxDir) : sandboxDir))
+        : os_1.default.homedir();
+    if (!profileHome)
+        return;
+    fs_1.default.mkdirSync(profileHome, { recursive: true });
+    const profiles = ['.zshrc', '.bash_profile', '.bashrc'].map(name => path_1.default.join(profileHome, name));
+    // 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');
+    }
+    // On Windows, Git Bash reads .bash_profile (login) and .bashrc (interactive).
+    // Neither is created by the OS or Git Bash installer, so create .bashrc if
+    // neither exists — otherwise the PATH entry is never written and Git Bash
+    // (VS Code integrated terminal, Claude Code) never sees managed node dirs.
+    if (process.platform !== 'darwin') {
+        const bashProfile = profiles[1]; // .bash_profile
+        const bashrc = profiles[2]; // .bashrc
+        if (!fs_1.default.existsSync(bashProfile) && !fs_1.default.existsSync(bashrc)) {
+            fs_1.default.writeFileSync(bashrc, stanza, 'utf8');
+        }
+    }
+    for (const profile of profiles) {
+        // .zshrc is macOS/Linux only; Git Bash on Windows uses .bash_profile/.bashrc.
+        if (process.platform === 'win32' && profile.endsWith('.zshrc'))
+            continue;
+        try {
+            if (!fs_1.default.existsSync(profile))
+                continue;
+            const content = fs_1.default.readFileSync(profile, 'utf8');
+            if (content.includes(legacyExportLine)) {
+                fs_1.default.writeFileSync(profile, content.replace(legacyExportLine, exportLine), 'utf8');
+                continue;
+            }
+            if (content.includes(marker)) {
+                if (!content.includes(exportLine)) {
+                    // Replace stale runtime directories or an older shim ordering.
+                    fs_1.default.writeFileSync(profile, content.replace(/export PATH=[\u201D"][^\u201D"]*\.fraim[^\u201D"]*[\u201D"]/, exportLine), 'utf8');
+                }
+                continue;
+            }
+            fs_1.default.appendFileSync(profile, stanza, 'utf8');
+        }
+        catch {
+            // Ignore unreadable or missing profiles.
+        }
+    }
+    (0, managed_agent_paths_1.invalidateMachinePathCache)();
+}

package/dist/src/core/utils/redact-secrets.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Credential redaction for log sinks (issue #1701, SEC-LEAK `63bc2c102800`).
+ *
+ * A FRAIM API key is a bearer credential: anything that writes one to a console,
+ * a log file, or a structured log record has disclosed it to everyone who can
+ * read that sink. Every log statement that wants to identify a caller must go
+ * through `redactApiKey` (for a known key) or `apiKeyRefFromRequest` (for an
+ * HTTP request) instead of interpolating the key itself.
+ *
+ * The reference is an unsalted SHA-256 prefix rather than a last-four suffix:
+ *   - it leaks no key material at all, where a suffix leaks 16 bits;
+ *   - it is stable, so the same caller correlates across the server log, the MCP
+ *     error log, and the local proxy's own log on the user's machine;
+ *   - it is unsalted deliberately, because the local proxy runs in a different
+ *     process from the server and must derive the same reference without sharing
+ *     a secret. Keys carry 128 bits of entropy (`generateApiKey` in
+ *     `src/fraim/db-service.ts`), so the digest is not brute-forceable.
+ *
+ * Fingerprinting every value, including one an unauthenticated caller supplied,
+ * also removes CRLF log-forging: no caller-controlled bytes reach a log line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_CREDENTIAL_REF = void 0;
+exports.redactApiKey = redactApiKey;
+exports.redactSecretsInText = redactSecretsInText;
+exports.apiKeyRefFromRequest = apiKeyRefFromRequest;
+const crypto_1 = require("crypto");
+/** Prefix every FRAIM-issued API key carries. */
+const FRAIM_KEY_PREFIX = 'fraim_';
+/** Hex characters kept from the digest. 48 bits: collision-free at any realistic key population. */
+const REFERENCE_HEX_CHARS = 12;
+/** What a log line shows when the request carried no credential at all. */
+exports.NO_CREDENTIAL_REF = 'key_none';
+/**
+ * A FRAIM key embedded in free-form text. Matched loosely on the character class
+ * so a truncated, uppercased, or future-format key is still caught.
+ */
+const EMBEDDED_FRAIM_KEY = /fraim_[A-Za-z0-9]{16,}/g;
+/**
+ * Non-reversible, stable reference for an API key, safe to write to any log sink.
+ * Returns `NO_CREDENTIAL_REF` when there is no credential to reference.
+ */
+function redactApiKey(value) {
+    if (typeof value !== 'string')
+        return exports.NO_CREDENTIAL_REF;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return exports.NO_CREDENTIAL_REF;
+    const digest = (0, crypto_1.createHash)('sha256').update(trimmed, 'utf8').digest('hex');
+    return `key_${digest.slice(0, REFERENCE_HEX_CHARS)}`;
+}
+/**
+ * Replace every credential-shaped value embedded in free-form text with its
+ * reference. Use on text that is logged but not authored here: request bodies,
+ * error messages, and stack traces. Idempotent.
+ */
+function redactSecretsInText(text) {
+    if (typeof text !== 'string' || !text.includes(FRAIM_KEY_PREFIX))
+        return text;
+    return text.replace(EMBEDDED_FRAIM_KEY, (match) => redactApiKey(match));
+}
+/**
+ * Reference for whichever credential a request carried, in precedence order:
+ * the value auth resolved, then the `x-api-key` header, then the `api-key` query
+ * parameter. The authenticated value wins so a forged header cannot rewrite the
+ * identity a log line reports.
+ *
+ * Shared by the request logger and the MCP error handler so both report the same
+ * reference for the same caller.
+ */
+function apiKeyRefFromRequest(req) {
+    if (!req)
+        return exports.NO_CREDENTIAL_REF;
+    const fromContext = req.apiKeyData?.key;
+    if (typeof fromContext === 'string' && fromContext.trim().length > 0) {
+        return redactApiKey(fromContext);
+    }
+    const headerValue = req.headers?.['x-api-key'];
+    const fromHeader = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (typeof fromHeader === 'string' && fromHeader.trim().length > 0) {
+        return redactApiKey(fromHeader);
+    }
+    const fromQuery = req.query?.['api-key'];
+    if (typeof fromQuery === 'string' && fromQuery.trim().length > 0) {
+        return redactApiKey(fromQuery);
+    }
+    return exports.NO_CREDENTIAL_REF;
+}

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

@@ -38,7 +38,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FIRST_RUN_ROW_IDS = exports.FirstRunSessionService = void 0;
 exports.commandVersion = commandVersion;
-exports.buildPersistShellPathWindowsCommand = buildPersistShellPathWindowsCommand;
 exports.buildFirstRunHubLaunchArgs = buildFirstRunHubLaunchArgs;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
@@ -52,6 +51,7 @@ const setup_1 = require("../cli/commands/setup");
 const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const persist_shell_path_1 = require("../cli/utils/persist-shell-path");
 const managed_agent_install_1 = require("../cli/utils/managed-agent-install");
 const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
 const types_1 = require("./types");
@@ -109,120 +109,6 @@ function ensureOutputDirs() {
         appendInstallLog(`orphaned-managed-shims-removed ${removedShims.join(', ')}`);
     }
 })();
-// Issue #1285: pure command-string builder extracted from persistShellPath()
-// so the generated PowerShell command's directory order (the current
-// versioned dir added before the legacy flat dir, per `bins`' own order —
-// see getManagedAgentBinDirs()) can be asserted directly, without mutating
-// the real registry-backed Windows User PATH in a test.
-function buildPersistShellPathWindowsCommand(bins) {
-    const assignments = bins.map((entry, index) => `$bin${index} = '${entry.replace(/'/g, "''")}'`);
-    const removals = bins.map((_, index) => `$parts = @($parts | Where-Object { $_ -ne $bin${index} })`);
-    const additions = bins.map((_, index) => `$parts += $bin${index}`);
-    return [
-        ...assignments,
-        `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
-        `$parts = @($cur -split ';' | Where-Object { $_ })`,
-        ...removals,
-        ...additions,
-        `$cur = ($parts | Select-Object -Unique) -join ';'`,
-        `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
-    ].join('; ');
-}
-function persistShellPath(includePackagedFraimBin = false) {
-    const marker = '# FRAIM managed binaries';
-    const legacyExportLine = 'export PATH=”$HOME/.fraim/node/bin:$PATH”';
-    // On Windows/Git Bash: add both the flat dir (bare POSIX agent scripts npm
-    // generates) and the versioned node subdir (node.exe). $HOME in Git Bash
-    // resolves to the Windows home directory, matching the registry paths.
-    let exportLine;
-    if (process.platform === 'win32') {
-        const portableNodeBin = (0, managed_agent_paths_1.getPortableNodeBinPath)();
-        const nodeRoot = (0, managed_agent_paths_1.getManagedNodeRoot)();
-        const fraimBinEntry = includePackagedFraimBin ? ':$HOME/.fraim/bin' : '';
-        // Versioned dir first (has fresh installs, matches getManagedAgentBinDirs()
-        // order), flat dir second (retains bare POSIX agent scripts as fallback).
-        exportLine = portableNodeBin !== nodeRoot
-            ? `export PATH="$PATH:$HOME/.fraim/node/${path_1.default.basename(portableNodeBin)}:$HOME/.fraim/node${fraimBinEntry}"`
-            : `export PATH="$PATH:$HOME/.fraim/node${fraimBinEntry}"`;
-    }
-    else {
-        exportLine = includePackagedFraimBin
-            ? 'export PATH="$PATH:$HOME/.fraim/bin:$HOME/.fraim/node/bin"'
-            : 'export PATH="$PATH:$HOME/.fraim/node/bin"';
-    }
-    // Guard against editor-autocorrect curly-quote regression (issue #1688):
-    // U+201C/201D/2018/2019 in exportLine would be written verbatim to shell
-    // profiles and break PATH resolution for all pre-existing PATH entries.
-    if (/[“”‘’]/.test(exportLine)) {
-        throw new Error(`persistShellPath: exportLine contains curly quotes. Writing this to a shell profile would corrupt PATH resolution. Check for editor autocorrect in session-service.ts. Line: ${JSON.stringify(exportLine)}`);
-    }
-    const stanza = `\n${marker}\n${exportLine}\n`;
-    if (process.platform === 'win32') {
-        const bins = includePackagedFraimBin
-            ? [path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'bin'), ...(0, managed_agent_paths_1.getManagedAgentBinDirs)()]
-            : (0, managed_agent_paths_1.getManagedAgentBinDirs)();
-        const psCmd = buildPersistShellPathWindowsCommand(bins);
-        // Issue #1692: a sandboxed test run (row detection on load, node row
-        // success, fraim row success all reach this function) must never write
-        // its temp fake-home bin dirs into the real, registry-backed Windows
-        // User PATH. FRAIM_TEST_SANDBOX is already the canonical "this process
-        // is a sandboxed test run" signal set by every test runner (see
-        // getUserFraimDirPath() in project-fraim-paths.ts) rather than a
-        // dedicated flag for this call site.
-        if (process.env.FRAIM_TEST_SANDBOX !== '1') {
-            (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8' });
-        }
-        // Fall through to write POSIX profile files for Git Bash (VS Code
-        // integrated terminal, Claude Code, etc.) which do not inherit the
-        // Windows user PATH written above.
-    }
-    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');
-    }
-    // On Windows, Git Bash reads .bash_profile (login) and .bashrc (interactive).
-    // Neither is created by the OS or Git Bash installer, so create .bashrc if
-    // neither exists — otherwise the PATH entry is never written and Git Bash
-    // (VS Code integrated terminal, Claude Code) never sees managed node dirs.
-    if (process.platform === 'win32') {
-        const bashProfile = profiles[1]; // .bash_profile
-        const bashrc = profiles[2]; // .bashrc
-        if (!fs_1.default.existsSync(bashProfile) && !fs_1.default.existsSync(bashrc)) {
-            fs_1.default.writeFileSync(bashrc, stanza, 'utf8');
-        }
-    }
-    for (const profile of profiles) {
-        // .zshrc is macOS/Linux only; Git Bash on Windows uses .bash_profile/.bashrc.
-        if (process.platform === 'win32' && profile.endsWith('.zshrc'))
-            continue;
-        try {
-            if (!fs_1.default.existsSync(profile))
-                continue;
-            const content = fs_1.default.readFileSync(profile, 'utf8');
-            if (content.includes(legacyExportLine)) {
-                fs_1.default.writeFileSync(profile, content.replace(legacyExportLine, exportLine), 'utf8');
-                continue;
-            }
-            if (content.includes(marker)) {
-                if (!content.includes(exportLine)) {
-                    // Stale export line: versioned dir changed, includePackagedFraimBin
-                    // toggled, or platform-specific line was never written. Replace it.
-                    fs_1.default.writeFileSync(profile, content.replace(/export PATH=[\u201D"][^\u201D"]*\.fraim[^\u201D"]*[\u201D"]/, exportLine), 'utf8');
-                }
-                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');
 }
@@ -323,7 +209,7 @@ function buildFirstRunHubLaunchArgs() {
 class FirstRunSessionService {
     constructor(options) {
         // Issue #646: the key may be absent when first-run is launched by the macOS
-        // installer (.pkg) instead of `fraim first-run --key=…`. In that case the
+        // installer (.dmg) instead of `fraim first-run --key=…`. In that case the
         // wizard prompts the user to paste their key (see setKey / needsKey).
         this.key = options.key || '';
         this.headless = options.headless === true;
@@ -393,13 +279,15 @@ class FirstRunSessionService {
         // Real detection — populate row statuses from `command -v` style probes.
         const nodeRow = this.getRow('node');
         const nodeVer = this.embeddedDesktop ? process.version : commandVersion('node');
-        if (nodeVer) {
+        const embeddedLaunchersReady = !this.embeddedDesktop
+            || (fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) && fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)()));
+        if (nodeVer && embeddedLaunchersReady) {
             nodeRow.status = 'ok';
             nodeRow.verb = this.embeddedDesktop ? `${nodeVer} bundled with FRAIM` : `${nodeVer} detected`;
         }
         else {
             nodeRow.status = 'pending';
-            nodeRow.verb = "we'll install";
+            nodeRow.verb = this.embeddedDesktop ? 'installer repair required' : "we'll install";
         }
         const gitRow = this.getRow('git');
         const gitVer = commandVersion('git');
@@ -424,7 +312,7 @@ class FirstRunSessionService {
                 fraimRow.status = 'pending';
                 fraimRow.verb = "we'll configure your IDEs";
             }
-            persistShellPath(this.embeddedDesktop);
+            (0, persist_shell_path_1.persistShellPath)();
         }
         else {
             fraimRow.status = 'pending';
@@ -669,17 +557,22 @@ class FirstRunSessionService {
     async runNodeRow() {
         const row = this.getRow('node');
         if (this.embeddedDesktop) {
-            persistShellPath(this.embeddedDesktop);
+            if (!this.fakeMode && (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) || !fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)()))) {
+                this.setRowError(row, 'Checking the native installer setup', 'Stable FRAIM CLI/MCP launchers are missing. Re-run the native installer in repair mode.', [{ id: 'retry', label: 'Check again', variant: 'primary' }]);
+                this.persist();
+                return this.respond('FRAIM installer repair is required.', false);
+            }
+            (0, persist_shell_path_1.persistShellPath)();
             row.status = 'ok';
-            row.verb = `${process.version} bundled with FRAIM`;
+            row.verb = 'Node and FRAIM launchers ready';
             this.persist();
-            return this.respond(`FRAIM includes its own runtime (${process.version}).`, true);
+            return this.respond('FRAIM command-line tools are ready.', true);
         }
         // 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) {
-            persistShellPath(this.embeddedDesktop);
+            (0, persist_shell_path_1.persistShellPath)();
             row.status = 'ok';
             row.verb = `${ver} installed`;
             this.persist();
@@ -711,7 +604,7 @@ class FirstRunSessionService {
         this.persist();
         return this.respond('git not found — continuing without it. Install git later if you plan to do code delivery work.', true);
     }
-    async runFraimRow(forceConfigure = false) {
+    async runFraimRow() {
         const row = this.getRow('fraim');
         if (this.fakeMode) {
             row.status = 'ok';
@@ -737,24 +630,12 @@ class FirstRunSessionService {
             return this.respond('FRAIM configured.', true);
         }
         try {
-            if (this.embeddedDesktop) {
-                (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
-            }
-            else if (!forceConfigure && !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@latest'], { npm_config_prefix: prefix });
+            if (this.embeddedDesktop && (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) || !fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)()))) {
+                throw new Error('Stable FRAIM launchers are missing. Re-run the native installer in repair mode.');
             }
-            else if (forceConfigure && !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@latest'], { npm_config_prefix: prefix });
-            }
-            persistShellPath(this.embeddedDesktop);
+            if (!this.embeddedDesktop)
+                (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            (0, persist_shell_path_1.persistShellPath)();
             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));
@@ -1002,7 +883,7 @@ class FirstRunSessionService {
         fraimRow.verb = 'configuring FRAIM for local AI agents';
         this.persist();
         appendInstallLog(`agent-recruiting-complete ready=${readyCount}`);
-        return this.runFraimRow(true);
+        return this.runFraimRow();
     }
     openTerminalWithCommand(command) {
         if (process.platform === 'win32') {
@@ -1051,12 +932,11 @@ class FirstRunSessionService {
             };
         }
         if (this.embeddedDesktop) {
-            (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
-            if (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)())) {
+            if (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) || !fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)())) {
                 return {
                     ok: false,
                     needsAgentSetup: true,
-                    message: 'FRAIM CLI was not installed into the packaged desktop profile. Re-run FRAIM setup before opening Hub.',
+                    message: 'FRAIM CLI/MCP launchers are missing. Re-run the native installer in repair mode before opening Hub.',
                 };
             }
             appendInstallLog('hub-opened embedded-desktop');