fraim-framework 2.0.197 → 2.0.198

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

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
+exports.configureFraimForHubAgent = configureFraimForHubAgent;
 exports.findAvailablePort = findAvailablePort;
 exports.findAvailablePortExcluding = findAvailablePortExcluding;
 const express_1 = __importDefault(require("express"));
@@ -862,6 +863,37 @@ function hubAgentOption(hubId) {
     const frId = HUB_TO_FIRST_RUN_ID[hubId];
     return frId ? types_1.FIRST_RUN_AGENT_OPTIONS.find((o) => o.id === frId) : undefined;
 }
+/**
+ * Issue #747: after the Hub installs an agent CLI, run the `add-ide` command for that agent so the
+ * FRAIM MCP (plus slash commands / rules) is wired into its config and its first run works.
+ * Previously the install only ran `npm install -g` + a version probe, so the agent launched with
+ * no `fraim` MCP server. This invokes the same `runAddIDE` the `fraim add-ide` CLI runs — scoped to
+ * the just-installed agent — rather than re-implementing the MCP-config write.
+ *
+ * `runAddIDE` reads the FRAIM key from ~/.fraim/config.json (written by setup/first-run) and
+ * `process.exit(1)`s when it is missing. We guard on that here via the exported `loadGlobalConfig`
+ * so a missing key degrades to a logged no-op instead of terminating the long-running Hub server.
+ * `skipTokenPrompts` keeps the run fully non-interactive.
+ */
+async function configureFraimForHubAgent(hubId) {
+    const frId = HUB_TO_FIRST_RUN_ID[hubId];
+    if (!frId)
+        return { configured: false, error: `Unknown hub agent: ${hubId}` };
+    try {
+        const { runAddIDE, loadGlobalConfig } = await Promise.resolve().then(() => __importStar(require('../cli/commands/add-ide')));
+        const config = await loadGlobalConfig();
+        if (!config?.fraimKey) {
+            return { configured: false, error: 'No FRAIM key in ~/.fraim/config.json; run `fraim setup` first.' };
+        }
+        // `frId` (e.g. 'claude-code', 'codex', 'gemini-cli', 'copilot-cli') is a valid add-ide
+        // `--ide` name/alias; runAddIDE resolves and configures it even when not yet detected.
+        await runAddIDE({ ide: frId, skipTokenPrompts: true });
+        return { configured: true, ideName: frId };
+    }
+    catch (e) {
+        return { configured: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
 function hubCommandVersion(command, extraBinDirs) {
     const executable = process.platform === 'win32' ? 'cmd.exe' : command;
     const args = process.platform === 'win32'
@@ -2529,12 +2561,19 @@ class AiHubServer {
                 if (!ver) {
                     throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH.`);
                 }
+                // Issue #747: run `add-ide` for the newly installed agent so the FRAIM MCP is wired in
+                // and its first run works (previously the agent launched with no `fraim` MCP server).
+                const mcp = await configureFraimForHubAgent(hubId);
+                if (!mcp.configured) {
+                    console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for ${option.label}: ${mcp.error || 'unknown reason'}`);
+                }
                 return res.json({
                     ok: true,
                     message: `${option.label} installed successfully.`,
                     needsLogin: true,
                     loginCommand: option.loginCommand,
                     loginHint: `Sign in to ${option.label} to activate it. A terminal window will open — complete sign-in there, then click "Check if Ready".`,
+                    fraimConfigured: mcp.configured,
                 });
             }
             catch (error) {

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

@@ -0,0 +1,283 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAIM_PROXY_LOG_FILE = exports.DEFAULT_FRAIM_REMOTE_URL = void 0;
+exports.fingerprintSecret = fingerprintSecret;
+exports.appendLimited = appendLimited;
+exports.sanitizeDiagnosticText = sanitizeDiagnosticText;
+exports.readFileTailUtf8 = readFileTailUtf8;
+exports.buildAgentDebugSteps = buildAgentDebugSteps;
+exports.interpretationForClassification = interpretationForClassification;
+exports.analyzeFraimProxyLog = analyzeFraimProxyLog;
+exports.diagnoseFraimServerConfigConsistency = diagnoseFraimServerConfigConsistency;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+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)
+    };
+}
+function normalizeUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+function appendLimited(current, chunk, maxChars = 8000) {
+    const next = current + chunk;
+    return next.length > maxChars ? next.slice(-maxChars) : next;
+}
+function sanitizeDiagnosticText(text, knownSecrets = []) {
+    let sanitized = text;
+    for (const secret of knownSecrets.filter(Boolean)) {
+        sanitized = sanitized.split(secret).join(`${secret.slice(0, 10)}...`);
+    }
+    return sanitized.replace(/fraim_[A-Za-z0-9_-]+/g, (match) => `${match.slice(0, 10)}...`);
+}
+function readFileTailUtf8(filePath, maxBytes = 256 * 1024) {
+    const stat = fs_1.default.statSync(filePath);
+    const fileSize = stat.size;
+    const bytesToRead = Math.min(fileSize, maxBytes);
+    const buffer = Buffer.alloc(bytesToRead);
+    const fd = fs_1.default.openSync(filePath, 'r');
+    try {
+        fs_1.default.readSync(fd, buffer, 0, bytesToRead, Math.max(0, fileSize - bytesToRead));
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    return {
+        content: buffer.toString('utf8'),
+        bytesRead: bytesToRead,
+        fileSize
+    };
+}
+function buildAgentDebugSteps(classification) {
+    switch (classification) {
+        case 'no-log-file':
+            return [
+                'Run the MCP client once, then inspect the FRAIM proxy log path from this diagnostic.',
+                'If the log file is still absent, the IDE is not launching the FRAIM stdio proxy.'
+            ];
+        case 'no-recent-proxy-lines':
+            return [
+                'No recent FRAIM proxy lifecycle lines were found. Restart the IDE and trigger one FRAIM tool call.',
+                'Then rerun: fraim doctor --test-mcp --json.'
+            ];
+        case 'no-log-lines-for-expected-key':
+            return [
+                'Recent proxy log lines belong to a different API key than the key doctor resolved.',
+                'Check the IDE MCP config env.FRAIM_API_KEY and regenerate it with: fraim add-ide.'
+            ];
+        case 'local-proxy-started-not-ready':
+            return [
+                'The FRAIM stdio proxy started but did not reach the ready state.',
+                'Inspect stderr and the proxy log for startup errors before changing server settings.'
+            ];
+        case 'local-proxy-ready-no-initialize':
+            return [
+                'The FRAIM stdio proxy was ready, but the IDE MCP client did not send initialize/tools traffic.',
+                'Check whether the IDE loaded the correct MCP settings file, then fully restart the IDE.'
+            ];
+        case 'stdio-closed-before-request':
+            return [
+                'The IDE launched the FRAIM stdio proxy and closed stdin before sending an MCP request.',
+                'Check the MCP server command/args shape and whether the IDE rejected the stdio process during startup.'
+            ];
+        case 'message-processing-failed':
+            return [
+                'The local proxy received malformed or unsupported stdio input.',
+                'Check whether the MCP client is using newline-delimited JSON-RPC stdio, not HTTP/SSE configuration.'
+            ];
+        case 'remote-request-failed':
+            return [
+                'The local proxy did send a request, but the remote server rejected or failed it.',
+                'Use the request id and remote status in details to correlate with production logs.'
+            ];
+        case 'local-proxy-forwarded-to-remote':
+            return [
+                'The local proxy sent MCP traffic to the remote server.',
+                'If the IDE still reports disconnected, inspect the IDE-side MCP/tool-discovery logs after the remote response.'
+            ];
+        default:
+            return [
+                'The proxy log did not match a known failure pattern.',
+                'Collect the last 200 proxy log lines and rerun doctor with --json for structured details.'
+            ];
+    }
+}
+function interpretationForClassification(classification) {
+    switch (classification) {
+        case 'no-log-file':
+            return 'No FRAIM proxy log exists, so no local proxy startup has been observed on this machine.';
+        case 'no-recent-proxy-lines':
+            return 'A proxy log exists, but it does not contain usable recent FRAIM lifecycle lines.';
+        case 'no-log-lines-for-expected-key':
+            return 'The local proxy log has recent activity, but not for the API key doctor resolved for this run.';
+        case 'local-proxy-started-not-ready':
+            return 'The local proxy appears to have started but did not finish startup.';
+        case 'local-proxy-ready-no-initialize':
+            return 'The local proxy started successfully, but no MCP initialize/tools request reached it.';
+        case 'stdio-closed-before-request':
+            return 'The MCP client opened the local proxy process but closed stdio before any request was processed.';
+        case 'message-processing-failed':
+            return 'The local proxy received input but could not parse/process it as MCP JSON-RPC.';
+        case 'remote-request-failed':
+            return 'The local proxy reached the remote MCP endpoint, and the failure is now remote/auth/network-side.';
+        case 'local-proxy-forwarded-to-remote':
+            return 'The local proxy has forwarded MCP traffic to the remote endpoint.';
+        default:
+            return 'The proxy log did not match a known FRAIM MCP startup pattern.';
+    }
+}
+function analyzeFraimProxyLog(logContent, options = {}) {
+    const maxLines = options.maxLines ?? 300;
+    const allLines = logContent.split(/\r?\n/).map(line => line.trim()).filter(Boolean).slice(-maxLines);
+    if (allLines.length === 0) {
+        const classification = 'no-recent-proxy-lines';
+        return {
+            classification,
+            interpretation: interpretationForClassification(classification),
+            agentDebugSteps: buildAgentDebugSteps(classification),
+            matchingLineCount: 0,
+            startingSeen: false,
+            readySeen: false,
+            stdinClosedSeen: false,
+            parseErrorCount: 0,
+            proxyingCount: 0,
+            remoteFailureCount: 0
+        };
+    }
+    const keyLineRegex = /^\S+\s+\[([^\]]+)\]\s+(.*)$/;
+    const matchingLines = options.expectedKey
+        ? allLines.filter(line => keyLineRegex.exec(line)?.[1] === options.expectedKey)
+        : allLines;
+    if (options.expectedKey && matchingLines.length === 0) {
+        const classification = 'no-log-lines-for-expected-key';
+        return {
+            classification,
+            interpretation: interpretationForClassification(classification),
+            agentDebugSteps: buildAgentDebugSteps(classification),
+            matchingLineCount: 0,
+            startingSeen: false,
+            readySeen: false,
+            stdinClosedSeen: false,
+            parseErrorCount: 0,
+            proxyingCount: 0,
+            remoteFailureCount: 0
+        };
+    }
+    let startingSeen = false;
+    let readySeen = false;
+    let stdinClosedSeen = false;
+    let parseErrorCount = 0;
+    let proxyingCount = 0;
+    let remoteFailureCount = 0;
+    let lastTimestamp;
+    let lastMethod;
+    let lastRemoteUrl;
+    let lastRemoteStatus;
+    for (const line of matchingLines) {
+        const timestamp = line.split(/\s+/, 1)[0];
+        if (timestamp)
+            lastTimestamp = timestamp;
+        if (line.includes('FRAIM Local MCP Server starting'))
+            startingSeen = true;
+        if (line.includes('FRAIM Local MCP Server ready'))
+            readySeen = true;
+        if (line.includes('Stdin closed'))
+            stdinClosedSeen = true;
+        if (line.includes('Message processing failed'))
+            parseErrorCount += 1;
+        const proxyingMatch = line.match(/\[req:([^\]]+)\]\s+Proxying\s+([^\s]+)\s+to\s+([^\s]+)/);
+        if (proxyingMatch) {
+            proxyingCount += 1;
+            lastMethod = proxyingMatch[2];
+            lastRemoteUrl = proxyingMatch[3];
+        }
+        const remoteFailureMatch = line.match(/\[req:[^\]]+\]\s+Remote request failed\s+\(([^)]*)\):/);
+        if (remoteFailureMatch) {
+            remoteFailureCount += 1;
+            lastRemoteStatus = remoteFailureMatch[1];
+        }
+    }
+    let classification = 'unknown';
+    if (parseErrorCount > 0) {
+        classification = 'message-processing-failed';
+    }
+    else if (remoteFailureCount > 0) {
+        classification = 'remote-request-failed';
+    }
+    else if (proxyingCount > 0) {
+        classification = 'local-proxy-forwarded-to-remote';
+    }
+    else if (stdinClosedSeen) {
+        classification = 'stdio-closed-before-request';
+    }
+    else if (readySeen) {
+        classification = 'local-proxy-ready-no-initialize';
+    }
+    else if (startingSeen) {
+        classification = 'local-proxy-started-not-ready';
+    }
+    return {
+        classification,
+        interpretation: interpretationForClassification(classification),
+        agentDebugSteps: buildAgentDebugSteps(classification),
+        matchingLineCount: matchingLines.length,
+        startingSeen,
+        readySeen,
+        stdinClosedSeen,
+        parseErrorCount,
+        proxyingCount,
+        remoteFailureCount,
+        lastTimestamp,
+        lastMethod,
+        lastRemoteUrl,
+        lastRemoteStatus
+    };
+}
+function diagnoseFraimServerConfigConsistency(fraimServer, options = {}) {
+    const configuredKey = fraimServer?.env?.FRAIM_API_KEY ? String(fraimServer.env.FRAIM_API_KEY) : '';
+    const configuredRemoteUrl = String(fraimServer?.env?.FRAIM_REMOTE_URL || exports.DEFAULT_FRAIM_REMOTE_URL);
+    const expectedRemoteUrl = options.expectedRemoteUrl || process.env.FRAIM_REMOTE_URL || exports.DEFAULT_FRAIM_REMOTE_URL;
+    const apiKeyMatchesExpected = options.expectedApiKey && configuredKey
+        ? configuredKey === options.expectedApiKey
+        : null;
+    const remoteUrlMatchesExpected = normalizeUrl(configuredRemoteUrl) === normalizeUrl(expectedRemoteUrl);
+    const isLocalRemote = configuredRemoteUrl.includes('localhost') || configuredRemoteUrl.includes('127.0.0.1');
+    const details = {
+        apiKeyMatchesExpected,
+        remoteUrlMatchesExpected,
+        configuredRemoteUrl,
+        expectedRemoteUrl,
+        configuredKeyFingerprint: configuredKey ? fingerprintSecret(configuredKey) : null,
+        expectedKeyFingerprint: options.expectedApiKey ? fingerprintSecret(options.expectedApiKey) : null
+    };
+    const issues = [];
+    if (apiKeyMatchesExpected === false) {
+        issues.push('configured FRAIM_API_KEY differs from the key resolved by doctor');
+    }
+    if (!remoteUrlMatchesExpected) {
+        issues.push('configured FRAIM_REMOTE_URL differs from the expected remote URL');
+    }
+    if (isLocalRemote) {
+        issues.push('configured FRAIM_REMOTE_URL points at a local server');
+    }
+    if (issues.length === 0) {
+        return {
+            status: 'passed',
+            message: 'FRAIM MCP config key and remote URL are consistent',
+            details
+        };
+    }
+    return {
+        status: 'warning',
+        message: `FRAIM MCP config consistency warning: ${issues.join('; ')}`,
+        suggestion: 'Regenerate IDE MCP settings with: fraim add-ide',
+        details
+    };
+}

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

