fraim-framework 2.0.196 → 2.0.198

package/dist/src/ai-hub/brand-store.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LOGO_BYTES = exports.ORG_BRAND_FILENAME = void 0;
+exports.resolveBrandColor = resolveBrandColor;
+exports.relativeLuminance = relativeLuminance;
+exports.contrastRatio = contrastRatio;
+exports.hasSufficientContrast = hasSufficientContrast;
+exports.sanitizeSvg = sanitizeSvg;
+exports.sanitizeLogo = sanitizeLogo;
+exports.normalizeBrand = normalizeBrand;
+exports.serializeBrand = serializeBrand;
+exports.parseBrand = parseBrand;
+exports.readBrandFromDir = readBrandFromDir;
+exports.writeBrandToDir = writeBrandToDir;
+/**
+ * Org brand store — Issue #744 (Hub cobranding).
+ *
+ * Deterministic, dependency-free, AI-free logic (architecture-standards §1/§3):
+ * the org brand descriptor (company name, color, logo) is stored ALONGSIDE
+ * company info, in the same org context storage as `org_context.md`
+ * (manager directive, spec R7.4), as a single `org_brand.json` file.
+ *
+ * Security: a manager-supplied logo is a stored-XSS vector. `sanitizeSvg` uses a
+ * strict element/attribute allowlist (not a denylist) and drops scripts, event
+ * handlers, external references, styles, and any non-graphical element, so the
+ * stored logo is safe to inline in the Hub (spec Compliance: SOC2/ISO27001).
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** File name of the brand descriptor, stored next to org_context.md. */
+exports.ORG_BRAND_FILENAME = 'org_brand.json';
+/** Max stored logo size (sanitized SVG markup or data: URI), in bytes. */
+exports.MAX_LOGO_BYTES = 512 * 1024;
+// ── Color ───────────────────────────────────────────────────────────────────
+/**
+ * Normalize a hex color to lowercase `#rrggbb`, expanding `#rgb`. Returns null
+ * for anything that is not a valid 3- or 6-digit hex (named colors, functions,
+ * and injection attempts are rejected).
+ */
+function resolveBrandColor(input) {
+    if (typeof input !== 'string')
+        return null;
+    const raw = input.trim().replace(/^#/, '').toLowerCase();
+    if (/^[0-9a-f]{3}$/.test(raw)) {
+        return '#' + raw.split('').map((c) => c + c).join('');
+    }
+    if (/^[0-9a-f]{6}$/.test(raw)) {
+        return '#' + raw;
+    }
+    return null;
+}
+function hexToRgb(hex) {
+    const norm = resolveBrandColor(hex);
+    if (!norm)
+        return null;
+    const n = norm.slice(1);
+    return [parseInt(n.slice(0, 2), 16), parseInt(n.slice(2, 4), 16), parseInt(n.slice(4, 6), 16)];
+}
+/** WCAG relative luminance of an sRGB color. */
+function relativeLuminance(hex) {
+    const rgb = hexToRgb(hex);
+    if (!rgb)
+        return 0;
+    const [r, g, b] = rgb.map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG contrast ratio between two colors (1..21). */
+function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * True when `color` is readable as a UI accent against `background`. Uses the
+ * WCAG 3:1 threshold for graphical/large UI objects (the accent is used on
+ * filled buttons and tab underlines, not as body text). Guards R2.3 so an
+ * unreadable brand color never ships; callers fall back to the FRAIM accent.
+ */
+function hasSufficientContrast(color, background, min = 3.0) {
+    if (!resolveBrandColor(color) || !resolveBrandColor(background))
+        return false;
+    return contrastRatio(color, background) >= min;
+}
+// ── SVG sanitization (allowlist) ──────────────────────────────────────────────
+/** Only these elements survive sanitization. */
+const ALLOWED_SVG_TAGS = new Set([
+    'svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon',
+    'text', 'tspan', 'defs', 'lineargradient', 'radialgradient', 'stop', 'title', 'desc',
+]);
+/** Only these attributes survive; everything else (incl. on*, href, style) is dropped. */
+const ALLOWED_SVG_ATTRS = new Set([
+    'viewbox', 'xmlns', 'width', 'height', 'fill', 'fill-rule', 'fill-opacity', 'stroke',
+    'stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-dasharray', 'stroke-opacity',
+    'opacity', 'd', 'points', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'r', 'rx', 'ry',
+    'transform', 'offset', 'stop-color', 'stop-opacity', 'gradientunits', 'gradienttransform',
+    'font-family', 'font-size', 'font-weight', 'text-anchor', 'letter-spacing',
+]);
+/**
+ * Sanitize an SVG string via a strict allowlist. Returns safe SVG markup, or ''
+ * if the input is not an <svg> document. Removes: <script>, <foreignObject>,
+ * <image>, <use>, <a>, comments/PIs/DOCTYPE, all event handlers, all href /
+ * xlink:href, inline styles, and any element or attribute not on the allowlist.
+ */
+function sanitizeSvg(input) {
+    if (typeof input !== 'string')
+        return '';
+    // Bound the work up front so a pathological logo can't drive the tag-walk
+    // regex into catastrophic backtracking (DoS guard).
+    if (input.length > exports.MAX_LOGO_BYTES)
+        return '';
+    let s = input.trim();
+    if (!/^<svg[\s>]/i.test(s))
+        return '';
+    // Drop comments, CDATA, processing instructions, and DOCTYPE outright.
+    s = s.replace(/<!--[\s\S]*?-->/g, '');
+    s = s.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+    s = s.replace(/<\?[\s\S]*?\?>/g, '');
+    s = s.replace(/<!DOCTYPE[\s\S]*?>/gi, '');
+    // Drop dangerous elements and their entire content.
+    s = s.replace(/<(script|style|foreignObject|iframe|use|image|a)\b[\s\S]*?<\/\1\s*>/gi, '');
+    // Drop self-closing / unclosed variants of the same dangerous elements.
+    s = s.replace(/<(script|style|foreignObject|iframe|use|image|a)\b[^>]*\/?>/gi, '');
+    // Walk every remaining tag; drop non-allowlisted elements and attributes.
+    s = s.replace(/<\/?([a-zA-Z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g, (full, rawName, rawAttrs) => {
+        const name = rawName.toLowerCase().replace(/^svg:/, '');
+        if (!ALLOWED_SVG_TAGS.has(name))
+            return '';
+        const isClose = /^<\//.test(full);
+        if (isClose)
+            return `</${name}>`;
+        const selfClose = /\/>$/.test(full);
+        const attrs = [];
+        const attrRe = /([a-zA-Z_:][\w:.-]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
+        let m;
+        while ((m = attrRe.exec(rawAttrs)) !== null) {
+            const attr = m[1].toLowerCase().replace(/^xml:/, '');
+            const value = m[3] !== undefined ? m[3] : m[4] || '';
+            if (!ALLOWED_SVG_ATTRS.has(attr))
+                continue;
+            // Defense in depth: never allow url()/javascript:/data: sneaking through a value.
+            if (/javascript:|url\s*\(|data:|expression\s*\(|<|>/i.test(value))
+                continue;
+            attrs.push(`${attr}="${value.replace(/"/g, '&quot;')}"`);
+        }
+        const attrStr = attrs.length ? ' ' + attrs.join(' ') : '';
+        return `<${name}${attrStr}${selfClose ? '/' : ''}>`;
+    });
+    // If sanitization emptied the root, treat as invalid.
+    if (!/^<svg[\s>]/i.test(s.trim()))
+        return '';
+    return s.trim();
+}
+/** Accept only png/jpeg data URIs (sanitized SVG is handled separately). */
+function isSafeRasterDataUri(s) {
+    return /^data:image\/(png|jpe?g);base64,[a-z0-9+/=\s]+$/i.test(s);
+}
+/** Sanitize a logo value: SVG markup -> sanitized SVG; png/jpeg data URI -> kept; else ''. */
+function sanitizeLogo(input) {
+    if (typeof input !== 'string' || !input.trim())
+        return '';
+    const s = input.trim();
+    if (/^<svg[\s>]/i.test(s)) {
+        const clean = sanitizeSvg(s);
+        return clean.length <= exports.MAX_LOGO_BYTES ? clean : '';
+    }
+    if (isSafeRasterDataUri(s)) {
+        return s.length <= exports.MAX_LOGO_BYTES ? s : '';
+    }
+    return '';
+}
+// ── Serialize / parse ─────────────────────────────────────────────────────────
+/** Normalize + sanitize a brand into its safe stored form. */
+function normalizeBrand(brand) {
+    const out = {};
+    if (typeof brand.name === 'string' && brand.name.trim()) {
+        out.name = brand.name.trim().slice(0, 120);
+    }
+    const color = resolveBrandColor(brand.color);
+    if (color)
+        out.color = color;
+    const logo = sanitizeLogo(brand.logo);
+    if (logo)
+        out.logo = logo;
+    return out;
+}
+function serializeBrand(brand) {
+    return JSON.stringify(normalizeBrand(brand), null, 2);
+}
+/** Parse a brand JSON string into a normalized OrgBrand, or null on any error. */
+function parseBrand(json) {
+    if (typeof json !== 'string' || !json.trim())
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const norm = normalizeBrand(obj);
+    return Object.keys(norm).length ? norm : null;
+}
+// ── Directory read / write ─────────────────────────────────────────────────────
+/** Read + normalize the brand from `<dir>/org_brand.json`, or null when absent/invalid. */
+function readBrandFromDir(dir) {
+    try {
+        const file = path_1.default.join(dir, exports.ORG_BRAND_FILENAME);
+        if (!fs_1.default.existsSync(file))
+            return null;
+        return parseBrand(fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Sanitize + normalize a brand and write it to `<dir>/org_brand.json`. Returns the stored brand. */
+function writeBrandToDir(dir, brand) {
+    const normalized = normalizeBrand(brand);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(dir, exports.ORG_BRAND_FILENAME), JSON.stringify(normalized, null, 2), 'utf8');
+    return normalized;
+}

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"));
@@ -49,6 +50,7 @@ const child_process_1 = require("child_process");
 const https_1 = __importDefault(require("https"));
 const types_1 = require("../first-run/types");
 const learning_context_builder_1 = require("../local-mcp-server/learning-context-builder");
+const brand_store_1 = require("./brand-store");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const catalog_1 = require("./catalog");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
@@ -861,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'
@@ -1447,6 +1480,9 @@ class AiHubServer {
             // #533: the resolved account email, so the profile card shows the real
             // identity (not a hardcoded placeholder) and the client can display it.
             userEmail: getHubUserEmail(),
+            // #744: the org cobrand identity (name/color/logo) from the org context
+            // storage, or null when unset so the Hub falls back to FRAIM identity.
+            orgBrand: (0, learning_context_builder_1.readOrgBrand)(normalizedProjectPath),
             assignments: { byProject: {}, source: 'client-localStorage' },
             // Issue #538 — source of truth for the "Hire a human manager" UI. Lazy-required
             // (not a top-level import) so the lightweight client CLI paths that import this
@@ -2302,7 +2338,15 @@ class AiHubServer {
                 ? path_1.default.resolve(req.query.projectPath)
                 : this.projectPath;
             const known = this.knownProjects(projectPath);
-            const entry = known.find((project) => project.id === req.params.id);
+            // Match by id, falling back to the canonical folderPath. The client and server
+            // hash a path to an id with different algorithms, and the client mints its own id
+            // for the CURRENT project (tfEnsureCurrentProject), so a delete-by-id can carry an
+            // id the server never assigned — the folderPath is the true project identity (#726).
+            const requestedFolderPath = typeof req.query.folderPath === 'string' && req.query.folderPath.length > 0
+                ? req.query.folderPath
+                : null;
+            const entry = known.find((project) => project.id === req.params.id)
+                || (requestedFolderPath ? known.find((project) => sameDirectoryPath(project.folderPath, requestedFolderPath)) : undefined);
             if (!entry)
                 return res.status(404).json({ error: 'Project not found.' });
             // The current projectPath is unconditionally re-injected on every load, so
@@ -2443,6 +2487,45 @@ class AiHubServer {
             // Re-read so the client gets the canonical post-write state (present flips).
             return res.json(readContextFile(projectPath, body.key));
         });
+        // Issue #744 — Hub cobranding.
+        // GET  /api/ai-hub/brand  → { brand: OrgBrand | null } resolved from the org
+        //   context storage (same layering as org_context.md).
+        // POST /api/ai-hub/brand  { name?, color?, logo?, projectPath? }  → sanitizes
+        //   + normalizes (SVG allowlist, hex normalize) and persists org_brand.json to
+        //   the org context write location. Loopback-only; write is constrained under
+        //   a personalized-employee/ directory (same path-traversal guard as context).
+        this.app.get('/api/ai-hub/brand', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            return res.json({ brand: (0, learning_context_builder_1.readOrgBrand)(projectPath) });
+        });
+        this.app.post('/api/ai-hub/brand', (req, res) => {
+            const body = (req.body ?? {});
+            const projectPath = typeof body.projectPath === 'string' && body.projectPath.length > 0
+                ? path_1.default.resolve(body.projectPath)
+                : this.projectPath;
+            const input = {
+                name: typeof body.name === 'string' ? body.name : undefined,
+                color: typeof body.color === 'string' ? body.color : undefined,
+                logo: typeof body.logo === 'string' ? body.logo : undefined,
+            };
+            const dest = path_1.default.resolve((0, learning_context_builder_1.resolveOrgBrandWriteDir)(projectPath));
+            // Path-traversal guard: the write dir must live under a personalized-employee
+            // directory (matches the context write guard; never the managed org cache).
+            if (!dest.split(path_1.default.sep).includes('personalized-employee')) {
+                return res.status(403).json({ error: 'Brand write destination outside personalized-employee.' });
+            }
+            try {
+                // writeBrandToDir sanitizes the logo (SVG allowlist) and normalizes the
+                // color before persisting, so unsafe input never reaches disk.
+                const stored = (0, brand_store_1.writeBrandToDir)(dest, input);
+                return res.json({ brand: stored });
+            }
+            catch (err) {
+                return res.status(500).json({ error: err instanceof Error ? err.message : 'Brand write failed.' });
+            }
+        });
         this.app.post('/api/ai-hub/artifact/open', async (req, res) => {
             const rawPath = typeof req.body?.path === 'string' ? req.body.path : '';
             const projectPath = typeof req.body?.projectPath === 'string' && req.body.projectPath.length > 0
@@ -2478,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
+    };
+}