@cachly-dev/mcp-server 0.10.14 → 0.10.15

package/src/__tests__/auth.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const body   = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.fakesig`;
+}
+
+const nowSec = () => Math.floor(Date.now() / 1000);
+
+describe('jwtExpiryMs', () => {
+  it('returns null for an empty string', () => {
+    expect(jwtExpiryMs('')).toBeNull();
+  });
+
+  it('returns null for a plain (non-JWT) string', () => {
+    expect(jwtExpiryMs('not-a-token')).toBeNull();
+  });
+
+  it('returns null when the JWT has only two parts', () => {
+    expect(jwtExpiryMs('header.payload')).toBeNull();
+  });
+
+  it('returns null when the JWT has four parts', () => {
+    expect(jwtExpiryMs('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload base64 is invalid', () => {
+    expect(jwtExpiryMs('header.!!!.sig')).toBeNull();
+  });
+
+  it('returns null when the payload has no exp field', () => {
+    expect(jwtExpiryMs(makeJwt({ sub: 'user-123', iat: nowSec() }))).toBeNull();
+  });
+
+  it('returns null when exp is 0', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: 0 }))).toBeNull();
+  });
+
+  it('converts exp (seconds) to milliseconds', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec }))).toBe(expSec * 1000);
+  });
+
+  it('returns a past timestamp for an expired token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() - 300 }))).toBeLessThan(Date.now());
+  });
+
+  it('returns a future timestamp for a valid token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() + 86400 }))).toBeGreaterThan(Date.now());
+  });
+
+  it('handles a token expiring in less than 60 minutes', () => {
+    const expSec = nowSec() + 30 * 60;
+    const result = jwtExpiryMs(makeJwt({ exp: expSec }))!;
+    const minsLeft = Math.floor((result - Date.now()) / 60_000);
+    expect(minsLeft).toBeGreaterThanOrEqual(29);
+    expect(minsLeft).toBeLessThanOrEqual(30);
+  });
+
+  it('ignores extra claims', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ sub: 'u', iat: nowSec(), exp: expSec, plan: 'free' }))).toBe(expSec * 1000);
+  });
+
+  it('handles padding-free base64url payloads', () => {
+    // base64url (no =) — Buffer.from handles this natively
+    const expSec = nowSec() + 7200;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec, x: 'a' }))).toBe(expSec * 1000);
+  });
+});
+
+describe('checkJwt', () => {
+  it('throws InvalidRequest when jwt is empty', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ code: ErrorCode.InvalidRequest, message: expect.stringContaining('CACHLY_JWT env var not set') }),
+    );
+  });
+
+  it('throws with setup URL when jwt is missing', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('throws InvalidRequest with expiry timestamp for an expired token', () => {
+    const expSec = nowSec() - 60;
+    const token  = makeJwt({ exp: expSec });
+    expect(() => checkJwt(token)).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('expired at'),
+      }),
+    );
+  });
+
+  it('does not throw for a valid non-expired token', () => {
+    expect(() => checkJwt(makeJwt({ exp: nowSec() + 3600 }))).not.toThrow();
+  });
+
+  it('does not throw for a token with no exp claim', () => {
+    expect(() => checkJwt(makeJwt({ sub: 'user' }))).not.toThrow();
+  });
+});
+
+describe('handleApiError', () => {
+  it('throws InvalidRequest for 401 with the detail message', () => {
+    expect(() => handleApiError(401, 'token expired')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Authentication failed (401): token expired'),
+      }),
+    );
+  });
+
+  it('throws InvalidRequest for 403 with the detail message', () => {
+    expect(() => handleApiError(403, 'plan limit reached')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Access denied (403): plan limit reached'),
+      }),
+    );
+  });
+
+  it('throws InternalError for other status codes', () => {
+    expect(() => handleApiError(500, 'server crash')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InternalError,
+        message: expect.stringContaining('cachly API error 500: server crash'),
+      }),
+    );
+  });
+
+  it('includes the cachly.dev/setup-ai link for 401 errors', () => {
+    expect(() => handleApiError(401, 'Unauthorized')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('includes account access hint for 403 errors', () => {
+    expect(() => handleApiError(403, 'Forbidden')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('access to this resource') }),
+    );
+  });
+});

package/src/handlers/brain.ts

@@ -12,13 +12,15 @@ import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER }
 import { detectNamespace } from '../namespace.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.10';
+const MCP_VERSION = '0.10.0';
 const WHATS_NEW: Record<string, string[]> = {
-  '0.10.10': [
+  '0.10.0': [
     `🆕 **What's new in v${MCP_VERSION}:**`,
