@cachly-dev/mcp-server 0.10.48 → 0.10.55

package/src/handlers/brain.ts

@@ -6,16 +6,57 @@ import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '..
 import { safeJsonParse } from '../utils.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
-         ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from '../search.js';
+         indexVocab as _indexVocab } from '../search.js';
 import type { KeywordMatch } from '../search.js';
-import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER } from '../embeddings.js';
-import { detectNamespace } from '../namespace.js';
+import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.0';
+const MCP_VERSION = '0.10.55';
 const WHATS_NEW: Record<string, string[]> = {
+  '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.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)`,
+  ],
+  '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.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.0': [
-    `🆕 **What's new in v${MCP_VERSION}:**`,
+    `🆕 **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`,
@@ -183,7 +224,7 @@ export async function handleBrainTool(
         const existing = await redis.get(depKey);
         const depTopics: string[] = safeJsonParse<string[]>(existing, []);
         if (!depTopics.includes(topic)) depTopics.push(topic);
-        await redis.set(depKey, JSON.stringify(depTopics));
+        await redis.set(depKey, JSON.stringify(depTopics), 'EX', 365 * 86400); // 1-year TTL
       }
 
       const lessonObj = {
@@ -207,9 +248,11 @@ export async function handleBrainTool(
       };
       const lesson = JSON.stringify(lessonObj);
 
-      // Always append to the history list (audit log)
+      // Always append to the history list (audit log); cap at 200 entries to prevent unbounded growth
       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
 
       // Update best key for success/partial; for failure only update if no success exists
       if (outcome === 'success' || outcome === 'partial') {
@@ -342,6 +385,44 @@ export async function handleBrainTool(
         }
       } 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: string[] = [];
+      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<CKGEdge | null>(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<{ topic?: string; what_worked?: string } | null>(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';
@@ -364,6 +445,7 @@ export async function handleBrainTool(
           : '',
         ...templateWarnings,
         ...iWasWrongWarning,
+        ...proactiveSuggestions,
       ].filter(l => l !== '').join('\n');
     }
 

package/src/handlers/team.ts

@@ -109,7 +109,9 @@ export async function handleTeamTool(
         file_paths: file_paths ?? [],
         commands: commands ?? [],
         tags: [...(tags ?? []), 'team'],
-        timestamp: new Date().toISOString(),
+        ts: new Date().toISOString(),
+        verified_at: outcome === 'success' ? new Date().toISOString() : undefined,
+        confidence: 1.0,
         recall_count: 0,
         version: 2,
       };

package/src/index.ts

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { jwtExpiryMs, checkJwt, handleApiError } from './auth.js';
 import { readFile } from 'node:fs/promises';
-import { execSync } from 'node:child_process';
-import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 // True only when this file is the entry point (not imported by tests or other modules).
@@ -60,8 +58,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
-const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.47';
+const CURRENT_VERSION = '0.10.55';
 
 // ── Per-request context (multi-tenant HTTP / Smithery) ───────────────────────
 // In stdio mode the module-level JWT/instance globals apply.
@@ -86,8 +83,18 @@ async function resolveDefaultInstanceId(): Promise<string> {
   if (_defaultInstanceId) return _defaultInstanceId;
   if (!getJWT()) return '';
   // Cooldown: don't hammer the API on every tool call after a transient failure.
+  // 10 s is enough to avoid rate-limit spam while not blocking the user for too long.
   const now = Date.now();
-  if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 30_000) return '';
+  if (_defaultInstanceLastAttempt > 0 && now - _defaultInstanceLastAttempt < 10_000) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      '⚠️ Cachly Brain is temporarily unreachable (API error a few seconds ago).\n\n' +
+      'The server will retry automatically in a moment. If this persists:\n' +
+      '• Run `get_api_status` for a full diagnostic\n' +
+      '• Check that CACHLY_JWT is set and valid\n' +
+      '• Visit https://cachly.dev/instances to verify your Brain is running'
+    );
+  };
   _defaultInstanceLastAttempt = now;
   try {
     const res = await fetch(`${API_URL}/api/v1/instances`, {
@@ -178,6 +185,26 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
       } catch { /* use raw JWT as fallback */ }
       JWT = apiKey;
       setEmbedJwt(apiKey); // keep embeddings.ts in sync
+      // Persist API key to ~/.claude/mcp.json so the next editor restart
+      // doesn't start over from a missing CACHLY_JWT (fixes BrainRecallCount=0 bug).
+      try {
+        const { resolve: _res, dirname: _dir } = await import('node:path');
+        const { homedir: _hd } = await import('node:os');
+        const { writeFile: _wf, mkdir: _mk, readFile: _rf } = await import('node:fs/promises');
+        const { existsSync: _ex } = await import('node:fs');
+        const globalJwtPath = _res(_hd(), '.claude', 'mcp.json');
+        await _mk(_dir(globalJwtPath), { recursive: true });
+        let cfg: { mcpServers?: Record<string, { env?: Record<string, string> }> } = {};
+        if (_ex(globalJwtPath)) {
+          try { cfg = JSON.parse(await _rf(globalJwtPath, 'utf-8')) as typeof cfg; } catch { /* corrupt — start fresh */ }
+        }
+        cfg.mcpServers ??= {};
+        cfg.mcpServers['cachly'] ??= {};
+        cfg.mcpServers['cachly'].env ??= {};
+        cfg.mcpServers['cachly'].env['CACHLY_JWT'] = apiKey;
+        if (_defaultInstanceId) cfg.mcpServers['cachly'].env['CACHLY_BRAIN_INSTANCE_ID'] = _defaultInstanceId;
+        await _wf(globalJwtPath, JSON.stringify(cfg, null, 2), 'utf-8');
+      } catch { /* non-fatal — editor will just prompt again on next restart */ }
       _deviceFlow = null;
       sendFunnelEvent('device_flow_completed');
       // Auto-provision: find or create the user's brain instance.
@@ -243,22 +270,61 @@ async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expir
     return 'pending';
   } catch { return 'pending'; }
 }
-// ── Confidence utils (imported from confidence.ts) ──────────────────────────
-import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES,
-         CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS,
-         CONFIDENCE_STALE_DAYS,
-         simpleHash } from './confidence.js';
+// ── Silent Auto-Setup (instant-trial, zero-click) ─────────────────────────
+// Attempts to provision a free trial silently on the first tool call when no
+// JWT is set. Returns true if credentials were written and the tool can
+// proceed transparently; false if the API is unreachable or trials are full.
+// Only runs once per process (subsequent failures short-circuit immediately).
+let _silentSetupAttempted = false;
+async function silentAutoSetup(): Promise<boolean> {
+  if (_silentSetupAttempted) return false;
+  _silentSetupAttempted = true;
+  try {
+    type TrialResp = { api_key: string; expires_at?: string; instance_id?: string; trial?: boolean };
+    const res = await fetch(`${API_URL}/auth/instant-trial`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) return false;
+    const data = await res.json() as TrialResp;
+    if (!data.api_key) return false;
 
+    JWT = data.api_key;
+    setEmbedJwt(data.api_key);
+    if (data.instance_id) _defaultInstanceId = data.instance_id;
+    sendFunnelEvent('trial_provisioned', { version: CURRENT_VERSION });
 
+    // Persist credentials so the next editor restart doesn't re-provision.
+    try {
+      const { resolve: _rp, dirname: _dn } = await import('node:path');
+      const { homedir: _hd } = await import('node:os');
+      const { writeFile: _wf, mkdir: _mk, readFile: _rf } = await import('node:fs/promises');
+      const { existsSync: _ex } = await import('node:fs');
+      const cfgPath = _rp(_hd(), '.claude', 'mcp.json');
+      await _mk(_dn(cfgPath), { recursive: true });
+      let cfg: { mcpServers?: Record<string, { env?: Record<string, string> }> } = {};
+      if (_ex(cfgPath)) {
+        try { cfg = JSON.parse(await _rf(cfgPath, 'utf-8')) as typeof cfg; } catch { /* corrupt — overwrite */ }
+      }
+      cfg.mcpServers ??= {};
+      cfg.mcpServers['cachly'] ??= {};
+      cfg.mcpServers['cachly'].env ??= {};
+      cfg.mcpServers['cachly'].env['CACHLY_JWT'] = data.api_key;
+      if (_defaultInstanceId) cfg.mcpServers['cachly'].env['CACHLY_BRAIN_INSTANCE_ID'] = _defaultInstanceId;
+      await _wf(cfgPath, JSON.stringify(cfg, null, 2), 'utf-8');
+    } catch { /* non-fatal — trial is active for this session even if persist fails */ }
+    return true;
+  } catch { return false; }
+}
 // ── Embeddings (imported from embeddings.ts) ────────────────────────────────