@@ -56,11 +56,51 @@ const toml = __importStar(require("toml"));
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
 const command_resolution_1 = require("../../mcp/command-resolution");
+const fraim_mcp_diagnostics_1 = require("./fraim-mcp-diagnostics");
 // Cache the npm major version so execFileSync is called at most once per process.
 // Without caching, each IDE config check calls diagnoseFraimMcpLaunchPlan which calls
 // getNpmMajorVersion, and execFileSync blocks the event loop for ~2s on Windows.
 // With 8+ IDE checks running via Promise.all the blocking stacks sequentially.
 let _npmMajorVersionCache = undefined;
+function getGlobalFraimConfigPath() {
+    return path_1.default.join(os_1.default.homedir(), '.fraim', 'config.json');
+}
+function resolveFraimApiKeyForDiagnostics() {
+    const configPath = getGlobalFraimConfigPath();
+    if (process.env.FRAIM_API_KEY) {
+        return {
+            present: true,
+            source: 'env',
+            configPath,
+            apiKey: process.env.FRAIM_API_KEY,
+            fingerprint: (0, fraim_mcp_diagnostics_1.fingerprintSecret)(process.env.FRAIM_API_KEY)
+        };
+    }
+    try {
+        if (!fs_1.default.existsSync(configPath)) {
+            return { present: false, source: 'missing', configPath };
+        }
+        const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        if (config.apiKey) {
+            return {
+                present: true,
+                source: 'global-config',
+                configPath,
+                apiKey: String(config.apiKey),
+                fingerprint: (0, fraim_mcp_diagnostics_1.fingerprintSecret)(String(config.apiKey))
+            };
+        }
+        return { present: false, source: 'missing', configPath };
+    }
+    catch (error) {
+        return {
+            present: false,
+            source: 'config-error',
+            configPath,
+            error: error.message
+        };
+    }
+}
 function getNpmMajorVersion() {
     if (_npmMajorVersionCache !== undefined) {
         return _npmMajorVersionCache;
@@ -130,7 +170,7 @@ async function testFraimConnectivity() {
                 }
             };
         }
