@cachly-dev/mcp-server 0.10.55 → 0.10.57

package/dist/{handlers → src/handlers}/brain.js

@@ -3,59 +3,42 @@ import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import { safeJsonParse } from '../utils.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
+import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.55';
+const MCP_VERSION = '0.10.57';
 const WHATS_NEW = {
-    '0.10.55': [
-        `🆕 **What's new in cachly MCP v0.10.55:**`,
-        `  ⚡ UX: API failure now shows a clear error instead of silently blocking for 30s`,
-        `  ⚡ UX: provisioning wait reduced from 25s → 8s (Brain is usually ready sooner)`,
-        `  🔧 VS Code: setup spinner is now cancellable — dismiss and MCP auto-connects later`,
-        `  🧠 VS Code: Brain Health panel shows offline-queued lessons with pending sync count`,
-    ],
-    '0.10.54': [
-        `🆕 **What's new in cachly MCP v${MCP_VERSION}:**`,
-        `  👀 Perf: first tool call no longer blocked by auto-session (was freezing for 30-120s on large repos)`,
-        `  👀 Perf: git history bootstrap runs in background — session_start responds instantly`,
-        `  🐞 Fixed: VS Code lessons now include author attribution (broken since launch)`,
-    ],
-    '0.10.53': [
-        `🆕 **What's new in cachly MCP v${MCP_VERSION}:**`,
-        `  🐛 Fixed: Brain bootstrap summary now visible in session_start (was silently discarded)`,
-        `  🐛 Fixed: team lessons now indexed correctly (\`ts\` field was stored as \`timestamp\`)`,
-        `  ✨ New: proactive follow-up hints after \`learn_from_attempts\` (CKG co-occurrence patterns)`,
-        `  ✨ New: author name attribution for VS Code lessons (set \`cachly.authorName\` in VS Code settings)`,
+    '0.10.57': [
+        `🆕 **What's new in v${MCP_VERSION}:**`,
+        `  🔧 **Critical fix** — corrected the npm bin/main entry path (\`dist/src/index.js\`); 0.10.50–0.10.52 shipped a broken entry point`,
+        `  🔧 Version hygiene — synced package.json, server.json, lockfile, MCP_VERSION; \`latest\` now points forward again`,
+        `  ✅ Accurate tool count (95) across README, server.json, CLI banners`,
+        `  ✅ Includes all Phase 2/3 work: quality reranking, Cachly-Bench, hybrid + CKG recall, team_confirm governance`,
     ],
     '0.10.52': [
-        `🆕 **What's new in cachly MCP v0.10.52:**`,
-        `  🚀 Zero-click setup: Brain activates automatically on first call (no auth prompt needed)`,
-        `  🐛 Fixed: all Brain connections now use decrypted passwords (resolves AUTH errors for all users)`,
+        `  ✅ \`smart_recall\` — CKG traversal as Layer 3: finds lessons that FIXED causal-graph-similar problems (🕸️ causal graph badge)`,
+        `  ✅ Bench corpus expanded: governance adversarial pair proves review-boost end-to-end (+22% P@1 headline)`,
+        `  🔧 Import cleanup: unused symbols removed from brain.ts (no functional change)`,
+        `  💡 \`smart_recall\` now shows keyword / semantic / CKG / hybrid match type for every result`,
     ],
-    '0.10.50': [
-        `🆕 **What's new in cachly MCP v0.10.50:**`,
-        `  🐛 Fixed: Brain connection now works out of the box (was failing with AUTH error)`,
-        `  🐛 Fixed: TLS defaults to off for free-tier instances (no more TLS handshake failure)`,
-        `  ✅ \`get_api_status\` correctly shows API key type instead of "invalid JWT format"`,
+    '0.10.51': [
+        `  ✅ \`team_confirm\` — human review raises lesson recall ranking (🛡️ senior / ✔️ peer)`,
+        `  ✅ Governance-aware recall — confirmed lessons outrank unreviewed auto-learned entries`,
     ],
-    '0.10.46': [
-        `🆕 **What's new in v0.10.46:**`,
-        `  ✅ \`brain_from_git\` — auto-learns from your full git history on setup`,
-        `  ✅ \`smart_recall\` — semantic + keyword hybrid search, 3× more relevant results`,
-        `  ✅ VS Code Extension — Brain persists across all projects, zero config`,
-        `  ✅ Device-flow auth — zero-config login, no JWT needed in editor config`,
-        `  ✅ Auto-provision — Brain instance created automatically after first login`,
-        `  ✅ JWT now persisted to ~/.claude/mcp.json — survives editor restarts`,
-        `  ✅ Confidence scoring — every recalled fact shows staleness + reliability`,
-        `  ✅ CKG (Causal Knowledge Graph) — root-cause chains between bugs + fixes`,
+    '0.10.50': [
+        `  ✅ \`smart_recall\` — unified keyword + semantic hybrid list (one ranked result, not two sections)`,
+        `  ✅ \`smart_recall\` — "Brain saved you here" banner surfaces time saved inline per proven lesson`,
+        `  ✅ Quality reranking — proven successes outrank symptom-dense failures (+11% Precision@1)`,
+        `  ✅ Cachly-Bench — IR benchmark with CI regression guard (see BENCH.md for the proof)`,
+        `  🔧 Contradiction resolution now persisted to Redis (90-day TTL)`,
+        `  💡 Run \`smart_recall\` to see your Brain's recall quality in action`,
     ],
-    '0.10.0': [
-        `🆕 **What's new in v0.10.0:**`,
-        `  ✅ Zero-friction setup — auto-provisions your Brain, no manual config needed`,
-        `  ✅ 10× faster briefings — batch Redis fetches replace per-key loops`,
-        `  ✅ Crash-proof data reads — corrupted cache entries no longer break tools`,
-        `  ✅ \`session_end\` warns when called without an active session`,
-        `  ✅ \`get_api_status\` now shows live Redis ping + all instance statuses`,
+    '0.10.49': [
+        `  ✅ \`brain_from_git\` — auto-seed your Brain from git history in seconds`,
+        `  ✅ \`brain_predict_failures\` — predict CI/build failures before they happen`,
+        `  ✅ VS Code extension — Brain status bar, ambient learning, CodeLens hints`,
+        `  ✅ Team Brain — share lessons across your whole engineering team`,
+        `  🔧 Stability — auto-expiring memory keys, longer provisioning wait, robust recall`,
     ],
 };
 export const BRAIN_TOOL_NAMES = new Set([
@@ -111,6 +94,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             await ckgUpdateEdge(redis, cId, 'contradicts', resId, false);
                         }
                         catch { /* non-critical */ }
+                        // Persist a queryable resolution record — so contradiction history survives
+                        // (CKG edges alone aren't easily auditable). Bounded + TTL'd like other history.
+                        try {
+                            const resolutionKey = `cachly:contradictions:${topic}`;
+                            const direction = prev.outcome === 'success' && outcome === 'failure'
+                                ? 'kept-success' : 'overwrote-failure';
+                            await redis.rpush(resolutionKey, JSON.stringify({
+                                ts, prev_outcome: prev.outcome, new_outcome: outcome, direction,
+                            }));
+                            await redis.ltrim(resolutionKey, -50, -1);
+                            await redis.expire(resolutionKey, 180 * 86400);
+                        }
+                        catch { /* non-critical */ }
                         contradictionWarning.push(`🗳️ Run \`madc_deliberate(topic="${topic}")\` to resolve via expert agent voting.`);
                     }
                 }
@@ -156,7 +152,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const depTopics = safeJsonParse(existing, []);
                 if (!depTopics.includes(topic))
                     depTopics.push(topic);
-                await redis.set(depKey, JSON.stringify(depTopics), 'EX', 365 * 86400); // 1-year TTL
+                await redis.set(depKey, JSON.stringify(depTopics), 'EX', 90 * 86400);
             }
             const lessonObj = {
                 topic,
@@ -178,11 +174,11 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 version: 3,
             };
             const lesson = JSON.stringify(lessonObj);
-            // Always append to the history list (audit log); cap at 200 entries to prevent unbounded growth
+            // Always append to the history list (audit log); keep last 100 entries, 90-day TTL
             const listKey = `cachly:lessons:${topic}`;
             await redis.rpush(listKey, lesson);
-            await redis.ltrim(listKey, -200, -1);
-            await redis.expire(listKey, 365 * 86400); // 1-year TTL
+            await redis.ltrim(listKey, -100, -1);
+            await redis.expire(listKey, 90 * 86400);
             // Update best key for success/partial; for failure only update if no success exists
             if (outcome === 'success' || outcome === 'partial') {
                 await redis.set(`cachly:lesson:best:${topic}`, lesson);
@@ -316,46 +312,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             catch { /* CKG updates are non-critical */ }
-            // ── Proactive follow-up suggestion (CKG co-occurrence patterns) ─────────
-            // After a successful fix, check if related concepts commonly follow it.
-            // Uses CKG co-occurs edges with confidence > 0.4 and at least 2 trials.
-            const proactiveSuggestions = [];
-            if (outcome === 'success' || outcome === 'partial') {
-                try {
-                    const conceptId = ckgSlug(topic);
-                    const fromEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
-                    for (const ek of fromEdgeKeys.slice(0, 20)) {
-                        const er = await redis.get(ek);
-                        if (!er)
-                            continue;
-                        const edge = safeJsonParse(er, null);
-                        if (!edge || edge.confidence < 0.4 || (edge.trials ?? 0) < 2)
-                            continue;
-                        if (edge.edgeType !== 'co-occurs' && edge.edgeType !== 'causes')
-                            continue;
-                        // Resolve related concept to a lesson key
-                        const relTopic = edge.to
-                            .replace(/^cause:/, '')
-                            .replace(/^tag:/, '')
-                            .replace(/^problem:/, '')
-                            .replace(/-/g, ':')
-                            .replace(/_/g, '-');
-                        const relRaw = await redis.get(`cachly:lesson:best:${relTopic}`);
-                        if (!relRaw)
-                            continue;
-                        const relLesson = safeJsonParse(relRaw, null);
-                        const displayTopic = relLesson?.topic ?? relTopic;
-                        if (!relLesson || !relLesson.what_worked || displayTopic === topic)
-                            continue;
-                        const pct = Math.round(edge.confidence * 100);
-                        if (proactiveSuggestions.length === 0)
-                            proactiveSuggestions.push('');
-                        proactiveSuggestions.push(`🔮 **Pattern detected:** \`${displayTopic}\` tends to follow this (${pct}% co-occurrence across ${edge.trials} sessions)`, `   → ${relLesson.what_worked.slice(0, 100)}${relLesson.what_worked.length > 100 ? '…' : ''}`, `   → Pre-empt it now: \`recall_best_solution(topic="${displayTopic}")\``);
-                        break; // one proactive hint is enough
-                    }
-                }
-                catch { /* non-critical */ }
-            }
             const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
             const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
             const action = isUpdate ? 'updated' : 'stored';
@@ -378,7 +334,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     : '',
                 ...templateWarnings,
                 ...iWasWrongWarning,
-                ...proactiveSuggestions,
             ].filter(l => l !== '').join('\n');
         }
         case 'recall_best_solution': {
@@ -419,8 +374,29 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const suggestPin = updatedLesson.recall_count === 3 && !lesson.pinned
                     ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
                     : '';
+                // ── Trust signal (today-safe consensus layer) ───────────────────────
+                // A lesson recalled many times — or confirmed by multiple distinct
+                // authors — has proven its value. Surface that as social proof.
+                const lessonAuthors = lesson.authors
+                    ?? (lesson.author ? [lesson.author] : []);
+                const distinctAuthors = [...new Set(lessonAuthors.filter(Boolean))];
+                const rc = updatedLesson.recall_count;
+                let trustBadge = '';
+                if (distinctAuthors.length >= 2 && rc >= 5) {
+                    trustBadge = `🏆 **Battle-tested** — recalled ${rc}× · verified by ${distinctAuthors.length} developers. Trust this.`;
+                }
+                else if (rc >= 10) {
+                    trustBadge = `🏆 **Battle-tested** — recalled ${rc}×. This is one of your most-proven solutions.`;
+                }
+                else if (distinctAuthors.length >= 2) {
+                    trustBadge = `✅ **Team-verified** — confirmed by ${distinctAuthors.length} developers.`;
+                }
+                else if (rc >= 5) {
+                    trustBadge = `✅ **Proven** — recalled ${rc}× without contradiction.`;
+                }
                 return [
                     rememberWhen,
+                    trustBadge,
                     `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
                     ``,
                     `**What worked:** ${lesson.what_worked}`,
@@ -470,57 +446,37 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const { instance_id, query, threshold = 0.78, } = args;
             const redis = await getConnection(instance_id);
             // ── Layer 1: Keyword search across ALL brain data (always works, no embedding) ──
-            const kwMatches = await keywordSearch(redis, ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'], query, 10);
-            const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
-            // Show sub-query info if multi-topic was detected
-            const subQueries = splitMultiQuery(query);
-            if (subQueries.length > 1) {
-                lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
-            }
-            if (kwMatches.length > 0) {
-                lines.push(`### 🔍 BM25 Matches (${kwMatches.length})\n`);
-                // Group by sub-query if multi-topic
-                if (subQueries.length > 1) {
-                    const grouped = new Map();
-                    for (const m of kwMatches.slice(0, 12)) {
-                        const sq = m.subQuery ?? query;
-                        if (!grouped.has(sq))
-                            grouped.set(sq, []);
-                        grouped.get(sq).push(m);
-                    }
-                    for (const [sq, matches] of grouped) {
-                        lines.push(`**Topic: "${sq}"** (${matches.length} results)\n`);
-                        for (const m of matches.slice(0, 4)) {
-                            const label = m.key
-                                .replace('cachly:ctx:', '📝 ')
-                                .replace('cachly:lesson:best:', '💡 ')
-                                .replace('cachly:idx:', '📂 ');
-                            const preview = m.content.slice(0, 300).replace(/\n/g, ' ');
-                            lines.push(`  **${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-                            lines.push(`  > ${preview}${m.content.length > 300 ? '…' : ''}\n`);
+            const rawMatches = await keywordSearch(redis, ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'], query, 10);
+            // ── Layer 1.5: Quality-aware rerank — proven success lessons outrank
+            // text-similar failed attempts (the moat; see src/rerank.ts + Cachly-Bench). ──
+            const kwMatches = rerankByQuality(rawMatches);
+            const savedHere = [];
+            const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
+            for (const m of lessonMatches.slice(0, 5)) {
+                const existing = await redis.get(m.key).catch(() => null);
+                if (existing) {
+                    const lesson = safeJsonParse(existing, null);
+                    if (lesson) {
+                        const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
+                        redis.set(m.key, JSON.stringify(updated)).catch(() => { });
+                        const sev = lesson.severity;
+                        const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
+                        redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                        // Surface banner for proven successes (recall_count >= 1 means it's been validated)
+                        if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
+                            savedHere.push({
+                                topic: m.key.replace('cachly:lesson:best:', ''),
+                                severity: sev ?? 'major',
+                                recall_count: (lesson.recall_count ?? 0) + 1,
+                                savedMins,
+                            });
                         }
                     }
-                    // Summary: which sub-queries had matches
-                    const matched = [...grouped.keys()];
-                    const unmatched = subQueries.filter(sq => !matched.includes(sq));
-                    if (unmatched.length > 0) {
-                        lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
-                    }
-                }
-                else {
-                    for (const m of kwMatches.slice(0, 8)) {
-                        const label = m.key
-                            .replace('cachly:ctx:', '📝 ')
-                            .replace('cachly:lesson:best:', '💡 ')
-                            .replace('cachly:idx:', '📂 ');
-                        const preview = m.content.slice(0, 400).replace(/\n/g, ' ');
-                        lines.push(`**${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-                        lines.push(`> ${preview}${m.content.length > 400 ? '…' : ''}\n`);
-                    }
                 }
             }
-            // ── Layer 2: Semantic search (optional, only if embedding provider + vector_token available) ──
+            // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
             const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+            const semHits = [];
             if (inst.vector_token && hasEmbedProvider()) {
                 try {
                     const embedding = await computeEmbedding(query);
@@ -532,16 +488,13 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     });
                     if (searchRes.ok) {
                         const results = (await searchRes.json());
-                        const semHits = results.filter(r => r.found && r.id);
-                        if (semHits.length > 0) {
-                            lines.push(`\n### 🎯 Semantic Matches (${semHits.length})\n`);
-                            for (const hit of semHits) {
-                                const parts = hit.id.replace('ctx:', '').split(':');
-                                const category = parts[0];
-                                const key = parts.slice(1).join(':');
-                                const content = await redis.get(`cachly:ctx:${category}:${key}`);
-                                lines.push(`**${key}** _(${((hit.similarity ?? 0) * 100).toFixed(0)}% similar)_`, `> ${content?.slice(0, 300) ?? '(evicted)'}${(content?.length ?? 0) > 300 ? '…' : ''}\n`);
-                            }
+                        for (const hit of results.filter(r => r.found && r.id)) {
+                            const parts = hit.id.replace('ctx:', '').split(':');
+                            const category = parts[0];
+                            const key = parts.slice(1).join(':');
+                            const redisKey = `cachly:ctx:${category}:${key}`;
+                            const content = await redis.get(redisKey).catch(() => null);
+                            semHits.push({ key: redisKey, similarity: hit.similarity ?? 0, content: content ?? '(evicted)' });
                         }
                     }
                 }
@@ -549,7 +502,158 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     // Semantic search failed silently — keyword results are enough
                 }
             }
-            if (kwMatches.length === 0) {
+            const bm25Scores = kwMatches.map(m => m.score);
+            const bm25Min = bm25Scores.length ? Math.min(...bm25Scores) : 0;
+            const bm25Range = bm25Scores.length ? (Math.max(...bm25Scores) - bm25Min) || 1 : 1;
+            const bm25Norm = (s) => (s - bm25Min) / bm25Range;
+            const hybridMap = new Map();
+            for (const m of kwMatches) {
+                const n = bm25Norm(m.score);
+                hybridMap.set(m.key, {
+                    key: m.key, content: m.content, bm25Score: n,
+                    hybridScore: n * (semHits.length > 0 ? 0.7 : 1.0),
+                    matchedWords: m.matchedWords, matchType: 'keyword', subQuery: m.subQuery,
+                });
+            }
+            for (const hit of semHits) {
+                const existing = hybridMap.get(hit.key);
+                if (existing) {
+                    existing.semScore = hit.similarity;
+                    existing.hybridScore = (existing.bm25Score ?? 0) * 0.6 + hit.similarity * 0.4;
+                    existing.matchType = 'hybrid';
+                }
+                else {
+                    hybridMap.set(hit.key, {
+                        key: hit.key, content: hit.content, semScore: hit.similarity,
+                        hybridScore: hit.similarity * 0.5, matchType: 'semantic',
+                    });
+                }
+            }
+            // ── Layer 3: CKG traversal — follow "fixes" edges to find lessons that solved
+            // structurally similar problems, even when vocabulary differs ───────────────
+            try {
+                const qTokens = tokenize(query).filter(t => t.length >= 4).slice(0, 4);
+                const candidateNodeIds = new Set();
+                for (const token of qTokens) {
+                    const nodeStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 20 });
+                    await new Promise((res, rej) => {
+                        nodeStream.on('data', (batch) => {
+                            for (const k of batch.slice(0, 5))
+                                candidateNodeIds.add(k.replace('cachly:ckg:node:', ''));
+                        });
+                        nodeStream.on('end', res);
+                        nodeStream.on('error', rej);
+                    });
+                }
+                const seenFroms = new Set();
+                for (const nodeId of [...candidateNodeIds].slice(0, 12)) {
+                    const inboundEdgeKeys = await redis.smembers(`cachly:ckg:idx:to:${nodeId}`);
+                    for (const ek of inboundEdgeKeys.slice(0, 6)) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const edge = safeJsonParse(er, null);
+                        if (!edge || edge.edgeType !== 'fixes' || edge.confidence < 0.35)
+                            continue;
+                        if (seenFroms.has(edge.from))
+                            continue;
+                        seenFroms.add(edge.from);
+                        const lessonKey = `cachly:lesson:best:${edge.from}`;
+                        const existing = hybridMap.get(lessonKey);
+                        if (existing) {
+                            // Already found by BM25/semantic — boost with causal confirmation
+                            existing.ckgScore = Math.max(existing.ckgScore ?? 0, edge.confidence);
+                            existing.hybridScore = existing.hybridScore * 0.88 + edge.confidence * 0.12;
+                            if (existing.matchType === 'keyword')
+                                existing.matchType = 'hybrid';
+                        }
+                        else {
+                            const content = await redis.get(lessonKey).catch(() => null);
+                            if (!content)
+                                continue;
+                            hybridMap.set(lessonKey, {
+                                key: lessonKey, content,
+                                ckgScore: edge.confidence,
+                                hybridScore: edge.confidence * 0.30, // CKG-only: lower than text hits
+                                matchType: 'ckg',
+                            });
+                        }
+                    }
+                }
+            }
+            catch { /* non-critical — keyword + semantic always available */ }
+            const hybridResults = [...hybridMap.values()].sort((a, b) => b.hybridScore - a.hybridScore);
+            // ── Build output ──────────────────────────────────────────────────────────
+            const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
+            // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
+            const SORDER = { critical: 0, major: 1, minor: 2 };
+            const topLesson = savedHere.sort((a, b) => (SORDER[a.severity] ?? 1) - (SORDER[b.severity] ?? 1))[0];
+            if (topLesson) {
+                lines.push(`> 💡 **Brain saved you ~${topLesson.savedMins}m here** — ${topLesson.severity} issue from \`${topLesson.topic}\` recalled ${topLesson.recall_count}× proven\n`);
+            }
+            // Show sub-query info if multi-topic was detected
+            const subQueries = splitMultiQuery(query);
+            if (subQueries.length > 1) {
+                lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
+            }
+            if (hybridResults.length > 0) {
+                const hasCKG = hybridResults.some(r => r.ckgScore !== undefined);
+                const modeLabel = semHits.length > 0 && hasCKG
+                    ? `keyword + semantic + CKG hybrid`
+                    : semHits.length > 0
+                        ? `keyword + semantic hybrid`
+                        : hasCKG
+                            ? `keyword + CKG hybrid`
+                            : `keyword`;
+                lines.push(`### 🔍 Results (${hybridResults.length} — ${modeLabel})\n`);
+                // Group by sub-query for multi-topic queries
+                if (subQueries.length > 1) {
+                    const grouped = new Map();
+                    for (const r of hybridResults.slice(0, 12)) {
+                        const sq = r.subQuery ?? query;
+                        if (!grouped.has(sq))
+                            grouped.set(sq, []);
+                        grouped.get(sq).push(r);
+                    }
+                    for (const [sq, results] of grouped) {
+                        lines.push(`**Topic: "${sq}"** (${results.length} results)\n`);
+                        for (const r of results.slice(0, 4)) {
+                            const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+                            const scorePart = r.matchType === 'ckg'
+                                ? `CKG: ${(r.ckgScore ?? 0).toFixed(2)}, 🕸️ causal graph`
+                                : r.ckgScore !== undefined && r.bm25Score !== undefined
+                                    ? `BM25: ${(r.bm25Score).toFixed(2)}, CKG: ${(r.ckgScore).toFixed(2)}, 🔀 hybrid`
+                                    : r.matchType === 'hybrid'
+                                        ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+                                        : r.matchType === 'semantic'
+                                            ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+                                            : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+                            const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
+                            lines.push(`  **${label}** _(${scorePart})_`);
+                            lines.push(`  > ${preview}${r.content.length > 300 ? '…' : ''}\n`);
+                        }
+                    }
+                    const matched = [...grouped.keys()];
+                    const unmatched = subQueries.filter(sq => !matched.includes(sq));
+                    if (unmatched.length > 0) {
+                        lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
+                    }
+                }
+                else {
+                    for (const r of hybridResults.slice(0, 8)) {
+                        const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+                        const scorePart = r.matchType === 'hybrid'
+                            ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+                            : r.matchType === 'semantic'
+                                ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+                                : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+                        const preview = r.content.slice(0, 400).replace(/\n/g, ' ');
+                        lines.push(`**${label}** _(${scorePart})_`);
+                        lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
+                    }
+                }
+            }
+            else {
                 lines.push(`⚠️ No matches found for: "${query}"`);
                 // Did-You-Mean: find nearest token in index vocab
                 const queryTokens = tokenize(query);
@@ -865,6 +969,29 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             }
             // Brain health
             lines.push(`📊 **Brain:** ${lessons.length} lessons · ${ctxCount} context entries`, '');
+            // ── 📌 Proven Laws — auto-crystallized lessons (quick win 3) ─────────────
+            // A lesson that has proven itself (recalled ≥ CRYSTALLIZE_RECALLS times) or
+            // was explicitly pinned becomes a "law" — surfaced at the top of every
+            // briefing so the most battle-tested knowledge is never buried. This is
+            // the today-safe version of swarm crystallization: enough confirmations
+            // auto-promote a lesson without any manual step.
+            {
+                const CRYSTALLIZE_RECALLS = 5;
+                const laws = lessons
+                    .filter(l => l.outcome === 'success' && (l.pinned === true || (l.recall_count ?? 0) >= CRYSTALLIZE_RECALLS))
+                    .sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0))
+                    .slice(0, 5);
+                if (laws.length > 0) {
+                    lines.push(`📌 **Proven Laws** (auto-crystallized — your most-trusted knowledge):`);
+                    for (const l of laws) {
+                        const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+                        const rc = l.recall_count ?? 0;
+                        const why = l.pinned === true ? 'pinned' : `recalled ${rc}×`;
+                        lines.push(`  🏆${sev} \`${l.topic}\` _(${why})_ — ${l.what_worked.slice(0, 100)}`);
+                    }
+                    lines.push('');
+                }
+            }
             // ── Layer 7: MCM Domain Coverage Map ────────────────────────────────────
             if (lessons.length >= 3) {
                 const domainMap = new Map();
@@ -967,8 +1094,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     for (const l of topRecalled) {
                         const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
                         const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-                        const rct = l.recall_count && l.recall_count > 1 ? ` _(${l.recall_count}× recalled)_` : '';
-                        lines.push(`  ${emoji}${sev} \`${l.topic}\`${rct} — ${l.what_worked.slice(0, 100)}`);
+                        const rc = l.recall_count ?? 0;
+                        const la = l.authors
+                            ?? (l.author ? [l.author] : []);
+                        const nAuthors = new Set(la.filter(Boolean)).size;
+                        const trust = (nAuthors >= 2 && rc >= 5) || rc >= 10 ? ' 🏆'
+                            : nAuthors >= 2 || rc >= 5 ? ' ✅' : '';
+                        const rct = rc > 1 ? ` _(${rc}× recalled)_` : '';
+                        lines.push(`  ${emoji}${sev}${trust} \`${l.topic}\`${rct} — ${l.what_worked.slice(0, 100)}`);
                     }
                     lines.push('');
                 }