-    `  📌 **pin_lesson / unpin_lesson** — Pin critical lessons to always show in session_start`,
-    `  📊 **brain_stats** — At-a-glance health dashboard (lessons, streak, roadmap, pinned, top topics)`,
-    `  ✅ Pinned lessons appear at top of every session briefing — never decay, never forgotten`,
+    `  ✅ 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`,
   ],
 };
 
@@ -340,20 +342,6 @@ export async function handleBrainTool(
         }
       } catch { /* CKG updates are non-critical */ }
 
-      // ── Auto-pin critical lessons ──────────────────────────────────────────
-      // severity=critical → always pin automatically so the lesson
-      // appears in every session_start without the user ever calling pin_lesson.
-      let autoPinNote = '';
-      if (severity === 'critical' && (outcome === 'success' || outcome === 'partial')) {
-        try {
-          const alreadyPinned = await redis.exists(`cachly:lesson:pin:${topic}`);
-          if (!alreadyPinned) {
-            await redis.set(`cachly:lesson:pin:${topic}`, '1');
-            autoPinNote = `📌 Auto-pinned (critical severity) — will appear in every session_start.`;
-          }
-        } catch { /* non-critical */ }
-      }
-
       const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
       const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
       const action = isUpdate ? 'updated' : 'stored';
@@ -374,7 +362,6 @@ export async function handleBrainTool(
         depends_on.length > 0
           ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
           : '',
-        autoPinNote,
         ...templateWarnings,
         ...iWasWrongWarning,
       ].filter(l => l !== '').join('\n');
@@ -946,35 +933,6 @@ export async function handleBrainTool(
         lines.push('');
       }
 