-        const globalConfigPath = path_1.default.join(os_1.default.homedir(), '.fraim', 'config.json');
+        const globalConfigPath = getGlobalFraimConfigPath();
         let apiKey;
         try {
             const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
@@ -164,7 +204,7 @@ async function testFraimConnectivity() {
         }
         // Test connectivity by making a request to the FRAIM server
         const startTime = Date.now();
-        const remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        const remoteUrl = process.env.FRAIM_REMOTE_URL || fraim_mcp_diagnostics_1.DEFAULT_FRAIM_REMOTE_URL;
         // Debug: Log what we're testing (helpful for troubleshooting)
         if (process.env.DEBUG_DOCTOR) {
             console.log('[DOCTOR DEBUG] Testing FRAIM connectivity:');
@@ -401,6 +441,24 @@ async function validateIDEMCPConfig(ide) {
                 }
             };
         }
+        if (fraimServer.command) {
+            const keyDiagnostic = resolveFraimApiKeyForDiagnostics();
+            const consistencyDiagnostic = (0, fraim_mcp_diagnostics_1.diagnoseFraimServerConfigConsistency)(fraimServer, {
+                expectedApiKey: keyDiagnostic.apiKey,
+                expectedRemoteUrl: process.env.FRAIM_REMOTE_URL || fraim_mcp_diagnostics_1.DEFAULT_FRAIM_REMOTE_URL
+            });
+            if (consistencyDiagnostic.status !== 'passed') {
+                return {
+                    ...consistencyDiagnostic,
+                    details: {
+                        ...consistencyDiagnostic.details,
+                        configPath,
+                        keySource: keyDiagnostic.source,
+                        keyConfigPath: keyDiagnostic.configPath
+                    }
+                };
+            }
+        }
         // Check for auth header (for HTTP servers)
         if (fraimServer.url) {
             const hasAuth = fraimServer.headers?.Authorization || fraimServer.http_headers?.Authorization;
@@ -432,6 +490,84 @@ async function validateIDEMCPConfig(ide) {
         };
     }
 }