@@ -1034,25 +1167,59 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lines.push('');
             }
             // ── 🔮 Predictive Pre-Warning — intent-based danger detection ────────────
-            // Fires BEFORE work starts. If focus area has known failure patterns → warn loudly.
-            if (focusTerms.length > 0) {
-                const dangerLessons = lessons.filter(l => {
-                    if (l.outcome === 'success')
-                        return false;
-                    const topicCategory = l.topic.split(':')[0];
-                    return focusTerms.some(term => l.topic.toLowerCase().includes(term) ||
-                        topicCategory === term ||
-                        (l.tags ?? []).some((t) => t.toLowerCase() === term));
-                });
-                if (dangerLessons.length >= 1) {
-                    // Insert warning block right after the title line (index 1 = blank line after title)
-                    const warning = [
-                        `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
-                        `  Known pitfalls for **"${focus}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`,
-                        ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
-                        '',
-                    ];
-                    lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+            // Fires BEFORE work starts. Uses explicit focus when given; otherwise
+            // derives the likely work area from the last session's changed files +
+            // summary (you usually keep working where you left off). This makes the
+            // warning fire even when the caller forgets to pass `focus`.
+            {
+                // Common path noise / extensions to drop when deriving terms from files.
+                const PATH_NOISE = new Set([
+                    'src', 'lib', 'test', 'tests', 'dist', 'index', 'main', 'app',
+                    'internal', 'pkg', 'cmd', 'node_modules', 'components', 'utils',
+                    'ts', 'tsx', 'js', 'jsx', 'go', 'py', 'rs', 'java', 'json', 'yaml', 'yml',
+                ]);
+                const deriveTermsFromFiles = (files) => {
+                    const terms = new Set();
+                    for (const f of files) {
+                        for (const seg of f.toLowerCase().split(/[/\\._-]/)) {
+                            if (seg.length > 3 && !PATH_NOISE.has(seg))
+                                terms.add(seg);
+                        }
+                    }
+                    return [...terms];
+                };
+                let warnTerms = focusTerms;
+                let warnLabel = focus;
+                let derived = false;
+                if (warnTerms.length === 0 && lastSession) {
+                    const fromFiles = deriveTermsFromFiles(lastSession.files_changed ?? []);
+                    const fromSummary = (lastSession.summary ?? '').toLowerCase()
+                        .replace(/[^a-z0-9\s:_-]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !PATH_NOISE.has(t));
+                    warnTerms = [...new Set([...fromFiles, ...fromSummary])];
+                    warnLabel = 'where you left off last session';
+                    derived = true;
+                }
+                if (warnTerms.length > 0) {
+                    const dangerLessons = lessons.filter(l => {
+                        if (l.outcome === 'success')
+                            return false;
+                        const topicCategory = l.topic.split(':')[0];
+                        return warnTerms.some(term => l.topic.toLowerCase().includes(term) ||
+                            topicCategory === term ||
+                            (l.tags ?? []).some((t) => t.toLowerCase() === term));
+                    });
+                    if (dangerLessons.length >= 1) {
+                        const headline = derived
+                            ? `  You're likely to continue **${warnLabel}** — ${dangerLessons.length} known pitfall${dangerLessons.length > 1 ? 's' : ''} there:`
+                            : `  Known pitfalls for **"${warnLabel}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`;
+                        const warning = [
+                            `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
+                            headline,
+                            ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
+                            '',
+                        ];
+                        lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+                    }
                 }
             }
             // ── 👥 Team Telepathy — what teammates learned this week ─────────────────