-      // ── Pinned lessons — always shown regardless of age/confidence ───────────
-      try {
-        const pinKeys: string[] = [];
-        const pinStream = redis.scanStream({ match: 'cachly:lesson:pin:*', count: 100 });
-        await new Promise<void>((res, rej) => {
-          pinStream.on('data', (b: string[]) => pinKeys.push(...b));
-          pinStream.on('end', res);
-          pinStream.on('error', rej);
-        });
-        if (pinKeys.length > 0) {
-          const pinnedTopics = pinKeys.map(k => k.replace('cachly:lesson:pin:', ''));
-          const pinLessonRaws = await redis.mget(...pinnedTopics.map(t => `cachly:lesson:best:${t}`));
-          const pinLines: string[] = [];
-          for (const raw of pinLessonRaws) {
-            if (!raw) continue;
-            const l = safeJsonParse<{ topic: string; outcome: string; what_worked: string; severity?: string } | null>(raw, null);
-            if (!l) continue;
-            const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
-            const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-            pinLines.push(`  📌${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
-          }
-          if (pinLines.length > 0) {
-            lines.push(`📌 **Pinned lessons (always shown):**`);
-            lines.push(...pinLines);
-            lines.push('');
-          }
-        }
-      } catch { /* non-critical */ }
-
       // Recent lessons
       if (lessons.length > 0) {
         lines.push(`🕐 **Recent lessons:**`);
@@ -1461,20 +1419,6 @@ export async function handleBrainTool(
       }
 
       const durationStr = durationMin !== undefined ? ` · ${durationMin} min` : '';
-
-      // ── Mini brain-stats snapshot at session end ───────────────────────────
-      let miniStatsLines: string[] = [];
-      try {
-        const totalLessons = await redis.keys('cachly:lesson:best:*').then(k => k.length).catch(() => 0);
-        const pinCount = await redis.keys('cachly:lesson:pin:*').then(k => k.length).catch(() => 0);
-        const streakRaw = await redis.get('cachly:streak:current');
-        const streak = streakRaw ? (JSON.parse(streakRaw) as { days: number }).days : 0;
-        const parts: string[] = [`📚 ${totalLessons} lesson${totalLessons !== 1 ? 's' : ''} total`];
-        if (pinCount > 0) parts.push(`📌 ${pinCount} pinned`);
-        if (streak > 1) parts.push(`🔥 ${streak}-day streak`);
-        miniStatsLines = [`🧠 **Brain:** ${parts.join(' · ')}`];
-      } catch { /* non-critical */ }
-
       return [
         `✅ **Session saved**${durationStr}`,
         ``,
@@ -1483,7 +1427,6 @@ export async function handleBrainTool(
         lessons_learned !== undefined ? `🧠 **Lessons stored:** ${lessons_learned}` : '',
         autoLearned.length > 0 ? `🤖 **Auto-learned:** ${autoLearned.length} lessons extracted from summary (${autoLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${autoLearned.length > 3 ? '…' : ''})` : '',
         ambientLearned.length > 0 ? `🌿 **Ambient git learning:** ${ambientLearned.length} commit${ambientLearned.length > 1 ? 's' : ''} auto-learned (${ambientLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${ambientLearned.length > 3 ? '…' : ''})` : '',
-        ...miniStatsLines,
         ``,
         `💡 Next session: \`session_start(focus="...")\` to see this summary.`,
       ].filter(l => l !== '').join('\n');

package/src/handlers/fedbrain.ts

@@ -6,6 +6,7 @@ import { calculateConfidence, confidenceBadge, CONFIDENCE_WARN_VALUE, CONFIDENCE
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // Git concurrency semaphore (for brain_from_git parallel workers)
@@ -397,7 +398,8 @@ export async function handleFedbrainTool(
       const raw = await redis.get(`cachly:lesson:best:${lesson_key}`);
       if (!raw) return `❌ Lesson \`${lesson_key}\` not found. Store it first with \`learn_from_attempts\`.`;
 
-      const lesson = JSON.parse(raw) as { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string };
+      const lesson = safeJsonParse(raw, null as null | { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string });
+      if (!lesson) return `❌ Lesson \`${lesson_key}\` data is corrupted. Re-store with \`learn_from_attempts\`.`;
 
       const domainTokens = [lesson.topic.split(':')[0], ...(lesson.tags ?? [])].filter(Boolean);
       const domainFingerprint = [...new Set(domainTokens)].sort().join(',');
@@ -747,7 +749,8 @@ export async function handleFedbrainTool(
       }
 
       type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }>; categories: string[]; created_from: string };
-      const crystal: Crystal = JSON.parse(raw);
+      const crystal = safeJsonParse<Crystal | null>(raw, null);
+      if (!crystal) return `❌ Memory Crystal data is corrupted. Re-create with \`memory_crystalize()\`.`;
       const age = Math.floor((Date.now() - new Date(crystal.ts).getTime()) / 86400000);
       const freshEmoji = age <= 7 ? '🟢' : age <= 30 ? '🟡' : '🔴';
 
@@ -784,49 +787,55 @@ export async function handleFedbrainTool(
       const crystalRaw = await redis.get('cachly:crystal:latest');
       if (crystalRaw) {
         type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }> };
-        const crystal: 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('');
+        const crystal = safeJsonParse<Crystal | null>(crystalRaw, null);
+        if (crystal) {
+          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) {
         type Session = { summary?: string; ts?: string; focus?: string };
-        const sess: Session = 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('');
+        const sess = safeJsonParse<Session | null>(lastSession, null);
+        if (sess) {
+          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) {
         type Handoff = { remaining_tasks?: string[]; instructions?: string; context_summary?: string; blocked_on?: string };
-        const h: Handoff = 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}`);
+        const h = safeJsonParse<Handoff | null>(handoff, null);
+        if (h) {
+          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('');
         }
-        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) {
         type Ctx = { content?: string };
-        const wip: Ctx = JSON.parse(wipRaw);
-        if (wip.content) {
+        const wip = safeJsonParse<Ctx | null>(wipRaw, null);
+        if (wip?.content) {
           lines.push(`### 🔧 WIP Registry`);
           lines.push(wip.content.slice(0, 400));
           lines.push('');
@@ -884,8 +893,8 @@ export async function handleFedbrainTool(
 
     // ── brain_from_git ────────────────────────────────────────────────────────
     case 'brain_from_git': {
-      const { instance_id, repo_path = '.', limit = 100, branch = 'HEAD', since = '' } = args as {
-        instance_id: string; repo_path?: string; limit?: number; branch?: string; since?: string;
+      const { instance_id, repo_path = '.', limit = 100, branch = 'HEAD', since = '', incremental = true } = args as {
+        instance_id: string; repo_path?: string; limit?: number; branch?: string; since?: string; incremental?: boolean;
       };
       const redis = await getConnection(instance_id);
       const { execSync } = await import('node:child_process');
@@ -904,9 +913,21 @@ export async function handleFedbrainTool(
         return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
       }
 
+      // Incremental mode: resume from last processed commit SHA
+      const lastShaKey = `cachly:brain_from_git:last_sha:${Buffer.from(repoDir).toString('base64').slice(0, 32)}`;
+      let lastSha = '';
+      let isIncremental = false;
+      if (incremental !== false && !since) {
+        lastSha = (await redis.get(lastShaKey)) ?? '';
+        isIncremental = Boolean(lastSha);
+      }
+
       // Build git log command
+      // In incremental mode, only fetch commits after the last processed SHA
       const sinceFlag = since ? `--since="${since}"` : '';
-      const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
+      const afterFlag = isIncremental ? `${lastSha}..HEAD` : '';
+      const revRange = afterFlag || branch;
+      const logCmd = `git log ${revRange} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
 
       let logOutput = '';
       try {
@@ -921,6 +942,9 @@ export async function handleFedbrainTool(
       });
 
       if (commits.length === 0) {
+        if (isIncremental) {
+          return `✅ brain_from_git: Brain is up to date — no new commits since last run (last SHA: \`${lastSha.slice(0, 8)}\`).`;
+        }
         return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
       }
 
@@ -951,8 +975,21 @@ export async function handleFedbrainTool(
       let ingested = 0;
       let skipped = 0;
       const categoryCount = new Map<string, number>();
+      const total = commits.length;
+      const progressInterval = Math.max(1, Math.floor(total / 10)); // emit ~10 progress updates
+      let lastProgressAt = 0;
+
+      process.stderr.write(`\n🧠 brain_from_git: processing ${total} commits from ${repoDir}...\n`);
+
+      for (let i = 0; i < commits.length; i++) {
+        const commit = commits[i]!;
+
+        // Emit progress to stderr so editors can display it in MCP logs
+        if (i - lastProgressAt >= progressInterval) {
+          process.stderr.write(`   ⏳ Processing ${i}/${total} commits (${ingested} lessons so far)...\n`);
+          lastProgressAt = i;
+        }
 
-      for (const commit of commits) {
         if (!commit.subject) { skipped++; continue; }
         const { category, outcome, severity } = classifyCommit(commit.subject);
         const domain = extractDomain(commit.subject);
@@ -987,11 +1024,20 @@ export async function handleFedbrainTool(
         ingested++;
       }
 
+      process.stderr.write(`   ✅ brain_from_git complete: ${ingested}/${total} commits ingested\n\n`);
+
+      // Save the latest commit SHA for incremental runs
+      if (commits.length > 0 && commits[0]?.sha) {
+        await redis.set(lastShaKey, commits[0].sha, 'EX', 90 * 24 * 3600); // expire after 90 days
+      }
+
       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}`,
+        `🔁 **brain_from_git: ${repoDir}**`,
+        isIncremental ? `🔄 Incremental mode — only new commits since \`${lastSha.slice(0, 8)}\` were processed` : '',
+        ``,
+        `📂 Branch: \`${revRange}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
         ``,
         `**Breakdown by category:**`,
         categoryBreakdown,
@@ -999,7 +1045,8 @@ export async function handleFedbrainTool(
         `💡 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');
+        `💾 Next run will automatically continue from the latest commit (incremental mode).`,
+      ].filter(Boolean).join('\n');
       } finally {
         _gitSemRelease();
       }
@@ -1026,12 +1073,14 @@ export async function handleFedbrainTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           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: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             if (edge.edgeType !== 'causes' && edge.edgeType !== 'degrades_under') continue;
 
             // Look up fix for this failure from CKG 'fixes' edges
@@ -1040,12 +1089,13 @@ export async function handleFedbrainTool(
             for (const fek of fixEdgeKeys.slice(0, 10)) {
               const feRaw = await redis.get(fek);
               if (!feRaw) continue;
-              const fe: CKGEdge = JSON.parse(feRaw);
+              const fe = safeJsonParse<CKGEdge | null>(feRaw, null);
+              if (!fe) continue;
               if (fe.edgeType === 'fixes') {
                 const lessonRaw = await redis.get(`cachly:lesson:best:${fe.from}`);
                 if (lessonRaw) {
-                  const lesson = JSON.parse(lessonRaw) as { what_worked?: string };
-                  fix = lesson.what_worked?.slice(0, 120);
+                  const lesson = safeJsonParse(lessonRaw, null as null | { what_worked?: string });
+                  fix = lesson?.what_worked?.slice(0, 120);
                   break;
                 }
               }

package/src/handlers/roadmap.ts

@@ -1,4 +1,5 @@
 import type { Redis } from 'ioredis';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -67,7 +68,8 @@ export async function handleRoadmapTool(
       const redis = await getConnection(rid);
       const raw = await redis.hget(`cachly:roadmap:${rid}`, itemId);
       if (!raw) return `⚠️ **roadmap_update** – Item \`${itemId}\` not found. Use \`roadmap_list\` to see all items.`;
-      const item = JSON.parse(raw) as Record<string, unknown>;
+      const item = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!item) return `⚠️ **roadmap_update** – Item \`${itemId}\` data is corrupted. Re-add with \`roadmap_add\`.`;
       const oldStatus = item.status as string;
       if (newStatus) item.status = newStatus;
       if (newPriority) item.priority = newPriority;
@@ -106,7 +108,10 @@ export async function handleRoadmapTool(
       const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
       const STATUS_ICON: Record<string, string> = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
       const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
-      let items = Object.values(all).map(v => JSON.parse(v as string) as Record<string, string | string[]>);
+      let items = Object.values(all).flatMap(v => {
+        const item = safeJsonParse<Record<string, string | string[]> | null>(v as string, null);
+        return item ? [item] : [];
+      });
       // Filter
       if (filterStatus === 'open') items = items.filter(i => openStatuses.has(i.status as string));
       else if (filterStatus) items = items.filter(i => i.status === filterStatus);

package/src/handlers/syndicate.ts

@@ -4,6 +4,7 @@ import { calculateConfidence } from '../confidence.js';
 import { ckgSlug, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -292,7 +293,8 @@ export async function handleSyndicateTool(
         for (const ek of [...fromKeys, ...toKeys].slice(0, 50)) {
           const raw = await redis.get(ek);
           if (!raw) continue;
-          const edge: CKGEdge = JSON.parse(raw);
+          const edge = safeJsonParse<CKGEdge | null>(raw, null);
+          if (!edge) continue;
           allEdges.push(edge);
           if (hop < max_hops) {
             if (!visited.has(edge.from)) queue.push({ id: edge.from, hop: hop + 1 });
@@ -366,16 +368,18 @@ export async function handleSyndicateTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           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: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             // Only interested in fixes and co-occurs for prediction
             if (edge.edgeType !== 'fixes' && edge.edgeType !== 'co-occurs' && edge.edgeType !== 'causes') continue;
             const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from}`);
-            const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+            const lesson = lessonRaw ? safeJsonParse<{ what_worked?: string; topic: string } | null>(lessonRaw, null) ?? undefined : undefined;
             predictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
           }
         }
@@ -389,15 +393,17 @@ export async function handleSyndicateTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+        {
+          type PredLesson = { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+          const l = safeJsonParse<PredLesson | null>(raw, null);
+          if (!l) continue;
           const haystack = [l.topic, l.what_failed ?? '', l.what_worked ?? ''].join(' ').toLowerCase();
           const score = ctxTokens.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
           if (score >= 1 && l.outcome !== 'failure') {
             const conf = calculateConfidence(l);
             textPredictions.push({ ...l, confidence: conf });
           }
-        } catch { /* skip */ }
+        }
       }
       textPredictions.sort((a, b) => b.confidence - a.confidence);