+async function testFraimLocalProxyTroubleshooting() {
+    if (process.env.NODE_ENV === 'test') {
+        return {
+            status: 'warning',
+            message: 'FRAIM local proxy troubleshooting skipped (test mode)',
+            details: {
+                testMode: true,
+                skipped: true,
+                diagnosticVersion: 'fraim-mcp-startup-v1'
+            }
+        };
+    }
+    const keyDiagnostic = resolveFraimApiKeyForDiagnostics();
+    const logPath = path_1.default.join(os_1.default.tmpdir(), fraim_mcp_diagnostics_1.FRAIM_PROXY_LOG_FILE);
+    if (!keyDiagnostic.present || !keyDiagnostic.apiKey) {
+        return {
+            status: 'error',
+            message: 'FRAIM local proxy troubleshooting cannot resolve an API key',
+            suggestion: keyDiagnostic.source === 'config-error'
+                ? `Fix JSON syntax in ${keyDiagnostic.configPath}`
+                : 'Run: fraim setup or set FRAIM_API_KEY before running MCP diagnostics',
+            details: {
+                diagnosticVersion: 'fraim-mcp-startup-v1',
+                keySource: keyDiagnostic.source,
+                keyConfigPath: keyDiagnostic.configPath,
+                keyError: keyDiagnostic.error
+            }
+        };
+    }
+    if (!fs_1.default.existsSync(logPath)) {
+        const classification = 'no-log-file';
+        return {
+            status: 'warning',
+            message: 'FRAIM local proxy log not found',
+            suggestion: (0, fraim_mcp_diagnostics_1.buildAgentDebugSteps)(classification)[0],
+            details: {
+                diagnosticVersion: 'fraim-mcp-startup-v1',
+                classification,
+                interpretation: (0, fraim_mcp_diagnostics_1.interpretationForClassification)(classification),
+                agentDebugSteps: (0, fraim_mcp_diagnostics_1.buildAgentDebugSteps)(classification),
+                logPath,
+                keySource: keyDiagnostic.source,
+                keyFingerprint: keyDiagnostic.fingerprint
+            }
+        };
+    }
+    const logTail = (0, fraim_mcp_diagnostics_1.readFileTailUtf8)(logPath);
+    const analysis = (0, fraim_mcp_diagnostics_1.analyzeFraimProxyLog)(logTail.content, {
+        expectedKey: keyDiagnostic.apiKey,
+        maxLines: 300
+    });
+    const errorClassifications = [
+        'message-processing-failed',
+        'remote-request-failed'
+    ];
+    const passedClassifications = [
+        'local-proxy-forwarded-to-remote'
+    ];
+    const status = errorClassifications.includes(analysis.classification)
+        ? 'error'
+        : passedClassifications.includes(analysis.classification)
+            ? 'passed'
+            : 'warning';
+    return {
+        status,
+        message: `FRAIM local proxy diagnostic: ${analysis.interpretation}`,
+        suggestion: status === 'passed' ? undefined : analysis.agentDebugSteps[0],
+        details: {
+            diagnosticVersion: 'fraim-mcp-startup-v1',
+            logPath,
+            logBytesRead: logTail.bytesRead,
+            logFileSize: logTail.fileSize,
+            keySource: keyDiagnostic.source,
+            keyFingerprint: keyDiagnostic.fingerprint,
+            ...analysis
+        }
+    };
+}
 // ============================================================
 // Issue #532: Stdio MCP Runtime Connectivity Check
 // ============================================================
