fraim-hub 2.0.327 → 2.0.329

package/dist/src/ai-hub/server.js

@@ -41,7 +41,7 @@ exports.selfHealBrokenManagedAgents = selfHealBrokenManagedAgents;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
 exports.installAgentAndRefreshDetection = installAgentAndRefreshDetection;
 exports.hubCommandVersion = hubCommandVersion;
-exports.__setStartupSyncSpawnForTests = __setStartupSyncSpawnForTests;
+exports.__setCatalogSyncSpawnForTests = __setCatalogSyncSpawnForTests;
 exports.__setAgentInstallTimeoutMsForTests = __setAgentInstallTimeoutMsForTests;
 exports.hubRunProcess = hubRunProcess;
 exports.buildOpenFileInvocation = buildOpenFileInvocation;
@@ -2088,12 +2088,10 @@ function hubRunSync(command, args, env) {
 // (typically seconds) while still bounding the failure the way AC-C1 requires.
 const DEFAULT_AGENT_INSTALL_TIMEOUT_MS = 90_000;
 let agentInstallTimeoutMs = DEFAULT_AGENT_INSTALL_TIMEOUT_MS;
-// Test seam for the startup machine-level sync (Issue #1645). Allows tests to
-// intercept the spawn call without actually invoking npx.
-let startupSyncSpawnFn = child_process_1.spawn;
-/** Test seam only. Pass null to restore the production spawn. */
-function __setStartupSyncSpawnForTests(fn) {
-    startupSyncSpawnFn = fn ?? child_process_1.spawn;
+// Intercept only the catalog subprocess in Hub tests.
+let catalogSyncSpawn = child_process_1.spawn;
+function __setCatalogSyncSpawnForTests(fn) {
+    catalogSyncSpawn = fn ?? child_process_1.spawn;
 }
 /** Test seam only. Mirrors __setEmployeeDetectionTtlForTests in hosts.ts — proves the bound
  * actually fires without a real 90s hang. Pass null to restore the production value. */
@@ -2904,6 +2902,7 @@ class AiHubServer {
         // request or window — see the comment on BADGE_POLL_INTERVAL_MS for why this can't just
         // live on the client or the relaunch-decision path.
         this.latestVersionPollTimer = null;
+        this.catalogSyncChild = null;
         this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
         const launchResolution = options.projectPath
             ? { projectPath: path_1.default.resolve(options.projectPath) }
@@ -3174,6 +3173,30 @@ class AiHubServer {
     resolveRunProjectPath(bodyProjectPath, scope) {
         return (0, run_working_directory_1.resolveRunWorkingDirectory)(scope, bodyProjectPath, this.defaultProjectPath());
     }
+    // Resolve latest outside the Hub process; sync also updates the MCP launcher record (#1354).
+    refreshLocalCatalogInBackground(global, projectRoot) {
+        if (process.env.NODE_ENV === 'test' || this.catalogSyncChild)
+            return;
+        const args = ['--yes', 'fraim@latest', 'sync', ...(global ? ['--global'] : [])];
+        try {
+            // Windows npx is a .cmd shim. Only fixed arguments enter cmd; projectRoot stays in cwd.
+            const child = catalogSyncSpawn(process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'npx', process.platform === 'win32' ? ['/d', '/s', '/c', 'npx', ...args] : args, { cwd: projectRoot, detached: true, stdio: 'ignore', windowsHide: true });
+            this.catalogSyncChild = child;
+            const release = () => {
+                if (this.catalogSyncChild === child)
+                    this.catalogSyncChild = null;
+            };
+            child.once('error', (error) => {
+                release();
+                console.warn('[ai-hub] catalog sync could not start:', error.message);
+            });
+            child.once('close', release);
+            child.unref();
+        }
+        catch (error) {
+            console.warn('[ai-hub] catalog sync could not start:', error.message);
+        }
+    }
     async start(port) {
         this.httpPort = port;
         await new Promise((resolve, reject) => {
@@ -3216,17 +3239,8 @@ class AiHubServer {
                 console.warn('[ai-hub] self-heal pass failed:', error?.message || error);
             });
         }
-        // Issue #1645: fire-and-forget machine-level sync so the delegate job list
-        // is current within the session. Skipped in NODE_ENV=test to avoid spawning
-        // real processes in the test suite's many short-lived Hub instances.
-        if (process.env.NODE_ENV !== 'test') {
-            const syncChild = startupSyncSpawnFn('npx', ['fraim', 'sync', '--global'], {
-                detached: true,
-                stdio: 'ignore',
-            });
-            syncChild.on('error', () => { });
-            syncChild.unref();
-        }
+        // Refresh the machine-level job list without delaying Hub startup.
+        this.refreshLocalCatalogInBackground(true);
         // Update-badge freshness: refresh the npm-latest cache on our own clock, not just when
         // a page load or relaunch decision happens to ask for it. Without this, a Hub that's
         // resident in the tray for days with no window reload and no tray re-click never learns
@@ -7036,12 +7050,7 @@ class AiHubServer {
                 res.status(201).json(responsePayload);
                 // Background sync: refresh the local FRAIM catalog so the next job
                 // picker load sees any jobs that were added or updated since last run.
-                try {
-                    const syncChild = (0, child_process_1.spawn)('npx', ['fraim', 'sync'], { cwd: projectPath, detached: true, stdio: 'ignore' });
-                    syncChild.on('error', () => { });
-                    syncChild.unref();
-                }
-                catch { /* ignore if spawn itself throws synchronously */ }
+                this.refreshLocalCatalogInBackground(false, projectPath);
             }
             catch (error) {
                 for (const spawningRun of pendingSpawnRuns) {

package/dist/src/api/payment/webhook.js

@@ -11,6 +11,7 @@ exports.resolveSubscriptionNextBillingDateWithInvoiceFallback = resolveSubscript
 exports.buildCurrentPeriodEndUpdate = buildCurrentPeriodEndUpdate;
 exports.resolveInvoicePaidNextBillingDate = resolveInvoicePaidNextBillingDate;
 const stripe_1 = require("../../config/stripe");
+const redact_secrets_1 = require("../../core/utils/redact-secrets");
 const feature_flags_1 = require("../../config/feature-flags");
 const email_service_1 = require("../../services/email-service");
 const dashboard_access_1 = require("../../services/dashboard-access");
@@ -273,7 +274,7 @@ async function handleSubscriptionCreatedOrUpdated(subscription, dbService) {
                 expiresAt: null, // Subscriptions don't have fixed expiration
                 cancelAt: subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null
             });
-            console.log(`✅ Upgraded trial key to paid subscription: ${apiKey.key}`);
+            console.log(`✅ Upgraded trial key to paid subscription: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
         }
         else {
             // Create new API key for subscription (shouldn't happen in normal flow)
@@ -295,7 +296,7 @@ async function handleSubscriptionCreatedOrUpdated(subscription, dbService) {
                 apiCallCount: 0,
                 personaSystemActive: (0, feature_flags_1.isPersonaEntitlementsEnabled)() || undefined
             });
-            console.log(`✅ Created new API key for subscription: ${newKey}`);
+            console.log(`✅ Created new API key for subscription: ${(0, redact_secrets_1.redactApiKey)(newKey)}`);
             apiKey = { key: newKey, userId: email };
         }
     }
@@ -358,7 +359,7 @@ async function handleSubscriptionDeleted(subscription, dbService) {
     // Send cancellation email
     const emailService = new email_service_1.EmailService();
     await emailService.sendSubscriptionCancelled(apiKey.userId, new Date());
-    console.log(`✅ API key expired due to subscription cancellation: ${apiKey.key}`);
+    console.log(`✅ API key expired due to subscription cancellation: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
 }
 async function handleInvoicePaid(invoice, dbService) {
     console.log(`✅ Invoice paid: ${invoice.id}`);
@@ -438,7 +439,7 @@ async function handleInvoicePaid(invoice, dbService) {
             suspendedAt: null,
             suspensionReason: null
         });
-        console.log(`✅ API key restored after payment: ${apiKey.key}`);
+        console.log(`✅ API key restored after payment: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
         // Send restoration email
         const emailService = new email_service_1.EmailService();
         const restorationBillingDate = nextBillingDate || new Date();
@@ -467,7 +468,7 @@ async function handleInvoicePaid(invoice, dbService) {
     }
     // Regular renewal
     {
-        console.log(`✅ Subscription renewed: ${apiKey.key}`);
+        console.log(`✅ Subscription renewed: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
         if (nextBillingDate) {
             await dbService.updateApiKey(apiKey.key, buildCurrentPeriodEndUpdate(nextBillingDate));
         }
@@ -532,7 +533,7 @@ async function handleInvoicePaymentFailed(invoice, dbService) {
         suspendedAt: new Date(),
         suspensionReason: 'payment_failed'
     });
-    console.log(`✅ API key suspended due to payment failure: ${apiKey.key}`);
+    console.log(`✅ API key suspended due to payment failure: ${(0, redact_secrets_1.redactApiKey)(apiKey.key)}`);
     // Send payment failure email with 7-day grace period
     const emailService = new email_service_1.EmailService();
     const gracePeriodEndsAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days

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

@@ -8,12 +8,58 @@ exports.getFraimMcpShimPath = getFraimMcpShimPath;
 exports.getFraimNpxShimPath = getFraimNpxShimPath;
 exports.getFraimCliShimPath = getFraimCliShimPath;
 exports.getPackagedFraimRuntimePath = getPackagedFraimRuntimePath;
+exports.getFraimMcpLauncherStatePath = getFraimMcpLauncherStatePath;
+exports.recordFraimMcpLauncherVersion = recordFraimMcpLauncherVersion;
 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 LAUNCHER_VERSION = 2;
+/**
+ * Issue #1354: how long a resolved version stays good before the launcher asks npm again.
+ *
+ * Resolving "latest" is a registry round trip by definition, so a launcher that resolves on
+ * every invocation pays that cost on every invocation - and pays a full connection timeout
+ * when the registry is unreachable, which is the silent-startup-failure this issue reports.
+ * Bounding it to one resolve per window is what makes the offline path cheap: with a fresh
+ * record there is no reason to touch the network at all.
+ *
+ * The tradeoff is explicit: inside the window the launcher runs the last version it resolved,
+ * so "always latest" is really "latest as of at most one window ago". 24h is not a new number -
+ * it matches `FraimLocalMCPServer.DEFAULT_CONNECT_SYNC_MAX_AGE_MS`, the connect-time catalog
+ * freshness window, rather than introducing a second unrelated one.
+ */
+const STALENESS_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long the resolve may spend talking to the registry before giving up.
+ *
+ * Paired with `--fetch-retries=0`: the resolve is always optional, because a failure falls back
+ * to the recorded version, so the only thing a long wait buys is the difference between a brief
+ * pause and an apparent hang at process spawn. 5s is comfortably above a healthy registry round
+ * trip (measured at roughly 0.7-1.4s on this machine) and well inside an MCP client's startup
+ * window, which is the budget this issue reports blowing.
+ */
+const RESOLVE_TIMEOUT_MS = 5000;
+/** Per-version npm caches to keep. Older ones are pruned so the directory stays bounded. */
+const CACHE_GENERATIONS_KEPT = 2;
+/**
+ * A per-version cache is only ever a prune candidate once it is this old.
+ *
+ * The generation count alone is not a safe rule here, because these directories are not inert
+ * caches: `runPackage` points `npm_config_cache` at one, and npx installs the package *inside*
+ * it at `_npx/<hash>/node_modules`. An MCP stdio server lives as long as its agent session and
+ * resolves dynamic imports from that tree for its whole life, so removing the cache of a version
+ * still being served would pull the module tree out from under a running process. On Windows it
+ * is worse than a clean failure: `rmSync` deletes whatever is not currently open and throws on
+ * the rest, leaving a half-gutted tree.
+ *
+ * An age floor is the cheap correct guard, and matches how this repository already bounds
+ * on-disk growth elsewhere (`artifact-retention-cleanup` retires by age in days, not by count).
+ * Growth stays bounded - everything past the newest few ages out - while any cache a plausibly
+ * live session could still be reading is off limits.
+ */
+const CACHE_MIN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const launcherSource = `#!/usr/bin/env node
 const fs = require('fs');
 const os = require('os');
@@ -21,6 +67,10 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const LAUNCHER_VERSION = ${LAUNCHER_VERSION};
+const STALENESS_WINDOW_MS = ${STALENESS_WINDOW_MS};
+const RESOLVE_TIMEOUT_MS = ${RESOLVE_TIMEOUT_MS};
+const CACHE_GENERATIONS_KEPT = ${CACHE_GENERATIONS_KEPT};
+const CACHE_MIN_AGE_MS = ${CACHE_MIN_AGE_MS};
 const USER_DIR = process.env.FRAIM_USER_DIR || path.join(os.homedir(), '.fraim');
 const STATE_DIR = path.join(USER_DIR, 'mcp-launcher');
 const STATE_PATH = path.join(STATE_DIR, 'latest.json');
@@ -64,10 +114,14 @@ function writeState(state) {
 }
 
 function resolveLatest(packageName) {
-  const result = runCommand(npmCommand, ['view', packageName, 'version', '--silent'], {
-    encoding: 'utf8',
-    env: process.env
-  });
+  // Fail fast rather than waiting out npm's default retry ladder. This resolve is always
+  // optional: a failure falls back to the recorded version, so a long wait buys nothing and is
+  // the difference between a brief pause and an apparent hang when the registry is unreachable.
+  const result = runCommand(
+    npmCommand,
+    ['view', packageName, 'version', '--silent', '--fetch-retries=0', '--fetch-timeout=' + RESOLVE_TIMEOUT_MS],
+    { encoding: 'utf8', env: process.env }
+  );
 
   if (result.status !== 0) {
     return null;
@@ -77,7 +131,47 @@ function resolveLatest(packageName) {
   return /^\\d+\\.\\d+\\.\\d+/.test(version) ? version : null;
 }
 
+/**
+ * Whether a record names a version this launcher can run.
+ *
+ * Deliberately not gated on launcherVersion. The record's shape is what matters and that has
+ * not changed, so a record written by an earlier launcher is still a usable fallback. Rejecting
+ * one would mean the first launch after a launcher upgrade fails outright when the registry is
+ * unreachable, turning a working offline start into an error for no benefit.
+ */
+function isUsableState(state) {
+  // The version shape is re-checked here, not only where npm answers. This record is the common
+  // path now rather than a rare fallback, and its value reaches both an npx --package argument
+  // and a cache directory name, so it is validated at the point of use rather than trusted
+  // because writeState happened to produce it.
+  return Boolean(
+    state &&
+    state.packageName === 'fraim' &&
+    state.binName === 'fraim' &&
+    typeof state.version === 'string' &&
+    /^\\d+\\.\\d+\\.\\d+/.test(state.version)
+  );
+}
+
+/** True while the recorded resolve is recent enough to reuse without asking npm. */
+function isFresh(state) {
+  if (!isUsableState(state)) return false;
+  const recordedAt = Date.parse(state.updatedAt);
+  if (!Number.isFinite(recordedAt)) return false;
+  const age = Date.now() - recordedAt;
+  // A record stamped in the future is a clock change, not freshness.
+  return age >= 0 && age < STALENESS_WINDOW_MS;
+}
+
 function resolvePackage() {
+  // Read the freshness record before reaching for the network. This ordering is the fix: the
+  // record used to be consulted only after the resolve had already failed, so the happy path
+  // was gated on npm reachability on every single launch.
+  const cached = readState();
+  if (isFresh(cached)) {
+    return { packageName: 'fraim', binName: 'fraim', version: cached.version, fromCache: true };
+  }
+
   const fraimVersion = resolveLatest('fraim');
   if (fraimVersion) {
     const state = { packageName: 'fraim', binName: 'fraim', version: fraimVersion, fromCache: false };
@@ -85,8 +179,7 @@ function resolvePackage() {
     return state;
   }
 
-  const cached = readState();
-  if (cached && cached.packageName === 'fraim' && cached.binName === 'fraim' && cached.version) {
+  if (isUsableState(cached)) {
     console.error('[fraim-mcp-launcher] Could not resolve npm latest; using cached fraim@' + cached.version + '.');
     return { packageName: 'fraim', binName: 'fraim', version: cached.version, fromCache: true };
   }
@@ -95,6 +188,37 @@ function resolvePackage() {
   process.exit(1);
 }
 
+/**
+ * Keep the newest few per-version caches and age out the rest. Each entry is a full npm cache
+ * for one version (~80MB), plus one retry-<timestamp>-<pid> directory per Windows launch
+ * failure, so without a bound the directory grows once per release forever.
+ *
+ * A directory is removed only when it is BOTH outside the newest CACHE_GENERATIONS_KEPT and
+ * older than CACHE_MIN_AGE_MS. The age floor is what keeps this safe: the package is installed
+ * inside the cache directory, so a recent one may still be backing a running MCP server.
+ *
+ * Best effort throughout: a cache that cannot be removed is not a reason to fail the launch.
+ */
+function pruneCaches(keepDir, nowMs) {
+  try {
+    const entries = fs.readdirSync(CACHE_ROOT, { withFileTypes: true })
+      .filter(function (entry) { return entry.isDirectory(); })
+      .map(function (entry) {
+        const full = path.join(CACHE_ROOT, entry.name);
+        let mtime = 0;
+        try { mtime = fs.statSync(full).mtimeMs; } catch (error) { mtime = 0; }
+        return { full: full, mtime: mtime };
+      })
+      .filter(function (entry) { return entry.full !== keepDir; })
+      .sort(function (a, b) { return b.mtime - a.mtime; });
+
+    for (const entry of entries.slice(Math.max(0, CACHE_GENERATIONS_KEPT - 1))) {
+      if (nowMs - entry.mtime < CACHE_MIN_AGE_MS) continue;
+      try { fs.rmSync(entry.full, { recursive: true, force: true }); } catch (error) { /* leave it */ }
+    }
+  } catch (error) { /* nothing to prune */ }
+}
+
 function runPackage(plan, cacheDir) {
   ensureDir(cacheDir);
   const env = { ...process.env, npm_config_cache: cacheDir };
@@ -107,6 +231,7 @@ function runPackage(plan, cacheDir) {
 
 const plan = resolvePackage();
 const versionCacheDir = path.join(CACHE_ROOT, plan.packageName + '-' + plan.version.replace(/[^a-zA-Z0-9._-]/g, '_'));
+pruneCaches(versionCacheDir, Date.now());
 let status = runPackage(plan, versionCacheDir);
 
 if (status !== 0 && process.platform === 'win32') {
@@ -132,6 +257,50 @@ 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 getFraimMcpLauncherStatePath() {
+    return path_1.default.join(process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim'), 'mcp-launcher', 'latest.json');
+}
+/**
+ * Record `version` as the version the launcher should run, resetting the freshness window.
+ *
+ * This is the deliberate escape hatch from `STALENESS_WINDOW_MS`. The window is what keeps
+ * ordinary launches off the network, but it also means a published fix reaches an installed
+ * machine up to a window late. `fraim sync` calls this with the version it is itself running, so
+ * `npx fraim@latest sync` resolves latest, runs as latest, and records latest - which the next
+ * MCP server spawn then uses immediately instead of waiting out the window.
+ *
+ * The semantics are "the version you just ran is the version recorded", which is why the caller
+ * passes its own version rather than this function consulting the registry. A sync that ran an
+ * older package must not claim to have recorded a newer one.
+ *
+ * The record's shape is duplicated from the generated launcher's `writeState`, deliberately and
+ * unavoidably: that script executes standalone from `~/.fraim/bin` with only Node built-ins and
+ * cannot import this module. The two writers must stay in step, and
+ * `test-1354-mcp-launcher-freshness-window.ts` asserts that a record written here is accepted by
+ * the launcher rather than merely that the fields look alike.
+ */
+function recordFraimMcpLauncherVersion(version) {
+    if (!/^\d+\.\d+\.\d+/.test(version))
+        return false;
+    const statePath = getFraimMcpLauncherStatePath();
+    try {
+        fs_1.default.mkdirSync(path_1.default.dirname(statePath), { recursive: true });
+        fs_1.default.writeFileSync(statePath, JSON.stringify({
+            packageName: 'fraim',
+            binName: 'fraim',
+            version,
+            fromCache: false,
+            launcherVersion: LAUNCHER_VERSION,
+            updatedAt: new Date().toISOString()
+        }, null, 2));
+        return true;
+    }
+    catch {
+        // Best effort. A sync that cannot write this record has still synced the catalog, and the
+        // launcher resolves normally when the window expires; failing the sync would be worse.
+        return false;
+    }
+}
 const windowsFraimMcpShimSource = `@echo off
 setlocal
 for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"

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/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');
 }
@@ -426,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';
@@ -676,7 +562,7 @@ class FirstRunSessionService {
                 this.persist();
                 return this.respond('FRAIM installer repair is required.', false);
             }
-            persistShellPath(this.embeddedDesktop);
+            (0, persist_shell_path_1.persistShellPath)();
             row.status = 'ok';
             row.verb = 'Node and FRAIM launchers ready';
             this.persist();
@@ -686,7 +572,7 @@ class FirstRunSessionService {
         // 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();
@@ -718,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';
@@ -747,21 +633,9 @@ class FirstRunSessionService {
             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 (!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...';
-                this.persist();
-                await runProcess('npm', ['install', '-g', 'fraim@latest'], { npm_config_prefix: prefix });
-            }
-            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));
@@ -1009,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') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.327",
+  "version": "2.0.329",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -49,6 +49,7 @@
     "dist/src/cli/utils/machine-path.js",
     "dist/src/cli/utils/managed-agent-install.js",
     "dist/src/cli/utils/managed-agent-paths.js",
+    "dist/src/cli/utils/persist-shell-path.js",
     "dist/src/cli/utils/managed-node-runtime.js",
     "dist/src/cli/utils/org-publish.js",
     "dist/src/cli/utils/pack-git-publish.js",
@@ -77,6 +78,7 @@
     "dist/src/core/utils/local-registry-resolver.js",
     "dist/src/core/utils/ports.js",
     "dist/src/core/utils/project-fraim-paths.js",
+    "dist/src/core/utils/redact-secrets.js",
     "dist/src/core/utils/setup-preferences.js",
     "dist/src/core/utils/windows-shim-path-search.js",
     "dist/src/db/payment-repository.js",
@@ -214,7 +216,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.327",
+    "fraim": "2.0.329",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",