fraim 2.0.327 → 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/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");
@@ -302,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)
@@ -631,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,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/dist/src/local-mcp-server/stdio-server.js

@@ -62,6 +62,7 @@ const crypto_1 = require("crypto");
 const axios_1 = __importDefault(require("axios"));
 const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
+const redact_secrets_1 = require("../core/utils/redact-secrets");
 const pack_home_1 = require("../cli/utils/pack-home");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 const ai_mentor_1 = require("../core/ai-mentor");
@@ -553,7 +554,7 @@ class FraimLocalMCPServer {
         }
         this.log('🚀 FRAIM Local MCP Server starting... [DEBUG-PROXY-V3]');
         this.log(`📡 Remote server: ${this.remoteUrl}`);
-        this.log(`🔑 API key: ${this.apiKey.substring(0, 10)}...`);
+        this.log(`🔑 API key: ${(0, redact_secrets_1.redactApiKey)(this.apiKey)}`);
         this.log(`Local MCP version: ${this.localVersion}`);
         this.log(`🔍 DEBUG BUILD: Machine detection v2 active`);
         // Initialize usage collector
@@ -626,23 +627,35 @@ class FraimLocalMCPServer {
             this.log(`Could not persist userEmail: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    /**
+     * Non-reversible reference for this proxy's key (issue #1701). Every line the
+     * proxy writes carries it, and the proxy mirrors those lines into a temp file
+     * that survives the process, so the key itself must never appear here. The
+     * reference matches the one the server logs for the same key, so a user's local
+     * log still correlates with the server-side log.
+     */
+    keyRef() {
+        return this.apiKey ? (0, redact_secrets_1.redactApiKey)(this.apiKey) : 'MISSING_API_KEY';
+    }
     log(message) {
         // Log to stderr (stdout is reserved for MCP protocol)
-        const key = this.apiKey || 'MISSING_API_KEY';
-        console.error(`[FRAIM key:${key}] ${message}`);
+        const keyRef = this.keyRef();
+        // Messages are assembled from remote responses and caught errors, either of
+        // which can carry a credential this proxy did not author.
+        const safeMessage = (0, redact_secrets_1.redactSecretsInText)(message);
+        console.error(`[FRAIM key:${keyRef}] ${safeMessage}`);
         // Also log to file for debugging
         try {
             const fs = require('fs');
             const logFile = require('path').join(require('os').tmpdir(), 'fraim-mcp-proxy.log');
-            fs.appendFileSync(logFile, `${new Date().toISOString()} [${key}] ${message}\n`);
+            fs.appendFileSync(logFile, `${new Date().toISOString()} [${keyRef}] ${safeMessage}\n`);
         }
         catch (e) {
             // Ignore file logging errors
         }
     }
     logError(message) {
-        const key = this.apiKey || 'MISSING_API_KEY';
-        console.error(`[FRAIM ERROR key:${key}] ${message}`);
+        console.error(`[FRAIM ERROR key:${this.keyRef()}] ${(0, redact_secrets_1.redactSecretsInText)(message)}`);
     }
     detectLocalVersion() {
         const candidates = [

package/dist/src/middleware/auth.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthMiddleware = void 0;
+const redact_secrets_1 = require("../core/utils/redact-secrets");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const cookie_service_1 = require("../services/cookie-service");
@@ -219,7 +220,7 @@ class AuthMiddleware {
         try {
             const apiKeyData = await this.dbService.verifyApiKey(apiKey);
             if (!apiKeyData) {
-                console.error(`❌ FRAIM AUTH: Invalid API key: ${apiKey}`);
+                console.error(`❌ FRAIM AUTH: Invalid API key: ${(0, redact_secrets_1.redactApiKey)(apiKey)}`);
                 setMcpAuthenticateChallenge();
                 return res.status(401).json({
                     jsonrpc: '2.0',
@@ -230,7 +231,7 @@ class AuthMiddleware {
             // Check if key is suspended
             if (apiKeyData.status === 'suspended') {
                 const reason = apiKeyData.suspensionReason || 'payment failure';
-                console.error(`❌ FRAIM AUTH: Suspended API key: ${apiKey} (reason: ${reason})`);
+                console.error(`❌ FRAIM AUTH: Suspended API key: ${(0, redact_secrets_1.redactApiKey)(apiKey)} (reason: ${reason})`);
                 return res.status(402).json({
                     jsonrpc: '2.0',
                     error: {
@@ -255,7 +256,7 @@ class AuthMiddleware {
                 const message = tier === 'trial'
                     ? 'Your 14-day free trial has expired. Please upgrade to continue using FRAIM.'
                     : 'Your subscription has expired. Please renew to continue using FRAIM.';
-                console.error(`❌ FRAIM AUTH: Expired API key: ${apiKey} (tier: ${tier})`);
+                console.error(`❌ FRAIM AUTH: Expired API key: ${(0, redact_secrets_1.redactApiKey)(apiKey)} (tier: ${tier})`);
                 return res.status(402).json({
                     jsonrpc: '2.0',
                     error: {

package/dist/src/middleware/logger.js

@@ -35,38 +35,21 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestLogger = requestLogger;
 const crypto_1 = require("crypto");
+const redact_secrets_1 = require("../core/utils/redact-secrets");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const LOG_FILE = path.join(process.cwd(), 'server-direct.log');
-/**
- * Extracts API key from request for logging purposes
- */
-function getApiKeyForLogging(req) {
-    const fromContext = req.apiKeyData?.key;
-    if (typeof fromContext === 'string' && fromContext.trim().length > 0) {
-        return fromContext;
-    }
-    const fromHeader = Array.isArray(req.headers['x-api-key'])
-        ? req.headers['x-api-key'][0]
-        : req.headers['x-api-key'];
-    if (typeof fromHeader === 'string' && fromHeader.trim().length > 0) {
-        return fromHeader;
-    }
-    const fromQuery = req.query?.['api-key'];
-    if (typeof fromQuery === 'string' && fromQuery.trim().length > 0) {
-        return fromQuery;
-    }
-    return 'ANONYMOUS';
-}
 function getBodyForLogging(req) {
     if (req.path === '/api/ai-hub/brand' && req.body && typeof req.body === 'object') {
         const body = { ...req.body };
         if (typeof body.logo === 'string' && body.logo.length > 0) {
             body.logo = `[redacted logo payload, ${body.logo.length} chars]`;
         }
-        return JSON.stringify(body);
+        return (0, redact_secrets_1.redactSecretsInText)(JSON.stringify(body));
     }
-    return JSON.stringify(req.body);
+    // Bodies are logged verbatim; a caller that puts a credential in one must not
+    // have it land in the log in the clear (issue #1701).
+    return (0, redact_secrets_1.redactSecretsInText)(JSON.stringify(req.body));
 }
 /**
  * Middleware to log all requests
@@ -118,8 +101,8 @@ function requestLogger(req, res, next) {
     res.on('finish', () => {
         const duration = Date.now() - start;
         const status = res.statusCode;
-        const keyStr = getApiKeyForLogging(req);
-        const logMsg = `[req:${requestId}] [local:${localMcpVersion}] ${keyStr} END ${method} ${path} ${status} ${duration}ms`;
+        const keyRef = (0, redact_secrets_1.apiKeyRefFromRequest)(req);
+        const logMsg = `[req:${requestId}] [local:${localMcpVersion}] ${keyRef} END ${method} ${path} ${status} ${duration}ms`;
         logEntry(logMsg);
     });
     next();

package/dist/src/middleware/telemetry.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TelemetryMiddleware = void 0;
+const redact_secrets_1 = require("../core/utils/redact-secrets");
 class TelemetryMiddleware {
     constructor(sessionManager) {
         this.sessionManager = sessionManager;
@@ -125,7 +126,7 @@ After successful fraim_connect, all other FRAIM tools will work. This is require
                     id: req.body?.id || null
                 });
             }
-            console.log(`Telemetry active for ${apiKey}`);
+            console.log(`Telemetry active for ${(0, redact_secrets_1.redactApiKey)(apiKey)}`);
             return next();
         }
         catch (error) {

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionManager = void 0;
+const redact_secrets_1 = require("../core/utils/redact-secrets");
 class SessionManager {
     constructor(dbService) {
         this.sessions = new Map();
@@ -42,7 +43,7 @@ class SessionManager {
                     : await this.dbService.getActiveSessionByApiKey(apiKey);
                 if (dbSession) {
                     sessionKey = this.getSessionKey(apiKey, dbSession.sessionId);
-                    console.log(`Re-hydrating session for API Key: ${apiKey}, sessionId: ${dbSession.sessionId}`);
+                    console.log(`Re-hydrating session for API Key: ${(0, redact_secrets_1.redactApiKey)(apiKey)}, sessionId: ${dbSession.sessionId}`);
                     session = {
                         sessionId: dbSession.sessionId,
                         lastWrite: now,

package/package.json

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