@@ -447,6 +583,8 @@ const STDIO_HANDSHAKE_TIMEOUT_MS = 15000;
 async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIMEOUT_MS) {
     return new Promise((resolve) => {
         const startTime = Date.now();
+        const keyDiagnostic = resolveFraimApiKeyForDiagnostics();
+        const knownSecrets = keyDiagnostic.apiKey ? [keyDiagnostic.apiKey] : [];
         let spawnCommand;
         let spawnArgs;
         // spawnOptions is typed loosely so we can set windowsVerbatimArguments below.
@@ -492,14 +630,34 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
             });
             return;
         }
+        let settled = false;
+        let initializeResponse = null;
+        let toolsListResponse = null;
+        const settle = (result, killChild = false) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killChild) {
+                try {
+                    child.stdin?.end();
+                }
+                catch { /* best effort */ }
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* best effort */ }
+            }
+            resolve(result);
+        };
         const timer = setTimeout(() => {
             try {
                 child.kill('SIGKILL');
             }
             catch { /* best effort */ }
-            resolve({
+            settle({
                 status: 'error',
-                phase: 'initialize',
+                phase: initializeResponse ? 'tools-list' : 'initialize',
                 message: `MCP server did not respond within ${timeoutMs}ms`,
                 suggestion: 'The server may be slow to start. Check that the package is installed and npx cache is warm.',
                 details: { command, args, timeoutMs, elapsed: Date.now() - startTime }
@@ -507,46 +665,89 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
         }, timeoutMs);
         let stderrBuffer = '';
         let stdoutBuffer = '';
+        let stdoutLineBuffer = '';
         let spawnError = null;
         child.stderr?.on('data', (d) => {
-            stderrBuffer += d.toString();
+            stderrBuffer = (0, fraim_mcp_diagnostics_1.appendLimited)(stderrBuffer, d.toString());
         });
         child.on('error', (err) => {
             spawnError = err;
         });
+        const handleStdoutLine = (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            try {
+                const msg = JSON.parse(trimmed);
+                if (msg?.id === 1 && msg?.result !== undefined) {
+                    initializeResponse = msg;
+                }
+                if (msg?.id === 2 && msg?.result !== undefined) {
+                    toolsListResponse = msg;
+                }
+                if (initializeResponse && toolsListResponse) {
+                    const toolCount = Array.isArray(toolsListResponse.result?.tools)
+                        ? toolsListResponse.result.tools.length
+                        : 0;
+                    const elapsed = Date.now() - startTime;
+                    settle({
+                        status: 'passed',
+                        message: `MCP server responded with ${toolCount} tool(s) in ${elapsed}ms`,
+                        details: { command, args, toolCount, elapsed }
+                    }, true);
+                }
+            }
+            catch {
+                // Ignore non-JSON lines (e.g., startup log output)
+            }
+        };
         child.stdout?.on('data', (d) => {
-            stdoutBuffer += d.toString();
+            const chunk = d.toString();
+            stdoutBuffer = (0, fraim_mcp_diagnostics_1.appendLimited)(stdoutBuffer, chunk);
+            stdoutLineBuffer += chunk;
+            let newlineIndex;
+            while ((newlineIndex = stdoutLineBuffer.indexOf('\n')) !== -1) {
+                const line = stdoutLineBuffer.slice(0, newlineIndex);
+                stdoutLineBuffer = stdoutLineBuffer.slice(newlineIndex + 1);
+                handleStdoutLine(line);
+            }
         });
         child.on('close', (code) => {
+            if (settled)
+                return;
             clearTimeout(timer);
             if (spawnError) {
                 const msg = spawnError.message || '';
                 const isEnoent = msg.includes('ENOENT') || msg.includes('not found');
-                resolve({
+                settle({
                     status: 'error',
                     phase: 'spawn',
                     message: `Failed to start MCP server: ${msg}`,
                     suggestion: isEnoent
                         ? 'Verify that npx is installed. Run: npm install -g npm to update npm/npx.'
                         : 'Check that the required package can be installed via npx.',
-                    details: { command, args, error: msg }
+                    details: { command, args, error: (0, fraim_mcp_diagnostics_1.sanitizeDiagnosticText)(msg, knownSecrets) }
                 });
                 return;
             }
             if (code !== 0 && stdoutBuffer.trim() === '') {
-                resolve({
+                settle({
                     status: 'error',
                     phase: 'spawn',
                     message: `MCP server exited with code ${code} before responding`,
                     suggestion: 'Run: npx -y <package> manually to check for installation errors.',
-                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                    details: { command, args, exitCode: code, stderr: (0, fraim_mcp_diagnostics_1.sanitizeDiagnosticText)(stderrBuffer.slice(-1000), knownSecrets) }
                 });
                 return;
             }
-            // Parse all JSON-RPC messages received from stdout
+            if (stdoutLineBuffer.trim()) {
+                handleStdoutLine(stdoutLineBuffer);
+            }
+            if (settled)
+                return;
+            // Parse all JSON-RPC messages received from stdout as a fallback for servers
+            // that closed without a trailing newline.
             const lines = stdoutBuffer.split('\n').map((l) => l.trim()).filter(Boolean);
-            let initializeResponse = null;
-            let toolsListResponse = null;
             for (const line of lines) {
                 try {
                     const msg = JSON.parse(line);
@@ -562,17 +763,17 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
                 }
             }
             if (!initializeResponse) {
-                resolve({
+                settle({
                     status: 'error',
                     phase: 'initialize',
                     message: 'MCP server did not return a valid initialize response',
                     suggestion: 'The server may have crashed during startup. Check stderr for error details.',
-                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                    details: { command, args, exitCode: code, stderr: (0, fraim_mcp_diagnostics_1.sanitizeDiagnosticText)(stderrBuffer.slice(-1000), knownSecrets) }
                 });
                 return;
             }
             if (!toolsListResponse) {
-                resolve({
+                settle({
                     status: 'error',
                     phase: 'tools-list',
                     message: 'MCP server did not respond to tools/list',
@@ -585,7 +786,7 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
                 ? toolsListResponse.result.tools.length
                 : 0;
             const elapsed = Date.now() - startTime;
-            resolve({
+            settle({
                 status: 'passed',
                 message: `MCP server responded with ${toolCount} tool(s) in ${elapsed}ms`,
                 details: { command, args, toolCount, elapsed }
@@ -611,7 +812,6 @@ async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIME
                 params: {}
             }) + '\n';
             child.stdin?.write(toolsMsg);
-            child.stdin?.end();
         }
         catch {
             // stdin may not be writable if the process exited immediately
@@ -686,6 +886,12 @@ function getMCPConnectivityChecks() {
         critical: true,
         run: testFraimConnectivity
     });
+    checks.push({
+        name: 'FRAIM local proxy troubleshooting',
+        category: 'mcpConnectivity',
+        critical: false,
+        run: testFraimLocalProxyTroubleshooting
+    });
     // Check 2: Validate each installed IDE's MCP config
     const installedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
     for (const ide of installedIDEs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.197",
+  "version": "2.0.198",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
   "bin": {