-import { embedConfig, setEmbedJwt, EMBED_PROVIDER, computeEmbedding,
-         hasEmbedProvider, embedProviderHint } from './embeddings.js';
+import { setEmbedJwt } from './embeddings.js';
 
 // ── Search Engine (imported from search.ts) ─────────────────────────────────
 import { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS,
          katakanaToRomaji, arabicLightStem, expandCrossLingual, CROSS_LINGUAL_MAP,
-         keywordSearch, ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from './search.js';
-import type { KeywordMatch } from './search.js';
+         ZERO_RESULTS_LOG, zeroResultsTotal } from './search.js';
 
 // ── Exported for testing (re-export from search.ts) ─────────────────────────
 export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp, STOPWORDS,
@@ -267,19 +333,6 @@ export { tokenize, splitMultiQuery, levenshtein, recencyBoost, extractTimestamp,
 // ── Types ─────────────────────────────────────────────────────────────────────
 // Instance is imported from handlers/brain.ts
 
-interface CreateResponse {
-  instance_id: string;
-  checkout_url?: string;
-  status: string;
-}
-
-interface SemanticSearchResponse {
-  found: boolean;
-  id?: string;
-  similarity?: number;
-  prompt?: string;
-}
-
 // ── Connection pool ───────────────────────────────────────────────────────────
 
 /** Reuse Redis connections across tool calls (keyed by instance_id). */
@@ -301,7 +354,7 @@ async function getConnection(instance_id: string): Promise<Redis> {
     // Verify the pooled connection is still alive before reusing it.
     // ioredis 'error' eviction is async — a connection can be in the pool
     // but already internally broken (status 'reconnecting' or 'end').
-    const status = (cached as any).status as string | undefined;
+    const status = (cached as { status?: string }).status;
     if (status === 'ready' || status === 'connect') {
       return cached;
     }
@@ -310,14 +363,13 @@ async function getConnection(instance_id: string): Promise<Redis> {
     cached.disconnect();
   }
 
-  // Fetch instance, waiting up to 25 s if it is still provisioning.
-  // This covers the zero-friction path: device-flow auth → auto-provision → first tool call
-  // all happen in quick succession and the instance isn't running yet.
+  // Fetch instance, waiting up to 8 s if it is still provisioning.
+  // (autoStartSession already gave the instance a head-start; 8 s covers any remaining gap.)
   let inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
   if (inst.status === 'provisioning') {
-    const deadline = Date.now() + 25_000;
+    const deadline = Date.now() + 8_000;
     while (inst.status === 'provisioning' && Date.now() < deadline) {
-      await new Promise(r => setTimeout(r, 3000));
+      await new Promise(r => setTimeout(r, 2000));
       inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
     }
   }
@@ -357,7 +409,9 @@ async function getConnection(instance_id: string): Promise<Redis> {
 
   // Fetch connection details (includes password) from the dedicated endpoint.
   let password: string | undefined;
-  let tlsEnabled = inst.tls_enabled !== false; // default true
+  // Default to false — most free/dev instances run without TLS.
+  // Only enable TLS when the API explicitly returns tls_enabled: true.
+  let tlsEnabled = inst.tls_enabled === true;
   try {
     const conn = await apiFetch<{ password?: string; tls_enabled?: boolean }>(
       `/api/v1/instances/${instance_id}/connection`
@@ -383,6 +437,7 @@ async function getConnection(instance_id: string): Promise<Redis> {
     lazyConnect: true,
     enableReadyCheck: true,
     connectTimeout: 8000,
+    commandTimeout: 10000,
     retryStrategy: () => null,  // fail fast, no reconnect loops in MCP context
   });
 
@@ -407,6 +462,7 @@ async function getConnection(instance_id: string): Promise<Redis> {
           lazyConnect: true,
           enableReadyCheck: true,
           connectTimeout: 8000,
+          commandTimeout: 10000,
           retryStrategy: () => null,
         });
         retryClient.on('error', () => pool.delete(instance_id));
@@ -468,11 +524,6 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   return res.json() as Promise<T>;
 }
 
-import { detectNamespace } from './namespace.js';
-
-// ── CKG (imported from ckg.ts) ─────────────────────────────────────────────
-import type { CKGEdge, CKGNode } from './ckg.js';
-import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from './ckg.js';
 import { handleBrainTool } from './handlers/brain.js';
 import { handleContextTool } from './handlers/context.js';
 import { handleInstanceTool } from './handlers/instances.js';
@@ -510,7 +561,10 @@ function sendFunnelEvent(event: string, extra?: Record<string, unknown>): void {
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       event, version: CURRENT_VERSION, editor: detectEditor(),
-      ...(getJWT() ? { jwt: getJWT() } : {}),
+      // Send Cachly API keys (cky_*) for server-side tenant resolution (recall counting, emails).
+      // Raw Keycloak JWTs (eyJ...) are intentionally excluded — they are short-lived bearer tokens
+      // that should never leave the MCP process boundary.
+      ...(getJWT().startsWith('cky_') ? { api_key: getJWT() } : {}),
       ...extra,
     }),
     signal: AbortSignal.timeout(3000),
@@ -532,12 +586,20 @@ async function sendAnonymousTelemetry(toolName: string): Promise<void> {
 }
 
 async function handleTool(name: string, args: Record<string, unknown>): Promise<string> {
-  // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
+  // Guard: if no JWT, try silent auto-setup first, then fall back to device flow.
   if (!getJWT()) {
+    // ── Step 1: Silent instant-trial (zero-click) ────────────────────────
+    // On the very first tool call, attempt to silently provision a free trial.
+    // If it succeeds the user never sees an auth prompt — Brain is just active.
+    const provisioned = await silentAutoSetup();
+    if (provisioned) {
+      return handleTool(name, args); // Transparent re-entry with active credentials
+    }
+
     void sendAnonymousTelemetry(name);
 
-    // ── Zero-credential device flow ─────────────────────────────────────
-    // 1st call: start device flow, return code + URL
+    // ── Step 2: Zero-credential device flow ─────────────────────────────
+    // 1st call after silent setup fails: start device flow, return code + URL
     // 2nd+ calls: poll for token; once authenticated, proceed transparently
     if (_deviceFlow) {
       const result = await pollDeviceFlow(_deviceFlow);
@@ -611,7 +673,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
   }
 
   // Delegate brain tools (learn, recall, session, etc.)
-  const brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
+  let brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
   if (brainResult !== null) {
     if (!_firstCallSuccessSent && getJWT()) {
       _firstCallSuccessSent = true;
@@ -636,28 +698,40 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       if (!isFirstSession && resultText.length > 100) {
         // Existing brain — session_start acts as implicit recall → increment counter.
         sendFunnelEvent('recall_best_solution', telemetryExtra);
-      } else if (isFirstSession && args.workspace_path) {
-        // First session with a known workspace: auto-bootstrap from git history.
-        // Runs synchronously so the user sees the result in the same response.
+      }
+
+      // Auto-bootstrap brain_from_git when workspace_path is provided and it hasn't run yet.
+      // We check a sentinel key in Valkey so this only fires once per workspace path,
+      // not just on the very first session (handles cases where brain was empty but
+      // session data existed, or where the user re-installed).
+      if (args.workspace_path) {
         try {
-          const gitBootstrap = await handleFedbrainTool('brain_from_git', {
-            instance_id: instanceId,
-            repo_path: args.workspace_path as string,
-            limit: 50,
-          }, getConnection, apiFetch);
-          if (gitBootstrap !== null) {
-            sendFunnelEvent('brain_from_git', telemetryExtra);
-            sendFunnelEvent('recall_best_solution', telemetryExtra);
-            // Append bootstrap summary to the session_start briefing.
-            const bootstrapText = typeof gitBootstrap === 'object' && gitBootstrap !== null && 'content' in gitBootstrap
-              ? (gitBootstrap as { content: { text?: string }[] }).content.map((c) => c.text ?? '').join('\n')
-              : String(gitBootstrap);
+          const workspacePath = args.workspace_path as string;
+          const autoKey = `cachly:brain_from_git:auto_done:${Buffer.from(workspacePath).toString('base64').slice(0, 40)}`;
+          const redis = await getConnection(instanceId);
+          const alreadyDone = await redis.get(autoKey);
+          if (!alreadyDone) {
+            // Mark immediately to prevent concurrent runs across multiple MCP tool calls
+            await redis.set(autoKey, '1', 'EX', 365 * 86400);
+            // Append a placeholder so the user gets immediate feedback, then bootstrap in background.
+            // Running brain_from_git synchronously would block session_start for 30-120s on large repos.
+            const bgMsg = '\n\n---\n\n🚀 **Auto-indexing your git history in the background** — your Brain will learn from recent commits automatically. No action needed.';
             if (typeof brainResult === 'object' && brainResult !== null && 'content' in brainResult) {
-              (brainResult as { content: { type: string; text: string }[] }).content.push({
-                type: 'text',
-                text: '\n---\n' + bootstrapText,
-              });
+              (brainResult as { content: { type: string; text: string }[] }).content.push({ type: 'text', text: bgMsg });
+            } else if (typeof brainResult === 'string') {
+              brainResult = brainResult + bgMsg;
             }
+            // Fire-and-forget — never block the session_start response
+            void handleFedbrainTool('brain_from_git', {
+              instance_id: instanceId,
+              repo_path: workspacePath,
+              limit: 50,
+            }, getConnection, apiFetch).then((gitBootstrap) => {
+              if (gitBootstrap !== null) {
+                sendFunnelEvent('brain_from_git', telemetryExtra);
+                sendFunnelEvent('recall_best_solution', telemetryExtra);
+              }
+            }).catch(() => { /* non-critical */ });
           }
         } catch { /* git bootstrap errors must never break session_start */ }
       }
@@ -760,28 +834,38 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       }
 
       // Decode JWT claims (inspection only, no verification)
-      let authInfo = '❌ invalid JWT format';
-      try {
-        const parts = getJWT().split('.');
-        if (parts.length === 3) {
-          const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as {
-            sub?: string; exp?: number; iss?: string;
-          };
-          const sub = payload.sub ?? '(unknown)';
-          const iss = payload.iss ?? '(unknown)';
-          const provider = iss.includes('keycloak') ? 'Keycloak' : 'OIDC';
-          const expTs = payload.exp ? new Date(payload.exp * 1000) : null;
-          const expired = expTs ? expTs < new Date() : false;
-          authInfo = [
-            `✅ JWT decoded`,
-            `  Sub (user ID): ${sub}`,
-            `  Provider:      ${provider}`,
-            `  Issuer:        ${iss}`,
-            `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${expired ? '⚠️  EXPIRED – get a new token!' : '✅'}`,
-          ].join('\n');
+      const jwt = getJWT();
+      let authInfo: string;
+      // API keys (cky_live_... / cky_trial_...) are valid long-lived credentials.
+      // Only try to decode as JWT (3-part base64url) if it looks like one.
+      if (jwt.startsWith('cky_')) {
+        const keyType = jwt.startsWith('cky_trial_') ? 'Trial' : 'Live';
+        const keyId = jwt.slice(0, 20) + '…';
+        authInfo = `✅ API key (${keyType})\n  Key prefix: ${keyId}`;
+      } else {
+        authInfo = '❌ invalid credential format';
+        try {
+          const parts = jwt.split('.');
+          if (parts.length === 3) {
+            const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as {
+              sub?: string; exp?: number; iss?: string;
+            };
+            const sub = payload.sub ?? '(unknown)';
+            const iss = payload.iss ?? '(unknown)';
+            const provider = iss.includes('keycloak') ? 'Keycloak' : 'OIDC';
+            const expTs = payload.exp ? new Date(payload.exp * 1000) : null;
+            const expired = expTs ? expTs < new Date() : false;
+            authInfo = [
+              `✅ JWT decoded`,
+              `  Sub (user ID): ${sub}`,
+              `  Provider:      ${provider}`,
+              `  Issuer:        ${iss}`,
+              `  Expires:       ${expTs ? expTs.toISOString() : 'never'} ${expired ? '⚠️  EXPIRED – get a new token!' : '✅'}`,
+            ].join('\n');
+          }
+        } catch {
+          authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
         }
-      } catch {
-        authInfo = '❌ JWT decode failed – check CACHLY_JWT format';
       }
 
       // List instances + connectivity
@@ -923,12 +1007,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       || _defaultInstanceId
       || process.env.CACHLY_BRAIN_INSTANCE_ID;
     if (instanceId) {
-      await autoStartSession(instanceId).catch(() => undefined);
+      // Fire-and-forget — session management is non-critical and must never block tool calls.
+      // The session_start briefing (which includes brain_from_git) can take 30-120s on large
+      // repos; awaiting it here would freeze the user's first MCP tool call entirely.
+      void autoStartSession(instanceId);
     }
-  } else if (_autoSessionStarting) {
-    // Another concurrent call is mid-start — wait for it before proceeding.
-    await _autoSessionStarting.catch(() => undefined);
   }
+  // Note: we intentionally do NOT await _autoSessionStarting for any call.
+  // The session tracker runs in background — tool calls must always proceed immediately.
   if (!sessionTools.has(name)) _autoSessionToolCount++;
 
   try {
@@ -1998,7 +2084,7 @@ if (process.argv[2] === 'status') {
 if (process.argv[2] === 'health') {
   const { existsSync } = await import('node:fs');
   const { readFile } = await import('node:fs/promises');
-  const { resolve, join: pJoin } = await import('node:path');
+  const { resolve } = await import('node:path');
 
   const cwd = process.cwd();
   let passed = 0;
@@ -2015,6 +2101,9 @@ if (process.argv[2] === 'health') {
   const jwt = process.env.CACHLY_JWT ?? '';
   if (!jwt) {
     fail('CACHLY_JWT not set — run: npx @cachly-dev/mcp-server@latest setup');
+  } else if (jwt.startsWith('cky_')) {
+    // Opaque cachly API key — no JWT expiry to check, format is valid by prefix
+    ok('API key set (cky_*** opaque key)');
   } else {
     try {
       const parts = jwt.split('.');
@@ -2032,7 +2121,7 @@ if (process.argv[2] === 'health') {
         ok(`JWT valid${minsLeft !== null ? ` (expires in ${Math.floor(minsLeft / 60)}h ${minsLeft % 60}m)` : ''}`);
       }
     } catch {
-      fail('CACHLY_JWT format invalid (expected JWT with 3 parts)');
+      fail('CACHLY_JWT format invalid (expected a cky_*** API key or a JWT with 3 parts)');
     }
   }
 
@@ -2080,11 +2169,23 @@ if (process.argv[2] === 'health') {
                   signal: AbortSignal.timeout(5000),
                 });
                 if (connRes.ok) {
-                  const conn = await connRes.json() as { password?: string; tls_enabled?: boolean };
-                  pingPassword = conn.password;
-                  pingTls = conn.tls_enabled !== false;
+                  const conn = await connRes.json() as { password?: string; connection_string?: string; tls_enabled?: boolean };
+                  // password may be a direct field, or embedded in connection_string as redis://:pass@host:port
+                  if (conn.password) {
+                    pingPassword = conn.password;
+                  } else if (conn.connection_string) {
+                    try {
+                      const u = new URL(conn.connection_string);
+                      if (u.password) pingPassword = decodeURIComponent(u.password);
+                    } catch { /* leave pingPassword undefined */ }
+                  }
+                  pingTls = conn.tls_enabled === true;
+                } else {
+                  warn(`Could not fetch Redis credentials (HTTP ${connRes.status}) — connectivity test may fail`);
                 }
-              } catch { /* proceed without password */ }
+              } catch (connErr) {
+                warn(`Could not fetch Redis credentials — ${(connErr as Error).message}`);
+              }
               const pingClient = new Redis({
                 host: inst.host, port: inst.port,
                 password: pingPassword,
@@ -2299,7 +2400,7 @@ if (process.argv[2] === 'setup') {
       if (!keyBody.key) throw new Error('no key in response');
       token = keyBody.key; // swap JWT → cky_live_...
       console.log(' ✓\n');
-    } catch (e) {
+    } catch {
       console.log(' (skipped)\n');
       // Non-fatal: fall back to using the Keycloak JWT directly.
       // It will expire but setup still works for now.
@@ -2689,7 +2790,7 @@ if (process.argv[2] === 'learn-git') {
       limit: maxCommits,
     });
     console.log(result);
-    sendFunnelEvent('brain_from_git', { api_key: JWT, instance_id: instanceId });
+    sendFunnelEvent('brain_from_git', { instance_id: instanceId });
     console.log('\n✅  Brain learned from your commits.\n');
     // Let fire-and-forget telemetry flush before exit.
     await new Promise(r => setTimeout(r, 300));