@cachly-dev/mcp-server 0.9.6 → 0.9.8

package/dist/index.js

@@ -47,7 +47,7 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.9.6';
+const CURRENT_VERSION = '0.9.8';
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
 // When neither is set, we auto-fetch the first running instance once per process.
@@ -2005,18 +2005,20 @@ function recencyBoost(timestampMs) {
  * └─────────────────────────────────────────────────────────────────┘
  */
 async function keywordSearch(redis, patterns, query, topK = 10) {
-    // ── Step 1: Collect and tokenize all documents ──
-    const allKeys = [];
-    for (const pattern of patterns) {
-        const stream = redis.scanStream({ match: pattern, count: 200 });
-        await new Promise((resolve, reject) => {
+    // ── Step 1: Collect all matching keys — patterns scanned in parallel ──
+    const keyBatches = await Promise.all(patterns.map(pattern => {
+        const keys = [];
+        const stream = redis.scanStream({ match: pattern, count: 500 });
+        return new Promise((resolve, reject) => {
             stream.on('data', (batch) => {
-                allKeys.push(...batch.filter((k) => !k.endsWith(':meta')));
+                keys.push(...batch.filter((k) => !k.endsWith(':meta')));
             });
-            stream.on('end', resolve);
+            stream.on('end', () => resolve(keys));
             stream.on('error', reject);
         });
-    }
+    }));
+    // Deduplicate across patterns (a key may match multiple globs)
+    const allKeys = [...new Set(keyBatches.flat())];
     if (allKeys.length === 0)
         return [];
     // Pipeline GET for speed
@@ -2269,12 +2271,32 @@ async function getConnection(instance_id) {
     return client;
 }
 // ── API helper ────────────────────────────────────────────────────────────────
+function jwtExpiryMs(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return payload.exp ? payload.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function apiFetch(path, options = {}) {
     if (!JWT) {
-        throw new McpError(ErrorCode.InvalidRequest, 'CACHLY_JWT env var not set. Get your API token from https://cachly.dev/settings');
+        throw new McpError(ErrorCode.InvalidRequest, 'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>');
+    }
+    // Detect token expiry before making the network call — gives a clearer error
+    const expMs = jwtExpiryMs(JWT);
+    if (expMs !== null && expMs < Date.now()) {
+        const expiredAt = new Date(expMs).toISOString();
+        throw new McpError(ErrorCode.InvalidRequest, `CACHLY_JWT expired at ${expiredAt}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`);
     }
+    const timeoutMs = Number(process.env.CACHLY_API_TIMEOUT_MS ?? 15_000);
     const res = await fetch(`${API_URL}${path}`, {
         ...options,
+        signal: AbortSignal.timeout(timeoutMs),
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${JWT}`,
@@ -2283,7 +2305,14 @@ async function apiFetch(path, options = {}) {
     });
     if (!res.ok) {
         const body = await res.json().catch(() => ({ error: res.statusText }));
-        throw new McpError(ErrorCode.InternalError, `cachly API error ${res.status}: ${body.error ?? res.statusText}`);
+        const detail = body.error ?? res.statusText;
+        if (res.status === 401) {
+            throw new McpError(ErrorCode.InvalidRequest, `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`);
+        }
+        if (res.status === 403) {
+            throw new McpError(ErrorCode.InvalidRequest, `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`);
+        }
+        throw new McpError(ErrorCode.InternalError, `cachly API error ${res.status}: ${detail}`);
     }
     if (res.status === 204)
         return undefined;
@@ -3804,6 +3833,68 @@ const TOOLS = [
             required: ['instance_id'],
         },
     },
+    {
+        name: 'crystal_view',
+        description: 'Inspect the current Memory Crystal — the compressed wisdom distilled from all past sessions. ' +
+            'Shows top patterns per category, lesson count, and when the crystal was last refreshed. ' +
+            'Call after session_start when you want to quickly see accumulated wisdom across all past work.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'Brain instance ID' },
+                show_raw: { type: 'boolean', description: 'Include raw JSON crystal data (default: false)' },
+            },
+            required: ['instance_id'],
+        },
+    },
+    {
+        name: 'compact_recover',
+        description: 'Call FIRST after any context limit hit / compaction. Reconstructs full context from Memory Crystal + ' +
+            'recent sessions + WIP registry + open failures. Returns a condensed briefing so the new context ' +
+            'window starts exactly where the previous one left off — no lost progress.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'Brain instance ID' },
+                focus: { type: 'string', description: 'What you were working on (helps filter relevant context)' },
+            },
+            required: ['instance_id'],
+        },
+    },
+    {
+        name: 'brain_from_git',
+        description: 'Bootstrap brain lessons from git history. Parses commit messages and infers fix/feature/refactor ' +
+            'lessons automatically. Great for onboarding an existing codebase — run once and the brain instantly ' +
+            'knows your team\'s accumulated patterns. Supports limit and branch options.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'Brain instance ID' },
+                repo_path: { type: 'string', description: 'Path to git repository (default: current directory)' },
+                limit: { type: 'number', description: 'Max commits to process (default: 100, max: 500)' },
+                branch: { type: 'string', description: 'Git branch to parse (default: current branch / HEAD)' },
+                since: { type: 'string', description: 'Only commits after this date, e.g. "2024-01-01" (optional)' },
+            },
+            required: ['instance_id'],
+        },
+    },
+    {
+        name: 'brain_predict_failures',
+        description: 'Pre-deploy failure prediction with probability percentages. Given a change context (e.g. ' +
+            '"upgrading Keycloak 21→24" or "deploying Redis 7 to prod"), returns the top likely failure modes ' +
+            'ranked by probability, with pre-loaded fixes. Uses CKG causal edges + lesson history. ' +
+            'Call before any significant deploy, migration, or infrastructure change.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'Brain instance ID' },
+                context: { type: 'string', description: 'What you are about to do, e.g. "upgrading Keycloak 21 to 24"' },
+                top_k: { type: 'number', description: 'Number of failure predictions to return (default: 5)' },
+                format: { type: 'string', enum: ['brief', 'detailed'], description: 'Output format (default: detailed)' },
+            },
+            required: ['instance_id', 'context'],
+        },
+    },
 ];
 // ── Handlers ──────────────────────────────────────────────────────────────────
 function formatInstance(inst) {
@@ -8442,6 +8533,387 @@ smart_recall(
             lines.push('', '---', `**Contribute:** \`fedbrain_contribute(lesson_key="fix:...")\``, `**Search:** \`fedbrain_search(query="...")\``, `**Confirm:** \`fedbrain_confirm(topic="...", outcome="worked")\``);
             return lines.join('\n');
         }
+        // ── crystal_view ──────────────────────────────────────────────────────────
+        case 'crystal_view': {
+            const { instance_id, show_raw = false } = args;
+            const redis = await getConnection(instance_id);
+            const raw = await redis.get('cachly:crystal:latest');
+            if (!raw) {
+                return [
+                    `💎 **Memory Crystal: not yet created**`, '',
+                    `No crystal found. Create one with \`memory_crystalize()\` to compress your accumulated wisdom.`,
+                    '', `💡 Tip: run \`memory_crystalize\` monthly for best results.`,
+                ].join('\n');
+            }
+            const crystal = JSON.parse(raw);
+            const age = Math.floor((Date.now() - new Date(crystal.ts).getTime()) / 86400000);
+            const freshEmoji = age <= 7 ? '🟢' : age <= 30 ? '🟡' : '🔴';
+            const lines = [
+                `💎 **Memory Crystal: ${crystal.label}**`, '',
+                `📅 Created: ${new Date(crystal.ts).toLocaleDateString('de-DE')} (${age}d ago ${freshEmoji})`,
+                `📊 Compressed from: ${crystal.created_from}`,
+                `🗂️ Categories: ${crystal.categories.slice(0, 10).map(c => `\`${c}\``).join(', ')}${crystal.categories.length > 10 ? ` +${crystal.categories.length - 10} more` : ''}`,
+                '',
+                `**🔑 Top patterns (${crystal.top_patterns.length}):**`,
+            ];
+            for (const p of crystal.top_patterns) {
+                lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 110)}`);
+            }
+            if (age > 30) {
+                lines.push('', `⚠️ Crystal is ${age}d old — run \`memory_crystalize()\` to refresh it.`);
+            }
+            if (show_raw) {
+                lines.push('', '```json', JSON.stringify(crystal, null, 2), '```');
+            }
+            lines.push('', `💡 Refresh: \`memory_crystalize()\`  |  Recover: \`compact_recover(instance_id="...")\``);
+            return lines.join('\n');
+        }
+        // ── compact_recover ───────────────────────────────────────────────────────
+        case 'compact_recover': {
+            const { instance_id, focus = '' } = args;
+            const redis = await getConnection(instance_id);
+            const lines = [`🔁 **Compact Recovery Briefing**\n`];
+            lines.push(`> *Call this first after any context limit hit. Reconstructs where you left off.*\n`);
+            // 1. Memory Crystal
+            const crystalRaw = await redis.get('cachly:crystal:latest');
+            if (crystalRaw) {
+                const crystal = JSON.parse(crystalRaw);
+                lines.push(`### 💎 Memory Crystal: ${crystal.label}`);
+                lines.push(`Compressed from ${crystal.session_count} sessions, ${crystal.lesson_count} lessons.`);
+                const topN = focus
+                    ? crystal.top_patterns.filter(p => p.category.toLowerCase().includes(focus.toLowerCase()) || p.insight.toLowerCase().includes(focus.toLowerCase())).slice(0, 4)
+                    : crystal.top_patterns.slice(0, 4);
+                for (const p of topN)
+                    lines.push(`  • **${p.category}**: ${p.insight.slice(0, 100)}`);
+                lines.push('');
+            }
+            // 2. Last session summary
+            const lastSession = await redis.get('cachly:session:last');
+            if (lastSession) {
+                const sess = JSON.parse(lastSession);
+                lines.push(`### 🕐 Last Session`);
+                if (sess.focus)
+                    lines.push(`Focus: _${sess.focus}_`);
+                if (sess.summary)
+                    lines.push(`Summary: ${sess.summary.slice(0, 300)}`);
+                lines.push('');
+            }
+            // 3. Session handoff
+            const handoff = await redis.get('cachly:session:handoff');
+            if (handoff) {
+                const h = JSON.parse(handoff);
+                lines.push(`### 📋 Handoff (from last window)`);
+                if (h.context_summary)
+                    lines.push(`Context: ${h.context_summary.slice(0, 200)}`);
+                if (h.remaining_tasks?.length) {
+                    lines.push(`Remaining tasks:`);
+                    for (const t of h.remaining_tasks.slice(0, 5))
+                        lines.push(`  • ${t}`);
+                }
+                if (h.instructions)
+                    lines.push(`⚠️ Instructions: ${h.instructions.slice(0, 200)}`);
+                if (h.blocked_on)
+                    lines.push(`🚧 Blocked on: ${h.blocked_on}`);
+                lines.push('');
+            }
+            // 4. WIP registry
+            const wipRaw = await redis.get('cachly:ctx:wip-registry');
+            if (wipRaw) {
+                const wip = JSON.parse(wipRaw);
+                if (wip.content) {
+                    lines.push(`### 🔧 WIP Registry`);
+                    lines.push(wip.content.slice(0, 400));
+                    lines.push('');
+                }
+            }
+            // 5. Open failures (roadmap with status=blocked/in_progress)
+            const roadmapKeys = [];
+            const rStream = redis.scanStream({ match: 'cachly:roadmap:*', count: 100 });
+            await new Promise((res, rej) => { rStream.on('data', (b) => roadmapKeys.push(...b)); rStream.on('end', res); rStream.on('error', rej); });
+            const openItems = [];
+            for (const k of roadmapKeys.slice(0, 30)) {
+                const r = await redis.get(k);
+                if (!r)
+                    continue;
+                try {
+                    const item = JSON.parse(r);
+                    if (item.status === 'in_progress' || item.status === 'blocked')
+                        openItems.push({ title: item.title ?? k, status: item.status, priority: item.priority });
+                }
+                catch { /* skip */ }
+            }
+            if (openItems.length > 0) {
+                lines.push(`### 🚧 Open Items`);
+                for (const i of openItems.slice(0, 5))
+                    lines.push(`  • [${i.status}] ${i.title}`);
+                lines.push('');
+            }
+            // 6. Focus-relevant lessons
+            if (focus) {
+                const lessonKeys = [];
+                const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+                await new Promise((res, rej) => { lStream.on('data', (b) => lessonKeys.push(...b)); lStream.on('end', res); lStream.on('error', rej); });
+                const relevant = [];
+                for (const k of lessonKeys) {
+                    const r = await redis.get(k);
+                    if (!r)
+                        continue;
+                    try {
+                        const l = JSON.parse(r);
+                        if (l.topic.toLowerCase().includes(focus.toLowerCase()) && l.what_worked) {
+                            relevant.push({ topic: l.topic, what_worked: l.what_worked });
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+                if (relevant.length > 0) {
+                    lines.push(`### 💡 Relevant Lessons for "${focus}"`);
+                    for (const l of relevant.slice(0, 4))
+                        lines.push(`  • **${l.topic}**: ${l.what_worked.slice(0, 100)}`);
+                    lines.push('');
+                }
+            }
+            if (lines.length <= 3) {
+                lines.push(`_No brain data found. Start accumulating knowledge with \`learn_from_attempts\` and \`session_start\`._`);
+            }
+            lines.push(`---`, `🧠 Brain is ready. Continue your work — full context restored.`);
+            return lines.join('\n');
+        }
+        // ── brain_from_git ────────────────────────────────────────────────────────
+        case 'brain_from_git': {
+            const { instance_id, repo_path = '.', limit = 100, branch = 'HEAD', since = '' } = args;
+            const redis = await getConnection(instance_id);
+            const { execSync } = await import('node:child_process');
+            const { resolve } = await import('node:path');
+            const repoDir = resolve(repo_path);
+            const maxCommits = Math.min(Number(limit) || 100, 500);
+            // Verify it's a git repo
+            try {
+                execSync('git rev-parse --git-dir', { cwd: repoDir, stdio: 'pipe' });
+            }
+            catch {
+                return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
+            }
+            // Build git log command
+            const sinceFlag = since ? `--since="${since}"` : '';
+            const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
+            let logOutput = '';
+            try {
+                logOutput = execSync(logCmd, { cwd: repoDir, encoding: 'utf-8', stdio: 'pipe' });
+            }
+            catch (e) {
+                return `❌ git log failed: ${e.message}. Check \`repo_path\` and \`branch\`.`;
+            }
+            const commits = logOutput.trim().split('\n').filter(Boolean).map(line => {
+                const [sha, subject, date, author] = line.split('|||');
+                return { sha: (sha ?? '').trim(), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim() };
+            });
+            if (commits.length === 0) {
+                return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
+            }
+            // Pattern classifiers
+            const classifyCommit = (subject) => {
+                const s = subject.toLowerCase();
+                if (/\b(fix|fixed|fixes|bug|hotfix|patch|revert|resolve|closes? #\d+)\b/.test(s)) {
+                    const sev = /\b(critical|crash|security|auth|data loss|outage|prod|production)\b/.test(s) ? 'critical' : /\b(major|breaking|regression|hotfix)\b/.test(s) ? 'major' : 'minor';
+                    return { category: 'fix', outcome: 'success', severity: sev };
+                }
+                if (/\b(feat|feature|add|added|implement|new|introduce)\b/.test(s))
+                    return { category: 'feat', outcome: 'success', severity: 'minor' };
+                if (/\b(refactor|clean|cleanup|improve|simplify|extract|rename)\b/.test(s))
+                    return { category: 'refactor', outcome: 'success', severity: 'minor' };
+                if (/\b(perf|optimize|speed|cache|latency|memory|performance)\b/.test(s))
+                    return { category: 'perf', outcome: 'success', severity: 'major' };
+                if (/\b(security|cve|auth|csrf|xss|sql|injection|sanitize|escape|encrypt)\b/.test(s))
+                    return { category: 'security', outcome: 'success', severity: 'critical' };
+                if (/\b(deploy|ci|cd|build|docker|k8s|helm|infra|devops)\b/.test(s))
+                    return { category: 'deploy', outcome: 'success', severity: 'major' };
+                if (/\b(test|spec|coverage|assert|mock|unit|integration)\b/.test(s))
+                    return { category: 'test', outcome: 'success', severity: 'minor' };
+                return { category: 'chore', outcome: 'success', severity: 'minor' };
+            };
+            // Extract domain keywords from commit subject
+            const extractDomain = (subject) => {
+                const s = subject.toLowerCase();
+                const tokens = s.replace(/[^a-z0-9\s\-_]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !['that', 'this', 'with', 'from', 'when', 'into', 'also', 'some', 'were'].includes(t));
+                return tokens.slice(0, 3).join('-') || 'general';
+            };
+            const ts = new Date().toISOString();
+            let ingested = 0;
+            let skipped = 0;
+            const categoryCount = new Map();
+            for (const commit of commits) {
+                if (!commit.subject) {
+                    skipped++;
+                    continue;
+                }
+                const { category, outcome, severity } = classifyCommit(commit.subject);
+                const domain = extractDomain(commit.subject);
+                const topic = `${category}:${domain}`;
+                categoryCount.set(category, (categoryCount.get(category) ?? 0) + 1);
+                const lessonObj = {
+                    topic, outcome, severity,
+                    what_worked: commit.subject.slice(0, 200),
+                    what_failed: '',
+                    context: `git:${commit.sha.slice(0, 8)} by ${commit.author} on ${commit.date}`,
+                    file_paths: [], commands: [`git show ${commit.sha.slice(0, 8)}`],
+                    tags: ['brain_from_git', category, 'git-history'],
+                    depends_on: [], recall_count: 0, ts, verified_at: ts,
+                    confidence: 0.55, // lower confidence for auto-inferred lessons
+                    audit_trail: [{ ts, action: 'brain_from_git', sha: commit.sha.slice(0, 8) }],
+                    version: 3,
+                };
+                // Only store if no existing lesson for this topic (avoid overwriting higher-confidence lessons)
+                const existing = await redis.get(`cachly:lesson:best:${topic}`);
+                if (!existing) {
+                    await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj));
+                    await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+                }
+                await redis.rpush('cachly:lessons:brain_from_git:all', JSON.stringify({ topic, sha: commit.sha.slice(0, 8), subject: commit.subject.slice(0, 60) }));
+                await redis.ltrim('cachly:lessons:brain_from_git:all', -500, -1);
+                // Update CKG
+                const conceptId = ckgSlug(topic);
+                await ckgUpsertNode(redis, conceptId, category, 'git-derived');
+                ingested++;
+            }
+            const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
+            return [
+                `🔁 **brain_from_git: ${repoDir}**`, '',
+                `📂 Branch: \`${branch}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
+                ``,
+                `**Breakdown by category:**`,
+                categoryBreakdown,
+                ``,
+                `💡 New lessons are stored with confidence 0.55 (auto-inferred).`,
+                `💡 As you confirm them via \`learn_from_attempts\`, confidence rises automatically.`,
+                `🔍 Explore: \`brain_search(query="fix")\`  |  \`ckg_inspect(concept="deploy")\``,
+            ].join('\n');
+        }
+        // ── brain_predict_failures ─────────────────────────────────────────────────
+        case 'brain_predict_failures': {
+            const { instance_id, context: ctx, top_k = 5, format = 'detailed' } = args;
+            const redis = await getConnection(instance_id);
+            const ctxTokens = ctx.toLowerCase().replace(/[^a-z0-9\s\-_:.]/g, ' ').split(/\s+/).filter(t => t.length > 2);
+            const failures = [];
+            // Step 1: CKG — find 'causes' and 'degrades_under' edges from context tokens
+            for (const token of ctxTokens.slice(0, 8)) {
+                const nodeKeys = [];
+                const nStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 50 });
+                await new Promise((res, rej) => { nStream.on('data', (b) => nodeKeys.push(...b)); nStream.on('end', res); nStream.on('error', rej); });
+                for (const nk of nodeKeys.slice(0, 5)) {
+                    const nodeRaw = await redis.get(nk);
+                    if (!nodeRaw)
+                        continue;
+                    const node = JSON.parse(nodeRaw);
+                    const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
+                    for (const ek of edgeKeys.slice(0, 20)) {
+                        const edgeRaw = await redis.get(ek);
+                        if (!edgeRaw)
+                            continue;
+                        const edge = JSON.parse(edgeRaw);
+                        if (edge.edgeType !== 'causes' && edge.edgeType !== 'degrades_under')
+                            continue;
+                        // Look up fix for this failure from CKG 'fixes' edges
+                        const fixEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${edge.to}`);
+                        let fix;
+                        for (const fek of fixEdgeKeys.slice(0, 10)) {
+                            const feRaw = await redis.get(fek);
+                            if (!feRaw)
+                                continue;
+                            const fe = JSON.parse(feRaw);
+                            if (fe.edgeType === 'fixes') {
+                                const lessonRaw = await redis.get(`cachly:lesson:best:${fe.from}`);
+                                if (lessonRaw) {
+                                    const lesson = JSON.parse(lessonRaw);
+                                    fix = lesson.what_worked?.slice(0, 120);
+                                    break;
+                                }
+                            }
+                        }
+                        failures.push({
+                            concept: node.id,
+                            failure: edge.to.replace(/-/g, ' '),
+                            probability: edge.confidence,
+                            fix,
+                            source: 'ckg',
+                        });
+                    }
+                }
+            }
+            // Step 2: Lesson history — find failure-outcome lessons matching context
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 300 });
+            await new Promise((res, rej) => { lStream.on('data', (b) => lessonKeys.push(...b)); lStream.on('end', res); lStream.on('error', rej); });
+            for (const k of lessonKeys.slice(0, 100)) {
+                const r = await redis.get(k);
+                if (!r)
+                    continue;
+                try {
+                    const l = JSON.parse(r);
+                    if (l.outcome !== 'failure' && l.outcome !== 'partial')
+                        continue;
+                    if (!l.what_failed)
+                        continue;
+                    const haystack = `${l.topic} ${l.what_failed}`.toLowerCase();
+                    const matchScore = ctxTokens.filter(t => haystack.includes(t)).length / Math.max(1, ctxTokens.length);
+                    if (matchScore < 0.15)
+                        continue;
+                    const sevBoost = l.severity === 'critical' ? 0.15 : l.severity === 'major' ? 0.05 : 0;
+                    failures.push({
+                        concept: l.topic,
+                        failure: l.what_failed.slice(0, 80),
+                        probability: Math.min(0.97, (l.confidence ?? 0.5) * matchScore * 1.5 + sevBoost),
+                        fix: l.what_worked?.slice(0, 120),
+                        topic: l.topic,
+                        source: 'lesson',
+                    });
+                }
+                catch { /* skip */ }
+            }
+            if (failures.length === 0) {
+                return [
+                    `🔮 **Failure Prediction: "${ctx}"**`, '',
+                    `No known failure patterns found for this context.`,
+                    `💡 The brain learns from every \`learn_from_attempts(outcome="failure")\` call.`,
+                    `🔍 Try: \`brain_predict(context="${ctx}")\` for broader predictions.`,
+                ].join('\n');
+            }
+            // Deduplicate and rank by probability
+            const seen = new Set();
+            const ranked = failures.filter(f => {
+                const k = f.failure.slice(0, 40);
+                if (seen.has(k))
+                    return false;
+                seen.add(k);
+                return true;
+            }).sort((a, b) => b.probability - a.probability).slice(0, Number(top_k));
+            const lines = [`🔮 **Failure Prediction for: "${ctx}"**\n`];
+            lines.push(`> Pre-deploy failure analysis based on ${failures.length} patterns. Ranked by probability.\n`);
+            for (let i = 0; i < ranked.length; i++) {
+                const f = ranked[i];
+                const pct = Math.round(f.probability * 100);
+                const bar = '█'.repeat(Math.round(pct / 10)) + '░'.repeat(10 - Math.round(pct / 10));
+                const icon = pct >= 70 ? '🔴' : pct >= 40 ? '🟡' : '🟢';
+                lines.push(`${icon} **${i + 1}. ${f.failure}**`);
+                lines.push(`   Probability: ${bar} **${pct}%** (${f.source === 'ckg' ? 'CKG causal edge' : 'lesson history'})`);
+                if (format === 'detailed' && f.fix) {
+                    lines.push(`   ✅ Pre-loaded fix: _${f.fix}_`);
+                }
+                if (format === 'detailed' && f.topic) {
+                    lines.push(`   📚 Lesson: \`${f.topic}\``);
+                }
+                lines.push('');
+            }
+            const highRisk = ranked.filter(f => f.probability >= 0.6);
+            if (highRisk.length > 0) {
+                lines.push(`⚠️ **${highRisk.length} high-risk failure${highRisk.length > 1 ? 's' : ''} detected** (≥60% probability). Review fixes before proceeding.`);
+            }
+            else {
+                lines.push(`✅ No high-risk failures detected. Proceed with caution and monitor closely.`);
+            }
+            lines.push('', `💡 After deploy: \`learn_from_attempts(topic="deploy:...", outcome="success|failure")\` to improve future predictions.`);
+            return lines.join('\n');
+        }
         default:
             return null;
     }
@@ -9080,6 +9552,21 @@ if (!JWT) {
         '╚══════════════════════════════════════════════════════════════════╝\n' +
         '\n');
 }
+else {
+    // Warn if the JWT is already expired or expiring within the hour.
+    const expMs = jwtExpiryMs(JWT);
+    if (expMs !== null) {
+        const minsLeft = Math.floor((expMs - Date.now()) / 60_000);
+        if (minsLeft <= 0) {
+            process.stderr.write(`\n⚠️  cachly: CACHLY_JWT expired ${Math.abs(minsLeft)} minute(s) ago.\n` +
+                `   All tool calls will fail. Get a fresh token at https://cachly.dev/setup-ai\n\n`);
+        }
+        else if (minsLeft < 60) {
+            process.stderr.write(`\n⚠️  cachly: CACHLY_JWT expires in ${minsLeft} minute(s).\n` +
+                `   Refresh it soon at https://cachly.dev/setup-ai to avoid interruptions.\n\n`);
+        }
+    }
+}
 // ── Update nudge (non-blocking, fire-and-forget) ─────────────────────────────
 // Check npm registry once per process start; if outdated, log to stderr so
 // the editor's MCP log shows an actionable one-liner. Skipped if opted out.