@cachly-dev/mcp-server 0.10.55 → 0.10.57

package/src/handlers/context.ts

@@ -64,13 +64,18 @@ export async function handleContextTool(
           if (ttl && ttl > 0) {
             body['expires_at'] = new Date(Date.now() + ttl * 1000).toISOString();
           }
-          await fetch(`${vectorUrl}/entries`, {
+          const res = await fetch(`${vectorUrl}/entries`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
-          }).catch(() => undefined);
-        } catch {
-          // Embedding optional — continue silently
+            signal: AbortSignal.timeout(8000),
+          });
+          if (!res.ok) {
+            process.stderr.write(`[cachly] semantic index skipped (HTTP ${res.status}) — smart_recall on this context will be keyword-only\n`);
+          }
+        } catch (e) {
+          // Embedding is optional — keyword recall still works. Log so it's debuggable.
+          process.stderr.write(`[cachly] semantic index failed: ${e instanceof Error ? e.message : String(e)} — smart_recall on this context will be keyword-only\n`);
         }
       }
 

package/src/handlers/fedbrain.ts

@@ -9,6 +9,9 @@ import { keywordSearch, tokenize } from '../search.js';
 import { safeJsonParse } from '../utils.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
+// Last brain_from_git category counts — set after each run so index.ts can include them in telemetry
+export let _lastBrainFromGitCounts: { fixes: number; features: number; refactors: number; total: number } | null = null;
+
 // Git concurrency semaphore (for brain_from_git parallel workers)
 let _gitSemCount = 0;
 const _GIT_SEM_MAX = 10;
@@ -363,8 +366,6 @@ export async function handleFedbrainTool(
 
       if (hooksArr.includes('ci')) {
         lines.push(`### GitHub Actions CI outcome hook`);
-        lines.push(`**Setup:** add a repo secret \`CACHLY_CACHE_TOKEN\` = your instance's cache token`);
-        lines.push(`(find it via \`get_connection_string\` — the token in the cache URL).`);
         lines.push(`**Add at the end of each job** (after build/test steps):`);
         lines.push('```yaml');
         lines.push(`- name: cachly CLS — record CI outcome`);
@@ -372,14 +373,15 @@ export async function handleFedbrainTool(
         lines.push(`  run: |`);
         lines.push(`    node -e "`);
         lines.push(`    const r=require('https');`);
-        lines.push(`    const d=JSON.stringify({source:'ci_outcome',payload:{`);
+        lines.push(`    const d=JSON.stringify({instance_id:'${instance_id}',source:'ci_outcome',payload:{`);
         lines.push(`      status:'\${{ job.status }}',prev_status:'unknown',job:'\${{ github.job }}',`);
         lines.push(`      context:'github-actions run \${{ github.run_number }}'}});`);
-        lines.push(`    r.request({hostname:'api.cachly.dev',path:'/v1/cache/'+process.env.CACHLY_CACHE_TOKEN+'/cls/ingest',method:'POST',`);
-        lines.push(`      headers:{'Content-Type':'application/json','Content-Length':d.length}},()=>{}).end(d);`);
+        lines.push(`    r.request({hostname:'api.cachly.dev',path:'/api/v1/cls/ingest',method:'POST',`);
+        lines.push(`      headers:{'Content-Type':'application/json','Authorization':'Bearer $CACHLY_JWT',`);
+        lines.push(`        'Content-Length':d.length}},()=>{}).end(d);`);
         lines.push(`    " 2>/dev/null || true`);
         lines.push(`  env:`);
-        lines.push(`    CACHLY_CACHE_TOKEN: \${{ secrets.CACHLY_CACHE_TOKEN }}`);
+        lines.push(`    CACHLY_JWT: \${{ secrets.CACHLY_JWT }}`);
         lines.push('```');
         lines.push('');
       }
@@ -1013,11 +1015,16 @@ export async function handleFedbrainTool(
         // 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));
+          // Auto-inferred git lessons get a 90-day TTL — they self-refresh on the next
+          // brain_from_git run, and shouldn't pin memory forever if the repo goes stale.
+          await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj), 'EX', 90 * 86400);
           await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+          await redis.ltrim(`cachly:lessons:${topic}`, -100, -1);
+          await redis.expire(`cachly:lessons:${topic}`, 90 * 86400);
         }
         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);
