fraim 2.0.325 → 2.0.327

package/dist/src/cli/commands/first-run.js

@@ -34,7 +34,7 @@ function openBrowser(url) {
 }
 const runFirstRun = async (options) => {
     // Issue #646: the key is optional. When launched by the no-terminal macOS
-    // installer (.pkg), no key is passed — the wizard prompts the user to paste it.
+    // installer (.dmg), no key is passed — the wizard prompts the user to paste it.
     const key = options.key || process.env.FRAIM_API_KEY || process.env.FRAIM_SETUP_KEY || process.env.FRAIM_INSTALL_KEY || '';
     const sessionService = new session_service_1.FirstRunSessionService({
         key,

package/dist/src/cli/doctor/checks/mcp-connectivity-checks.js

@@ -150,6 +150,22 @@ function diagnoseFraimMcpLaunchPlan(fraimServer, platform = process.platform, np
                 }
             };
         }
+        const shimSource = fs_1.default.readFileSync(command, 'utf8');
+        if (/ELECTRON_RUN_AS_NODE|app\.asar/i.test(shimSource)) {
+            return {
+                status: 'error',
+                message: 'FRAIM MCP config uses an obsolete Hub/Electron-routed stable shim',
+                suggestion: 'Run: fraim doctor --fix-mcp to replace it with the stable node/npx launcher',
+                details: {
+                    launchPlanSource: 'legacy-hub-routed-shim',
+                    phase: 'preflight',
+                    command,
+                    args,
+                    expectedCommand: fraimMcpShimPath,
+                    companionNpxShim: fraimNpxShimPath
+                }
+            };
+        }
         return {
             status: 'passed',
             message: 'FRAIM MCP config uses the stable FRAIM shim',

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -8,15 +8,12 @@ exports.getFraimMcpShimPath = getFraimMcpShimPath;
 exports.getFraimNpxShimPath = getFraimNpxShimPath;
 exports.getFraimCliShimPath = getFraimCliShimPath;
 exports.getPackagedFraimRuntimePath = getPackagedFraimRuntimePath;
-exports.getPackagedFraimRuntime = getPackagedFraimRuntime;
-exports.hasPackagedFraimRuntime = hasPackagedFraimRuntime;
 exports.ensureFraimMcpLatestLauncher = ensureFraimMcpLatestLauncher;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const windows_shim_path_search_1 = require("../../core/utils/windows-shim-path-search");
 const LAUNCHER_VERSION = 1;
-const PACKAGED_RUNTIME_VERSION = 1;
 const launcherSource = `#!/usr/bin/env node
 const fs = require('fs');
 const os = require('os');
@@ -32,7 +29,9 @@ const CACHE_ROOT = path.join(USER_DIR, 'npm-cache', 'mcp');
 const commandName = (name) => process.platform === 'win32' ? name + '.cmd' : name;
 const npmCommand = commandName('npm');
 const npxCommand = commandName('npx');
-const cliArgs = process.argv.slice(2).length > 0 ? process.argv.slice(2) : ['mcp'];
+const rawArgs = process.argv.slice(2);
+const cliMode = rawArgs[0] === '--fraim-cli';
+const cliArgs = cliMode ? rawArgs.slice(1) : (rawArgs.length > 0 ? rawArgs : ['mcp']);
 
 function quoteCmdArg(arg) {
   const value = String(arg);
@@ -133,75 +132,6 @@ function getFraimCliShimPath() {
 function getPackagedFraimRuntimePath() {
     return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'bin', 'packaged-fraim-runtime.json');
 }
-function runtimeFromEnv(env = process.env) {
-    return env.FRAIM_PACKAGED_CLI_EXECUTABLE && env.FRAIM_PACKAGED_CLI_SCRIPT
-        ? { executable: env.FRAIM_PACKAGED_CLI_EXECUTABLE, script: env.FRAIM_PACKAGED_CLI_SCRIPT }
-        : null;
-}
-// Regular Node.js (and ELECTRON_RUN_AS_NODE) cannot see inside Electron's
-// .asar archives. For paths like …/app.asar/node_modules/…, verify the
-// archive file itself rather than the internal entry.
-function existsOrAsarExists(filePath) {
-    const normalized = filePath.replace(/\\/g, '/');
-    const asarSep = normalized.indexOf('.asar/');
-    if (asarSep === -1)
-        return fs_1.default.existsSync(filePath);
-    return fs_1.default.existsSync(filePath.slice(0, asarSep + '.asar'.length));
-}
-function getPackagedFraimRuntime(env = process.env) {
-    const envRuntime = runtimeFromEnv(env);
-    if (envRuntime)
-        return envRuntime;
-    try {
-        const raw = JSON.parse(fs_1.default.readFileSync(getPackagedFraimRuntimePath(), 'utf8'));
-        if (!raw.executable || !raw.script)
-            return null;
-        if (!fs_1.default.existsSync(raw.executable) || !existsOrAsarExists(raw.script))
-            return null;
-        return { executable: raw.executable, script: raw.script };
-    }
-    catch {
-        return null;
-    }
-}
-function hasPackagedFraimRuntime(env = process.env) {
-    return getPackagedFraimRuntime(env) !== null;
-}
-function posixSingleQuote(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function windowsBatchPath(value) {
-    return value.replace(/%/g, '%%').replace(/"/g, '""');
-}
-function writePackagedRuntimeMetadata(runtime) {
-    writeFileIfChanged(getPackagedFraimRuntimePath(), JSON.stringify({
-        version: PACKAGED_RUNTIME_VERSION,
-        executable: runtime.executable,
-        script: runtime.script,
-        updatedAt: new Date().toISOString(),
-    }, null, 2) + '\n');
-}
-function packagedFraimShimSource(command, runtime) {
-    const { executable, script } = runtime;
-    const commandArg = command === 'mcp' ? ' mcp' : '';
-    if (process.platform === 'win32') {
-        return [
-            '@echo off',
-            'setlocal',
-            'set "ELECTRON_RUN_AS_NODE=1"',
-            `"${windowsBatchPath(executable)}" "${windowsBatchPath(script)}"${commandArg} %*`,
-            'exit /b %ERRORLEVEL%',
-            '',
-        ].join('\r\n');
-    }
-    return [
-        '#!/usr/bin/env sh',
-        'set -eu',
-        'export ELECTRON_RUN_AS_NODE=1',
-        `exec ${posixSingleQuote(executable)} ${posixSingleQuote(script)}${commandArg} "$@"`,
-        '',
-    ].join('\n');
-}
 const windowsFraimMcpShimSource = `@echo off
 setlocal
 for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
@@ -225,6 +155,9 @@ for /f "delims=" %%D in ('dir /b /ad /o-n "%FRAIM_USER_DIR_VALUE%\\node\\node-v*
 echo [fraim-mcp] Could not find node on PATH or in "%FRAIM_USER_DIR_VALUE%\\node" 1>&2
 exit /b 1
 `;
+const windowsFraimCliShimSource = windowsFraimMcpShimSource
+    .replace(/fraim-mcp-latest\.js" %\*/g, 'fraim-mcp-latest.js" --fraim-cli %*')
+    .replace(/\[fraim-mcp\]/g, '[fraim]');
 const windowsFraimNpxShimSource = `@echo off
 setlocal
 for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
@@ -246,47 +179,31 @@ for /f "delims=" %%D in ('dir /b /ad /o-n "%FRAIM_USER_DIR_VALUE%\\node\\node-v*
 echo [fraim-npx] Could not find npx on PATH or in "%FRAIM_USER_DIR_VALUE%\\node" 1>&2
 exit /b 1
 `;
-const posixFraimMcpShimSource = `#!/usr/bin/env sh
+function posixFraimShimSource(executable) {
+    const args = executable === 'node' ? '"$FRAIM_USER_DIR_VALUE/bin/fraim-mcp-latest.js" "$@"' : '"$@"';
+    const label = executable === 'node' ? 'fraim-mcp' : 'fraim-npx';
+    return `#!/usr/bin/env sh
 set -eu
 SHIM_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 FRAIM_USER_DIR_VALUE=$(dirname "$SHIM_DIR")
-LAUNCHER="$FRAIM_USER_DIR_VALUE/bin/fraim-mcp-latest.js"
 
-if command -v node >/dev/null 2>&1; then
-  exec node "$LAUNCHER" "$@"
+if command -v ${executable} >/dev/null 2>&1; then
+  exec ${executable} ${args}
 fi
-if [ -x "$FRAIM_USER_DIR_VALUE/node/bin/node" ]; then
-  PATH="$FRAIM_USER_DIR_VALUE/node/bin:$PATH"
-  export PATH
-  exec "$FRAIM_USER_DIR_VALUE/node/bin/node" "$LAUNCHER" "$@"
-fi
-if [ -x "$FRAIM_USER_DIR_VALUE/node/node" ]; then
-  PATH="$FRAIM_USER_DIR_VALUE/node:$PATH"
-  export PATH
-  exec "$FRAIM_USER_DIR_VALUE/node/node" "$LAUNCHER" "$@"
-fi
-
-echo "[fraim-mcp] Could not find node on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
-exit 1
-`;
-const posixFraimNpxShimSource = `#!/usr/bin/env sh
-set -eu
-SHIM_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-FRAIM_USER_DIR_VALUE=$(dirname "$SHIM_DIR")
-
-if command -v npx >/dev/null 2>&1; then
-  exec npx "$@"
-fi
-if [ -x "$FRAIM_USER_DIR_VALUE/node/bin/npx" ]; then
-  exec "$FRAIM_USER_DIR_VALUE/node/bin/npx" "$@"
-fi
-if [ -x "$FRAIM_USER_DIR_VALUE/node/npx" ]; then
-  exec "$FRAIM_USER_DIR_VALUE/node/npx" "$@"
-fi
-
-echo "[fraim-npx] Could not find npx on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
+# Match the generating host's distribution layout; staging and other architectures
+# cannot match this suffix. Legacy installs remain valid fallback locations.
+for NODE_BIN in "$FRAIM_USER_DIR_VALUE/node"/node-v*-${process.platform}-${process.arch}/bin "$FRAIM_USER_DIR_VALUE/node/bin" "$FRAIM_USER_DIR_VALUE/node"; do
+  if [ -x "$NODE_BIN/node" ] && [ -x "$NODE_BIN/${executable}" ]; then
+    PATH="$NODE_BIN:$PATH"
+    export PATH
+    exec "$NODE_BIN/${executable}" ${args}
+  fi
+done
+
+echo "[${label}] Could not find ${executable} on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
 exit 1
 `;
+}
 const writeFileIfChanged = (filePath, content, mode) => {
     if (!fs_1.default.existsSync(filePath) || fs_1.default.readFileSync(filePath, 'utf8') !== content) {
         fs_1.default.writeFileSync(filePath, content, 'utf8');
@@ -306,30 +223,14 @@ function ensureFraimMcpLatestLauncher() {
     fs_1.default.mkdirSync(launcherDir, { recursive: true });
     const fraimMcpShimPath = getFraimMcpShimPath();
     const fraimNpxShimPath = getFraimNpxShimPath();
-    const packagedRuntime = getPackagedFraimRuntime();
-    if (packagedRuntime) {
-        const fraimCliShimPath = getFraimCliShimPath();
-        if (runtimeFromEnv()) {
-            writePackagedRuntimeMetadata(packagedRuntime);
-        }
-        writeFileIfChanged(fraimMcpShimPath, packagedFraimShimSource('mcp', packagedRuntime), process.platform === 'win32' ? undefined : 0o755);
-        writeFileIfChanged(fraimCliShimPath, packagedFraimShimSource('cli', packagedRuntime), process.platform === 'win32' ? undefined : 0o755);
-        // Issue #1474: keep the npx companion shim in parity with the non-packaged branch below.
-        // The packaged fraim-mcp shim itself never invokes npx, but git/playwright base MCP servers
-        // (added later via the connect-mcp skill once a system npm is available) and doctor's
-        // launch-plan diagnostic both expect this file to exist alongside the stable fraim shim.
-        // Without it, doctor's "stable shim missing on disk" check could never be satisfied on a
-        // packaged install, and --fix-mcp/add-ide (which call this same function) could never fix it.
-        writeFileIfChanged(fraimNpxShimPath, process.platform === 'win32' ? windowsFraimNpxShimSource : posixFraimNpxShimSource, process.platform === 'win32' ? undefined : 0o755);
-        return {
-            command: fraimMcpShimPath,
-            args: [],
-            path: packagedRuntime.script,
-        };
-    }
+    const fraimCliShimPath = getFraimCliShimPath();
+    fs_1.default.rmSync(getPackagedFraimRuntimePath(), { force: true });
     writeFileIfChanged(launcherPath, launcherSource, process.platform === 'win32' ? undefined : 0o755);
-    writeFileIfChanged(fraimMcpShimPath, process.platform === 'win32' ? windowsFraimMcpShimSource : posixFraimMcpShimSource, process.platform === 'win32' ? undefined : 0o755);
-    writeFileIfChanged(fraimNpxShimPath, process.platform === 'win32' ? windowsFraimNpxShimSource : posixFraimNpxShimSource, process.platform === 'win32' ? undefined : 0o755);
+    writeFileIfChanged(fraimMcpShimPath, process.platform === 'win32' ? windowsFraimMcpShimSource : posixFraimShimSource('node'), process.platform === 'win32' ? undefined : 0o755);
+    writeFileIfChanged(fraimNpxShimPath, process.platform === 'win32' ? windowsFraimNpxShimSource : posixFraimShimSource('npx'), process.platform === 'win32' ? undefined : 0o755);
+    writeFileIfChanged(fraimCliShimPath, process.platform === 'win32' ? windowsFraimCliShimSource : posixFraimShimSource('node')
+        .replace(/fraim-mcp-latest\.js" "\$@"/g, 'fraim-mcp-latest.js" --fraim-cli "$@"')
+        .replace(/\[fraim-mcp\]/g, '[fraim]'), process.platform === 'win32' ? undefined : 0o755);
     return {
         command: fraimMcpShimPath,
         args: [],

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -56,12 +56,7 @@ exports.BASE_MCP_SERVERS = [
     }
 ];
 function activeBaseMCPServers() {
-    // The packaged desktop owns FRAIM's runtime but intentionally does not bundle
-    // npm. Keep third-party npx MCP servers out of fresh desktop-generated config;
-    // users can add them later through connect-mcp when a system npm is available.
-    return (0, fraim_mcp_latest_launcher_1.hasPackagedFraimRuntime)()
-        ? exports.BASE_MCP_SERVERS.filter((server) => server.id === 'fraim')
-        : exports.BASE_MCP_SERVERS;
+    return exports.BASE_MCP_SERVERS;
 }
 // ============================================================================
 // PROVIDER MCP SERVER BUILDER (uses provider registry)

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/core/fraim-config-schema.generated.js

@@ -627,6 +627,9 @@ exports.FRAIM_CONFIG_SCHEMA = {
                 },
                 "learning_usage": {
                     "kind": "number"
+                },
+                "hub_event_logs": {
+                    "kind": "number"
                 }
             }
         }
@@ -768,5 +771,6 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "artifact_retention_period.evidence",
     "artifact_retention_period.feedback",
     "artifact_retention_period.cleanup_manifests",
-    "artifact_retention_period.learning_usage"
+    "artifact_retention_period.learning_usage",
+    "artifact_retention_period.hub_event_logs"
 ];

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

@@ -323,7 +323,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 +393,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');
@@ -669,11 +671,16 @@ class FirstRunSessionService {
     async runNodeRow() {
         const row = this.getRow('node');
         if (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);
+            }
             persistShellPath(this.embeddedDesktop);
             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.
@@ -737,10 +744,10 @@ class FirstRunSessionService {
             return this.respond('FRAIM configured.', true);
         }
         try {
-            if (this.embeddedDesktop) {
-                (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            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')) {
+            else if (!this.embeddedDesktop && !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...';
@@ -1051,12 +1058,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');

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -8,6 +8,7 @@ exports.resolveArtifactRetentionConfig = resolveArtifactRetentionConfig;
 exports.runArtifactCleanup = runArtifactCleanup;
 exports.planArtifactCleanup = planArtifactCleanup;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
@@ -25,6 +26,7 @@ exports.ARTIFACT_RETENTION_CATEGORIES = [
     // deleted. Aggregate counters are never pruned; deleting them would misreport
     // history rather than minimise it.
     'learning_usage',
+    'hub_event_logs',
 ];
 function readWorkspaceConfig(workspaceRoot) {
     try {
@@ -69,7 +71,7 @@ function resolveArtifactRetentionConfig(workspaceRoot) {
     for (const category of exports.ARTIFACT_RETENTION_CATEGORIES) {
         values[category] = category in rawRetention
             ? parseRetentionValue(category, rawRetention[category], defaultValue, invalidValues)
-            : defaultValue;
+            : category === 'hub_event_logs' && !('default' in rawRetention) ? 7 : defaultValue;
     }
     return { values, defaultValue, invalidValues };
 }
@@ -172,7 +174,8 @@ function evidenceEligibilityDate(workspaceRoot, absolutePath, gitDates) {
     const relativePath = normalizeRelative(workspaceRoot, absolutePath);
     return gitDates.get(relativePath) ?? fileMtime(absolutePath);
 }
-function collectCandidates(workspaceRoot, activeUserEmail) {
+function collectCandidates(workspaceRoot, options) {
+    const { activeUserEmail } = options;
     const candidates = [];
     const add = (category, absolutePath, eligible, reason, eligibilityDate) => {
         candidates.push({
@@ -224,8 +227,82 @@ function collectCandidates(workspaceRoot, activeUserEmail) {
         }
         add('evidence', filePath, true, 'Evidence file.', eligibilityDate);
     }
+    // A workspace policy owns only its project bucket. Manager/company archives
+    // and other projects must not inherit whichever project is being cleaned.
+    const logRoot = node_path_1.default.resolve(options.hubEventLogRoot ?? node_path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'ai-hub-event-logs'));
+    // Project archive keys use the resolved path; keep core cleanup independent
+    // of the separately shipped Hub package that also uses this convention.
+    const bucket = node_crypto_1.default.createHash('sha256').update(node_path_1.default.resolve(workspaceRoot)).digest('hex').slice(0, 24);
+    const bucketDir = node_path_1.default.join(logRoot, bucket);
+    try {
+        if (!node_fs_1.default.lstatSync(bucketDir).isDirectory())
+            return candidates;
+    }
+    catch {
+        return candidates;
+    }
+    for (const filePath of listFiles(bucketDir)) {
+        if (!filePath.endsWith('.jsonl'))
+            continue;
+        const state = readHubArchiveState(logRoot, filePath);
+        if (!state)
+            continue;
+        add('hub_event_logs', filePath, state.eligible, state.reason, state.eligibilityDate);
+        Object.assign(candidates[candidates.length - 1], state);
+    }
     return candidates;
 }
+function readHubArchiveState(root, filePath) {
+    if (!isConfinedRegularFile(root, filePath))
+        return null;
+    try {
+        const metaPath = `${filePath}.meta.json`;
+        const hasMeta = isConfinedRegularFile(root, metaPath);
+        let meta = {};
+        if (hasMeta) {
+            try {
+                meta = JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf8')) ?? {};
+            }
+            catch { /* Crashed or legacy archive: use mtime. */ }
+        }
+        const endedAt = typeof meta.endedAt === 'string' ? parseDate(meta.endedAt) : undefined;
+        const active = !endedAt && isLiveProcess(meta.ownerPid);
+        const stat = node_fs_1.default.statSync(filePath);
+        return {
+            eligible: !active,
+            reason: active ? 'Archive writer is still running.' : endedAt ? 'Run has ended.' : 'Archive has no terminal stamp; using last write.',
+            eligibilityDate: endedAt ?? stat.mtime,
+            sidecarPath: hasMeta ? metaPath : undefined,
+            hubArchive: { root, realPath: node_fs_1.default.realpathSync(filePath), mtimeMs: stat.mtimeMs, size: stat.size },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isConfinedRegularFile(root, filePath) {
+    try {
+        if (!node_fs_1.default.lstatSync(filePath).isFile())
+            return false;
+        const relative = node_path_1.default.relative(node_fs_1.default.realpathSync(root), node_fs_1.default.realpathSync(filePath));
+        return relative !== '' && !relative.startsWith(`..${node_path_1.default.sep}`) && relative !== '..' && !node_path_1.default.isAbsolute(relative);
+    }
+    catch {
+        return false;
+    }
+}
+function isLiveProcess(pid) {
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Access denied still means a process exists. PID reuse errs toward retention.
+        return error.code !== 'ESRCH';
+    }
+}
 function daysBetween(from, to) {
     return Math.floor((to.getTime() - from.getTime()) / 86_400_000);
 }
@@ -254,7 +331,7 @@ function incrementCount(report, action) {
 function runArtifactCleanup(workspaceRoot, options) {
     const now = options.now ?? new Date();
     const retention = resolveArtifactRetentionConfig(workspaceRoot);
-    const candidates = collectCandidates(workspaceRoot, options.activeUserEmail);
+    const candidates = collectCandidates(workspaceRoot, options);
     const report = {
         generatedAt: now.toISOString(),
         apply: options.apply,
@@ -265,7 +342,7 @@ function runArtifactCleanup(workspaceRoot, options) {
     };
     for (const candidate of candidates) {
         const retentionValue = retention.values[candidate.category];
-        const decision = shouldDelete(candidate, retentionValue, now);
+        let decision = shouldDelete(candidate, retentionValue, now);
         let action;
         let error;
         if (!candidate.eligible) {
@@ -279,8 +356,31 @@ function runArtifactCleanup(workspaceRoot, options) {
         }
         else {
             try {
-                node_fs_1.default.unlinkSync(candidate.absolutePath);
-                action = 'deleted';
+                if (candidate.category === 'hub_event_logs' && candidate.hubArchive) {
+                    const prior = candidate.hubArchive;
+                    const current = readHubArchiveState(prior.root, candidate.absolutePath);
+                    // A terminal run can resume while other candidates are being collected.
+                    // Revalidate immediately before unlink; a changed archive waits for the
+                    // next cleanup, even when its new retention setting would be immediate.
+                    if (!current || !current.eligible || current.hubArchive?.realPath !== prior.realPath
+                        || current.hubArchive?.mtimeMs !== prior.mtimeMs || current.hubArchive?.size !== prior.size
+                        || current.eligibilityDate?.getTime() !== candidate.eligibilityDate?.getTime()
+                        || current.sidecarPath !== candidate.sidecarPath) {
+                        decision = { delete: false, reason: 'Archive changed or resumed after enumeration; retained for a later cleanup.' };
+                    }
+                    else {
+                        decision = shouldDelete({ ...candidate, ...current }, retentionValue, now);
+                    }
+                }
+                if (!decision.delete) {
+                    action = 'retained';
+                }
+                else {
+                    node_fs_1.default.unlinkSync(candidate.absolutePath);
+                    if (candidate.sidecarPath)
+                        node_fs_1.default.unlinkSync(candidate.sidecarPath);
+                    action = 'deleted';
+                }
             }
             catch (err) {
                 action = 'failed';

package/dist/src/services/installer-service.js

@@ -1,26 +1,9 @@
 "use strict";
 /**
- * InstallerService - Generates installer scripts and dashboard HTML for the Get Started flow.
- * Scripts are loaded from templates in scripts/installer/ and populated with token/baseUrl.
+ * InstallerService - Generates dashboard HTML for the Get Started flow.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InstallerService = void 0;
-const fs_1 = require("fs");
-const path_1 = require("path");
-function getScriptsDir() {
-    // When running from dist: dist/services/ -> dist/../scripts = scripts
-    // When running from src with tsx: src/services/ -> src/../scripts = scripts
-    const candidates = [
-        (0, path_1.join)(process.cwd(), 'scripts', 'installer'),
-        (0, path_1.join)(__dirname, '..', '..', 'scripts', 'installer'),
-        (0, path_1.join)(__dirname, '..', '..', '..', 'scripts', 'installer')
-    ];
-    for (const dir of candidates) {
-        if ((0, fs_1.existsSync)(dir))
-            return dir;
-    }
-    return null;
-}
 /**
  * Default marketing site base URL. All asset references and nav links in the
  * layout shell resolve against this host. Overridable via FRAIM_MARKETING_URL.
@@ -55,15 +38,6 @@ function buildLayoutShell(marketingBaseUrl) {
 <script src="${m}/js/script.js"></script></body></html>`;
 }
 class InstallerService {
-    constructor() {
-        this.scriptsDir = getScriptsDir();
-    }
-    requireScriptsDir() {
-        if (!this.scriptsDir) {
-            throw new Error('Installer scripts directory not found. Installer download is unavailable.');
-        }
-        return this.scriptsDir;
-    }
     /**
      * Build the HTML layout shell (nav, styles, theme) wrapping body content.
      *
@@ -105,27 +79,11 @@ class InstallerService {
 <h1 style="color:var(--error-color);margin-bottom:12px">${title}</h1><p style="color:var(--text-secondary)">${message}</p>
 <p style="margin-top:16px"><a href="${linkHref}" class="btn-primary">${linkText}</a></p></div></div>`;
     }
-    /**
-     * Generate the Mac installer script (.command) with the API key embedded.
-     */
-    generateMacScript(key, _baseUrl) {
-        const fraimCmd = `npx -y fraim@latest first-run --key=${key}`;
-        const templatePath = (0, path_1.join)(this.requireScriptsDir(), 'fraim-install-mac.template.sh');
-        const template = (0, fs_1.readFileSync)(templatePath, 'utf-8');
-        return template
-            .replace('{{FRAIM_CMD}}', fraimCmd)
-            .split('{{KEY}}').join(key);
+    generateMacScript(_key, _baseUrl) {
+        throw new Error('Shell installer fallbacks are retired; download FRAIM-Setup.dmg.');
     }
-    /**
-     * Generate the Windows installer script (.cmd) with the API key embedded.
-     */
-    generateWindowsScript(key, _baseUrl) {
-        const fraimCmd = `npx -y fraim@latest first-run --key=${key}`;
-        const templatePath = (0, path_1.join)(this.requireScriptsDir(), 'fraim-install-win.template.cmd');
-        const template = (0, fs_1.readFileSync)(templatePath, 'utf-8');
-        return template
-            .replace('{{FRAIM_CMD}}', fraimCmd)
-            .split('{{KEY}}').join(key);
+    generateWindowsScript(_key, _baseUrl) {
+        throw new Error('Command installer fallbacks are retired; download FRAIM-Setup.exe.');
     }
 }
 exports.InstallerService = InstallerService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.325",
+  "version": "2.0.327",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {