fraim 2.0.326 → 2.0.328

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/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/commands/sync.js

@@ -376,9 +376,18 @@ const runSync = async (options) => {
     await refreshOrgCache(remoteUrl, apiKey);
     // 1d. Refresh manager home
     await refreshManagerCache(remoteUrl, apiKey);
-    // 1e. Refresh MCP proxy launcher
-    const { ensureFraimMcpLatestLauncher } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
+    // 1e. Refresh MCP proxy launcher, and record the version this sync is running as the one
+    // the launcher should use next. Issue #1354: the launcher reuses its recorded version inside
+    // a freshness window instead of resolving npm on every launch, so without this a published
+    // fix reaches an installed machine up to a window late and nothing the user can run shortens
+    // that. Writing the record here makes `npx fraim@latest sync` the deliberate way to pull a
+    // release through immediately: it resolves latest, runs as latest, and records latest, which
+    // the next MCP server spawn picks up at once.
+    const { ensureFraimMcpLatestLauncher, recordFraimMcpLauncherVersion } = await Promise.resolve().then(() => __importStar(require('../mcp/fraim-mcp-latest-launcher')));
     ensureFraimMcpLatestLauncher();
+    if (recordFraimMcpLauncherVersion((0, version_utils_1.getFraimVersion)())) {
+        console.log(chalk_1.default.green(`  MCP launcher will use fraim@${(0, version_utils_1.getFraimVersion)()} on its next launch`));
+    }
     // 1f. Ensure user-level directories and runtime dependencies (Issue #1508:
     // synced scripts like the DOCX review layer require npm deps such as
     // adm-zip; a plain sync must install them, not just create directories)

package/dist/src/cli/doctor/checks/fraim-mcp-diagnostics.js

@@ -12,15 +12,14 @@ exports.buildAgentDebugSteps = buildAgentDebugSteps;
 exports.interpretationForClassification = interpretationForClassification;
 exports.analyzeFraimProxyLog = analyzeFraimProxyLog;
 exports.diagnoseFraimServerConfigConsistency = diagnoseFraimServerConfigConsistency;
-const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
+const redact_secrets_1 = require("../../../core/utils/redact-secrets");
 exports.DEFAULT_FRAIM_REMOTE_URL = 'https://fraim.wellnessatwork.me';
 exports.FRAIM_PROXY_LOG_FILE = 'fraim-mcp-proxy.log';
 function fingerprintSecret(secret) {
     return {
-        prefix: secret.slice(0, 10),
-        length: secret.length,
-        sha256: crypto_1.default.createHash('sha256').update(secret).digest('hex').slice(0, 16)
+        ref: (0, redact_secrets_1.redactApiKey)(secret),
+        length: secret.length
     };
 }
 function normalizeUrl(url) {
@@ -33,9 +32,11 @@ function appendLimited(current, chunk, maxChars = 8000) {
 function sanitizeDiagnosticText(text, knownSecrets = []) {
     let sanitized = text;
     for (const secret of knownSecrets.filter(Boolean)) {
-        sanitized = sanitized.split(secret).join(`${secret.slice(0, 10)}...`);
+        sanitized = sanitized.split(secret).join((0, redact_secrets_1.redactApiKey)(secret));
     }
-    return sanitized.replace(/fraim_[A-Za-z0-9_-]+/g, (match) => `${match.slice(0, 10)}...`);
+    // Issue #1701: a truncated key is still disclosed key material. Substitute the
+    // same reference the rest of FRAIM logs so diagnostics stay correlatable.
+    return sanitized.replace(/fraim_[A-Za-z0-9_-]+/g, (match) => (0, redact_secrets_1.redactApiKey)(match));
 }
 function readFileTailUtf8(filePath, maxBytes = 256 * 1024) {
     const stat = fs_1.default.statSync(filePath);
@@ -133,7 +134,13 @@ function interpretationForClassification(classification) {
             return 'The proxy log did not match a known FRAIM MCP startup pattern.';
     }
 }
-function analyzeFraimProxyLog(logContent, options = {}) {
+function analyzeFraimProxyLog(logContent, 
+/**
+ * `expectedKeyRef` is the redacted reference the proxy writes in its per-line
+ * `[...]` segment (issue #1701), not a raw key. Callers holding a raw key must
+ * pass `redactApiKey(key)`.
+ */
+options = {}) {
     const maxLines = options.maxLines ?? 300;
     const allLines = logContent.split(/\r?\n/).map(line => line.trim()).filter(Boolean).slice(-maxLines);
     if (allLines.length === 0) {
@@ -152,10 +159,10 @@ function analyzeFraimProxyLog(logContent, options = {}) {
         };
     }
     const keyLineRegex = /^\S+\s+\[([^\]]+)\]\s+(.*)$/;
-    const matchingLines = options.expectedKey
-        ? allLines.filter(line => keyLineRegex.exec(line)?.[1] === options.expectedKey)
+    const matchingLines = options.expectedKeyRef
+        ? allLines.filter(line => keyLineRegex.exec(line)?.[1] === options.expectedKeyRef)
         : allLines;
-    if (options.expectedKey && matchingLines.length === 0) {
+    if (options.expectedKeyRef && matchingLines.length === 0) {
         const classification = 'no-log-lines-for-expected-key';
         return {
             classification,

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

@@ -55,6 +55,7 @@ const child_process_1 = require("child_process");
 const win32_cmd_spawn_1 = require("../../utils/win32-cmd-spawn");
 const axios_1 = __importDefault(require("axios"));
 const toml = __importStar(require("toml"));
+const redact_secrets_1 = require("../../../core/utils/redact-secrets");
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
 const fraim_mcp_diagnostics_1 = require("./fraim-mcp-diagnostics");
@@ -150,6 +151,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',
@@ -286,7 +303,7 @@ async function testFraimConnectivity() {
         if (process.env.DEBUG_DOCTOR) {
             console.log('[DOCTOR DEBUG] Testing FRAIM connectivity:');
             console.log('  URL:', remoteUrl);
-            console.log('  API Key:', apiKey.substring(0, 15) + '...');
+            console.log('  API Key:', (0, redact_secrets_1.redactApiKey)(apiKey));
             console.log('  NODE_ENV:', process.env.NODE_ENV || 'not set');
         }
         // Warn if testing against localhost (might be in test mode)
@@ -615,7 +632,8 @@ async function testFraimLocalProxyTroubleshooting() {
     }
     const logTail = (0, fraim_mcp_diagnostics_1.readFileTailUtf8)(logPath);
     const analysis = (0, fraim_mcp_diagnostics_1.analyzeFraimProxyLog)(logTail.content, {
-        expectedKey: keyDiagnostic.apiKey,
+        // The proxy tags each line with the key's reference, never the key (issue #1701).
+        expectedKeyRef: (0, redact_secrets_1.redactApiKey)(keyDiagnostic.apiKey),
         maxLines: 300
     });
     const errorClassifications = [

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

@@ -8,15 +8,58 @@ exports.getFraimMcpShimPath = getFraimMcpShimPath;
 exports.getFraimNpxShimPath = getFraimNpxShimPath;
 exports.getFraimCliShimPath = getFraimCliShimPath;
 exports.getPackagedFraimRuntimePath = getPackagedFraimRuntimePath;
-exports.getPackagedFraimRuntime = getPackagedFraimRuntime;
-exports.hasPackagedFraimRuntime = hasPackagedFraimRuntime;
+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 PACKAGED_RUNTIME_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');
@@ -24,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');
@@ -32,7 +79,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);
@@ -65,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;
@@ -78,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 };
@@ -86,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 };
   }
@@ -96,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 };
@@ -108,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') {
@@ -133,75 +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 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;
+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');
 }
-// 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;
+/**
+ * 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 {
-        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 };
+        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 {
-        return null;
+        // 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;
     }
 }
-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 +324,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 +348,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
-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" "$@"
-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
+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")
 
-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" "$@"
+if command -v ${executable} >/dev/null 2>&1; then
+  exec ${executable} ${args}
 fi
+# 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 "[fraim-npx] Could not find npx on PATH or in $FRAIM_USER_DIR_VALUE/node" >&2
+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 +392,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)