+        await redis.expire('cachly:lessons:brain_from_git:all', 90 * 86400);
 
         // Update CKG
         const conceptId = ckgSlug(topic);
@@ -1034,6 +1041,13 @@ export async function handleFedbrainTool(
 
       const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
 
+      _lastBrainFromGitCounts = {
+        fixes: categoryCount.get('fix') ?? 0,
+        features: categoryCount.get('feat') ?? 0,
+        refactors: categoryCount.get('refactor') ?? 0,
+        total: ingested,
+      };
+
       return [
         `🔁 **brain_from_git: ${repoDir}**`,
         isIncremental ? `🔄 Incremental mode — only new commits since \`${lastSha.slice(0, 8)}\` were processed` : '',

package/src/handlers/roadmap.ts

@@ -157,9 +157,12 @@ export async function handleRoadmapTool(
       const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
       const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
       const items = Object.values(all)
-        .map(v => JSON.parse(v as string) as Record<string, unknown>)
+        .flatMap(v => {
+          const item = safeJsonParse<Record<string, unknown> | null>(v as string, null);
+          return item ? [item] : [];
+        })
         .filter(i => i.status === 'in-progress' || i.status === 'planned')
-        .filter(i => !filterTag || (i.tags as string[]).includes(filterTag));
+        .filter(i => !filterTag || (Array.isArray(i.tags) ? i.tags : []).includes(filterTag));
       if (items.length === 0) return '🎉 **No open roadmap items!** All tasks are done (or use `roadmap_list` to check).';
       // in-progress first, then by priority
       items.sort((a, b) => {
@@ -169,7 +172,8 @@ export async function handleRoadmapTool(
       });
       const next = items[0];
       const remaining = items.length - 1;
-      const tags = (next.tags as string[]).length ? `\nTags:      ${(next.tags as string[]).join(', ')}` : '';
+      const nextTags = Array.isArray(next.tags) ? next.tags as string[] : [];
+      const tags = nextTags.length ? `\nTags:      ${nextTags.join(', ')}` : '';
       const milestone = next.milestone ? `\nMilestone: ${next.milestone}` : '';
       const notes = next.notes ? `\nNotes:     ${(next.notes as string).split('\n').pop()?.slice(0, 120)}` : '';
       return [

package/src/handlers/tco.ts

@@ -0,0 +1,347 @@
+/**
+ * Travel Chaos Organizer — MCP bridge.
+ *
+ * Exposes the TCO REST API as MCP tools so any Claude instance with cachly-mcp
+ * configured can manage travel plans through natural language.
+ *
+ * Auth: TCO and Cachly share the same Keycloak realm, so the Cachly JWT
+ * (CACHLY_JWT env var) is forwarded as-is to the TCO backend — no extra
+ * credentials needed.
+ *
+ * Config:
+ *   TCO_API_URL   — base URL of the TCO FastAPI backend (e.g. http://localhost:8000)
+ *                   If not set, all tools return a configuration error.
+ */
+
+const TCO_URL = process.env.TCO_API_URL ?? '';
+
+export const TCO_TOOL_NAMES = new Set([
+  'tco_list_trips',
+  'tco_create_trip',
+  'tco_get_timeline',
+  'tco_delete_trip',
+  'tco_inbox_list',
+  'tco_inbox_assign',
+  'tco_inbox_reject',
+  'tco_parse_url',
+  'tco_import_email',
+  'tco_parse_text',
+  'tco_cache_stats',
+  'tco_provision_cache',
+  'tco_telegram_status',
+  'tco_telegram_send',
+]);
+
+type TcoFetch = (path: string, jwt: string, init?: RequestInit) => Promise<unknown>;
+
+async function tcoFetch(path: string, jwt: string, init: RequestInit = {}): Promise<unknown> {
+  if (!TCO_URL) {
+    throw new Error(
+      'TCO_API_URL is not configured. Add `TCO_API_URL=http://<your-tco-host>:8000` to your environment.'
+    );
+  }
+  const res = await fetch(`${TCO_URL}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${jwt}`,
+      'Content-Type': 'application/json',
+      ...(init.headers ?? {}),
+    },
+    signal: AbortSignal.timeout(20_000),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`TCO API ${res.status}: ${text}`);
+  }
+
+  const ct = res.headers.get('content-type') ?? '';
+  if (res.status === 204 || !ct.includes('application/json')) return null;
+  return res.json();
+}
+
+function noConfig(): string {
+  return (
+    '⚙️  **TCO not configured.**\n\n' +
+    'Set `TCO_API_URL=http://<host>:8000` in your environment and restart cachly-mcp.\n' +
+    'See `apps/travel-chaos-organizer/README.md` for setup instructions.'
+  );
+}
+
+function fmt(data: unknown): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export async function handleTcoTool(
+  name: string,
+  args: Record<string, unknown>,
+  jwt: string,
+): Promise<string | null> {
+  if (!TCO_TOOL_NAMES.has(name)) return null;
+  if (!TCO_URL) return noConfig();
+
+  try {
+    switch (name) {
+
+      // ── List all trips ───────────────────────────────────────────────────
+      case 'tco_list_trips': {
+        const trips = await tcoFetch('/api/v1/trips', jwt);
+        const list = trips as Array<Record<string, unknown>>;
+        if (!list.length) return '📭 No trips yet. Use `tco_create_trip` to get started.';
+        const rows = list.map((t) => {
+          const dates = t.start_date
+            ? `${t.start_date}${t.end_date ? ` → ${t.end_date}` : ''}`
+            : 'no dates';
+          return `• **${t.name}** \`${t.id}\` — ${dates}`;
+        });
+        return `🗺️  **Your trips (${list.length}):**\n\n${rows.join('\n')}`;
+      }
+
+      // ── Create a trip ────────────────────────────────────────────────────
+      case 'tco_create_trip': {
+        const { name: tripName, description = null, start_date = null, end_date = null } = args as {
+          name: string; description?: string | null; start_date?: string | null; end_date?: string | null;
+        };
+        const trip = await tcoFetch('/api/v1/trips', jwt, {
+          method: 'POST',
+          body: JSON.stringify({ name: tripName, description, start_date, end_date }),
+        });
+        const t = trip as Record<string, unknown>;
+        return `✅ Trip **${t.name}** created (id: \`${t.id}\`)`;
+      }
+
+      // ── Get timeline for a trip ──────────────────────────────────────────
+      case 'tco_get_timeline': {
+        const { trip_id } = args as { trip_id: string };
+        const items = await tcoFetch(`/api/v1/trips/${trip_id}/items`, jwt);
+        const list = items as Array<Record<string, unknown>>;
+        if (!list.length) return `📂 Trip \`${trip_id}\` has no timeline items yet. Upload a document to get started.`;
+
+        const TYPE_ICONS: Record<string, string> = {
+          flight: '✈️', train: '🚂', bus: '🚌', hotel: '🏨',
+          rental_car: '🚗', activity: '🎡', transfer: '🚕', document: '📄', other: '📋',
+        };
+        const rows = list.map((i) => {
+          const icon = TYPE_ICONS[i.type as string] ?? '📋';
+          const time = i.event_at ? ` · ${(i.event_at as string).slice(0, 16).replace('T', ' ')}` : '';
+          const ref = i.booking_ref ? ` · #${i.booking_ref}` : '';
+          const provider = i.provider ? ` · ${i.provider}` : '';
+          return `${icon} **${i.title}**${time}${provider}${ref}`;
+        });
+        return `📅 **Timeline (${list.length} items):**\n\n${rows.join('\n')}`;
+      }
+
+      // ── Delete a trip ────────────────────────────────────────────────────
+      case 'tco_delete_trip': {
+        const { trip_id } = args as { trip_id: string };
+        await tcoFetch(`/api/v1/trips/${trip_id}`, jwt, { method: 'DELETE' });
+        return `🗑️ Trip \`${trip_id}\` deleted.`;
+      }
+
+      // ── Inbox: list pending items ────────────────────────────────────────
+      case 'tco_inbox_list': {
+        const status = (args.status as string | undefined) ?? 'pending';
+        const items = await tcoFetch(`/api/v1/inbox?status_filter=${status}`, jwt);
+        const list = items as Array<Record<string, unknown>>;
+        if (!list.length) return `🎉 Chaos inbox is empty (status: ${status}).`;
+        const rows = list.map((i) => {
+          const pd = i.parsed_data as Record<string, unknown> | null;
+          const title = (pd?.title as string | undefined) ?? '(no title)';
+          const src = (i.source as string | undefined) ?? 'unknown source';
+          return `• **${title}** \`${i.id}\` — from ${src}`;
+        });
+        return `📥 **Inbox (${list.length} ${status}):**\n\n${rows.join('\n')}\n\nUse \`tco_inbox_assign\` to move to a trip.`;
+      }
+
+      // ── Inbox: assign item to trip ───────────────────────────────────────
+      case 'tco_inbox_assign': {
+        const { inbox_id, trip_id, type = 'other' } = args as {
+          inbox_id: string; trip_id: string; type?: string;
+        };
+        const result = await tcoFetch(`/api/v1/inbox/${inbox_id}/assign`, jwt, {
+          method: 'POST',
+          body: JSON.stringify({ trip_id, type }),
+        });
+        const r = result as Record<string, unknown>;
+        return `✅ Inbox item assigned to trip. New timeline item id: \`${r.trip_item_id}\``;
+      }
+
+      // ── Inbox: reject / delete item ──────────────────────────────────────
+      case 'tco_inbox_reject': {
+        const { inbox_id } = args as { inbox_id: string };
+        await tcoFetch(`/api/v1/inbox/${inbox_id}`, jwt, { method: 'DELETE' });
+        return `🗑️ Inbox item \`${inbox_id}\` rejected and removed.`;
+      }
+
+      // ── Parse a public URL into a trip ───────────────────────────────────
+      case 'tco_parse_url': {
+        const { url, trip_id } = args as { url: string; trip_id?: string };
+        const body: Record<string, string> = { url };
+        if (trip_id) body.trip_id = trip_id;
+        const result = await tcoFetch('/api/v1/parse/url', jwt, {
+          method: 'POST',
+          body: JSON.stringify(body),
+        });
+        const r = result as Record<string, unknown>;
+        const confidence = typeof r.confidence === 'number' ? ` (confidence: ${Math.round(r.confidence * 100)}%)` : '';
+        const dest = trip_id ? `trip \`${trip_id}\`` : 'chaos inbox';
+        return `✅ URL parsed and saved to ${dest}${confidence}.\n\nParsed: ${fmt(r.parsed_data ?? r)}`;
+      }
+
+      // ── Import email text into inbox or trip ─────────────────────────────
+      case 'tco_import_email': {
+        const { raw_email, trip_id } = args as { raw_email: string; trip_id?: string };
+        const body: Record<string, string> = { raw_email };
+        if (trip_id) body.trip_id = trip_id;
+        const result = await tcoFetch('/api/v1/mail/import', jwt, {
+          method: 'POST',
+          body: JSON.stringify(body),
+        });
+        const r = result as Record<string, unknown>;
+        const dest = trip_id ? `trip \`${trip_id}\`` : 'chaos inbox';
+        return `✅ Email imported to ${dest}. Inbox id: \`${r.inbox_id ?? '?'}\``;
+      }
+
+      // ── Parse raw text via Ollama (Cachly-cached) ────────────────────────
+      case 'tco_parse_text': {
+        const { text, trip_id } = args as { text: string; trip_id?: string };
+        const params = new URLSearchParams();
+        params.set('raw_text', text);
+        if (trip_id) params.set('trip_id', trip_id);
+        const result = await tcoFetch('/api/v1/parse/text', jwt, {
+          method: 'POST',
+          body: params.toString(),
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        });
+        const r = result as Record<string, unknown>;
+        const parsed = r.parsed as Record<string, unknown> | undefined;
+        const cached = (r as Record<string, unknown>).cached;
+        const dest = trip_id ? `trip \`${trip_id}\`` : 'Chaos Inbox';
+        const cacheNote = cached ? ' ⚡ **(Cache Hit — kein AI-Call)**' : '';
+        const confidence = typeof parsed?.confidence === 'number'
+          ? ` (confidence: ${Math.round((parsed.confidence as number) * 100)}%)`
+          : '';
+        return `✅ Text geparst und in ${dest} gespeichert${confidence}${cacheNote}.\n\nParsed: ${fmt(parsed ?? r)}`;
+      }
+
+      // ── Cachly Redis cache stats ─────────────────────────────────────────
+      case 'tco_cache_stats': {
+        const stats = await tcoFetch('/api/v1/cache/stats', jwt) as Record<string, unknown>;
+        if (!stats.configured) {
+          return (
+            '📭 **Cachly Redis ist nicht verbunden.**\n\n' +
+            'Setze `CACHLY_REDIS_URL=redis://<host>:6379/0` in der TCO `.env` und deploye neu.\n' +
+            'Nutze `tco_provision_cache` um eine kostenlose Cachly-Instanz zu erstellen.'
+          );
+        }
+        const hits = stats.hits as number;
+        const misses = stats.misses as number;
+        const total = hits + misses;
+        const hitPct = total > 0 ? Math.round((hits / total) * 100) : 0;
+        const saved = hits > 0
+          ? `\n\n💡 **~${hits} AI-Calls eingespart** (jeder Cache Hit = kein Ollama-Aufruf).`
+          : '';
+        return (
+          `✅ **Cachly Redis — aktiv**\n\n` +
+          `| Metric | Wert |\n|--------|------|\n` +
+          `| Cache Hits | **${hits}** |\n` +
+          `| Cache Misses | ${misses} |\n` +
+          `| Hit Rate | **${hitPct}%** |\n` +
+          `| Gecachte Dokumente | ${stats.key_count} |\n` +
+          `| TTL | ${stats.ttl_days} Tage |` +
+          saved
+        );
+      }
+
+      // ── Provision a Cachly free instance for TCO ─────────────────────────
+      case 'tco_provision_cache': {
+        const CACHLY_API = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
+        const res = await fetch(`${CACHLY_API}/api/v1/instances`, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${jwt}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ name: 'tco-cache', tier: 'free' }),
+          signal: AbortSignal.timeout(30_000),
+        });
+
+        if (!res.ok) {
+          const txt = await res.text().catch(() => '');
+          // Instance may already exist — try to fetch it
+          if (res.status === 409 || txt.includes('already')) {
+            const listRes = await fetch(`${CACHLY_API}/api/v1/instances`, {
+              headers: { Authorization: `Bearer ${jwt}` },
+            });
+            if (listRes.ok) {
+              const list = await listRes.json() as Array<Record<string, unknown>>;
+              const existing = list.find((i) => i.name === 'tco-cache');
+              if (existing) {
+                return (
+                  `ℹ️ **Instanz "tco-cache" existiert bereits.**\n\n` +
+                  `Redis URL: \`${existing.redis_url ?? existing.connection_string ?? '(siehe Cachly Dashboard)'}\`\n\n` +
+                  `Setze in der TCO \`.env\`:\n\`\`\`\nCACHLY_REDIS_URL=${existing.redis_url ?? existing.connection_string}\n\`\`\`\n` +
+                  `Dann: \`bash scripts/deploy.sh\``
+                );
+              }
+            }
+          }
+          throw new Error(`Cachly API ${res.status}: ${txt}`);
+        }
+
+        const instance = await res.json() as Record<string, unknown>;
+        const redisUrl = instance.redis_url ?? instance.connection_string ?? '';
+        return (
+          `🎉 **Cachly Redis Instanz erstellt!**\n\n` +
+          `Name: \`tco-cache\` (Free Tier, 25 MB)\n` +
+          `Redis URL: \`${redisUrl}\`\n\n` +
+          `**Setup (2 Schritte):**\n` +
+          `1. Füge zur TCO \`.env\` hinzu:\n\`\`\`\nCACHLY_REDIS_URL=${redisUrl}\n\`\`\`\n` +
+          `2. Neu deployen:\n\`\`\`bash\nbash scripts/deploy.sh\n\`\`\`\n\n` +
+          `Ab sofort werden alle Ollama Parse-Ergebnisse gecacht — kein zweiter AI-Call für dasselbe Dokument.`
+        );
+      }
+
+      // ── Telegram: check linked status ────────────────────────────────────
+      case 'tco_telegram_status': {
+        const me = await tcoFetch('/api/v1/users/me', jwt) as Record<string, unknown>;
+        const linked = me.telegram_linked === true;
+        if (linked) {
+          return (
+            `✅ **Telegram ist verknüpft.**\n\n` +
+            `Plan: ${me.plan === 'pro' ? '✦ Pro' : 'Free'}\n\n` +
+            `Du kannst mit \`tco_telegram_send\` direkt Nachrichten an den User senden.`
+          );
+        }
+        return (
+          `🔴 **Telegram nicht verknüpft.**\n\n` +
+          `Der User muss in der TCO-App unter *Einstellungen → Mit Telegram verknüpfen* einen PIN generieren ` +
+          `und diesen an @TCOBot senden (\`/link <PIN>\`).`
+        );
+      }
+
+      // ── Telegram: send message to user ───────────────────────────────────
+      case 'tco_telegram_send': {
+        const { message } = args as { message: string };
+        const me = await tcoFetch('/api/v1/users/me', jwt) as Record<string, unknown>;
+        if (!me.telegram_linked) {
+          return (
+            `🔴 **Telegram nicht verknüpft** — Nachricht wurde nicht gesendet.\n\n` +
+            `Nutze \`tco_telegram_status\` für Details zur Verknüpfung.`
+          );
+        }
+        await tcoFetch('/api/v1/users/telegram-notify', jwt, {
+          method: 'POST',
+          body: JSON.stringify({ message }),
+        });
+        return `✅ Telegram-Nachricht gesendet:\n\n> ${message.slice(0, 200)}${message.length > 200 ? '…' : ''}`;
+      }
+
+      default:
+        return null;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `❌ TCO error: ${msg}`;
+  }
+}

package/src/handlers/team.ts

@@ -11,7 +11,7 @@ type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
 
 export const TEAM_TOOL_NAMES = new Set([
-  'sync_file_changes', 'team_learn', 'team_recall', 'team_synthesize', 'memory_crystalize',
+  'sync_file_changes', 'team_learn', 'team_confirm', 'team_recall', 'team_synthesize', 'memory_crystalize',
   'brain_doctor', 'recall_at', 'trace_dependency', 'global_learn', 'global_recall',
   'publish_lesson', 'import_public_brain', 'setup_ai_memory',
 ]);
@@ -109,9 +109,7 @@ export async function handleTeamTool(
         file_paths: file_paths ?? [],
         commands: commands ?? [],
         tags: [...(tags ?? []), 'team'],
-        ts: new Date().toISOString(),
-        verified_at: outcome === 'success' ? new Date().toISOString() : undefined,
-        confidence: 1.0,
+        timestamp: new Date().toISOString(),
         recall_count: 0,
         version: 2,
       };
@@ -126,6 +124,59 @@ export async function handleTeamTool(
       return `✅ Team lesson stored by **${author}**: \`${topic}\` (${outcome})\n💡 ${what_worked.slice(0, 120)}`;
     }
 
+    // ── team_confirm — knowledge governance (Phase 3) ─────────────────────────
+    // A human reviewer endorses a stored lesson. The endorsement raises the
+    // lesson's recall ranking (see src/rerank.ts), so trusted, reviewed knowledge
+    // surfaces above unreviewed auto-learned entries.
+    case 'team_confirm': {
+      const { instance_id, topic, reviewer, level = 'peer', note = '' } = args as {
+        instance_id: string; topic: string; reviewer: string;
+        level?: 'senior' | 'peer'; note?: string;
+      };
+      if (!instance_id) return '❌ instance_id required';
+      if (!topic || !reviewer) return '❌ Required: topic, reviewer';
+      const reviewLevel = level === 'senior' ? 'senior' : 'peer';
+
+      const redis = await getConnection(instance_id);
+      const key = `cachly:lesson:best:${topic}`;
+      const raw = await redis.get(key);
+      const lesson = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!lesson) {
+        return `📭 No best-solution lesson found for \`${topic}\`.\n\nA lesson must exist (store one with \`team_learn\` / \`learn_from_attempts\`) before it can be confirmed.`;
+      }
+
+      // Track distinct reviewers so endorsements can't be inflated by one person.
+      const endorsersKey = `cachly:lesson:endorsers:${topic}`;
+      const added = await redis.sadd(endorsersKey, reviewer);
+      await redis.expire(endorsersKey, 365 * 86400);
+      const endorsements = await redis.scard(endorsersKey);
+
+      // Senior beats peer; never downgrade an existing senior review to peer.
+      const prevLevel = (lesson.review_level as string) ?? '';
+      const effectiveLevel = prevLevel === 'senior' ? 'senior' : reviewLevel;
+
+      const updated = {
+        ...lesson,
+        reviewed_by: reviewer,
+        review_level: effectiveLevel,
+        endorsements,
+        reviewed_at: new Date().toISOString(),
+      };
+      await redis.set(key, JSON.stringify(updated));
+
+      // Append an immutable review record for the audit trail.
+      const reviewLog = {
+        reviewer, level: reviewLevel, note: note.slice(0, 280), ts: new Date().toISOString(),
+      };
+      const logKey = `cachly:lesson:reviews:${topic}`;
+      await redis.rpush(logKey, JSON.stringify(reviewLog));
+      await redis.ltrim(logKey, -50, -1);
+      await redis.expire(logKey, 365 * 86400);
+
+      const badge = effectiveLevel === 'senior' ? '🛡️ senior-reviewed' : '✔️ peer-reviewed';
+      return `${badge} — \`${topic}\` confirmed by **${reviewer}** (${endorsements} distinct endorsement${endorsements === 1 ? '' : 's'}).\n📈 This lesson now ranks higher in \`smart_recall\` / \`team_recall\`.${note ? `\n📝 ${note.slice(0, 200)}` : ''}`;
+    }
+
     // ── team_recall ───────────────────────────────────────────────────────────
     case 'team_recall': {
       const { instance_id, topic, author, limit = 10 } = args as {
@@ -148,6 +199,7 @@ export async function handleTeamTool(
         topic: string; outcome: string; what_worked: string;
         ts: string; severity?: string; recall_count?: number;
         author?: string; tags?: string[];
+        reviewed_by?: string; review_level?: string; endorsements?: number;
       };
       let lessons: TeamLesson[] = [];
       if (lessonKeys.length > 0) {
@@ -171,8 +223,10 @@ export async function handleTeamTool(
         lessons = lessons.filter(l => l.author?.toLowerCase().includes(a));
       }
 
-      // Sort by recall_count desc
-      lessons.sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+      // Sort: reviewed lessons first (senior > peer), then by recall_count desc.
+      const reviewRank = (l: TeamLesson) => l.reviewed_by ? (l.review_level === 'senior' ? 2 : 1) : 0;
+      lessons.sort((a, b) =>
+        (reviewRank(b) - reviewRank(a)) || ((b.recall_count ?? 0) - (a.recall_count ?? 0)));
       lessons = lessons.slice(0, limit);
 
       if (lessons.length === 0) {
@@ -185,11 +239,17 @@ export async function handleTeamTool(
       for (const l of lessons) {
         const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
         const sev = l.severity === 'critical' ? '🔴 ' : l.severity === 'major' ? '🟡 ' : '';
+        const reviewBadge = l.reviewed_by
+          ? (l.review_level === 'senior' ? ' 🛡️' : ' ✔️')
+          : '';
         const authorStr = l.author ? ` · _by ${l.author}_` : '';
+        const reviewStr = l.reviewed_by
+          ? ` · reviewed by ${l.reviewed_by}${(l.endorsements ?? 0) > 1 ? ` +${(l.endorsements ?? 0) - 1}` : ''}`
+          : '';
         const recallStr = (l.recall_count ?? 0) > 0 ? ` · recalled ${l.recall_count}×` : '';
         const ago = Math.round((Date.now() - new Date(l.ts).getTime()) / 86400000);
         const agoStr = ago === 0 ? 'today' : ago === 1 ? 'yesterday' : `${ago}d ago`;
-        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${authorStr}${recallStr} · ${agoStr}`);
+        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${reviewBadge}${authorStr}${reviewStr}${recallStr} · ${agoStr}`);
         lines.push(`   ${l.what_worked.slice(0, 120)}`);
         lines.push('');
       }