@cachly-dev/mcp-server 0.10.117 → 0.10.118

package/dist/src/doctor.js

@@ -0,0 +1,247 @@
+// `cachly doctor` — one-command setup diagnosis.
+//
+// The activation funnel dies silently: a missing JWT, an unreachable API, a
+// half-installed hook set or a stale v1 shell hook all look identical from the
+// editor ("the brain just doesn't answer"). doctor makes every link of the
+// chain visible in one run: environment → credential → API → instance → hooks
+// → ledger. Pure check functions with injected effects so the whole module is
+// unit-testable; the CLI shell in index.ts only wires and prints.
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { AMBIENT_HOOK_VERSION } from './ambient-hooks.js';
+import { netBalance, shouldBackoff } from './ambient-recall.js';
+const MIN_NODE_MAJOR = 18;
+/** Node runtime new enough for fetch/AbortSignal (>= 18). */
+export function checkNodeVersion(version = process.version) {
+    const major = Number(version.replace(/^v/, '').split('.')[0]);
+    if (Number.isFinite(major) && major >= MIN_NODE_MAJOR) {
+        return { name: 'Node.js', status: 'ok', detail: `${version}` };
+    }
+    return {
+        name: 'Node.js',
+        status: 'fail',
+        detail: `${version} — too old`,
+        hint: `cachly needs Node ${MIN_NODE_MAJOR}+ (built-in fetch). Install a current LTS from nodejs.org.`,
+    };
+}
+/** Credential present and roughly the right shape (cky_… API key or JWT). */
+export function checkCredential(jwt) {
+    if (!jwt) {
+        return {
+            name: 'Credential',
+            status: 'fail',
+            detail: 'CACHLY_JWT is not set',
+            hint: 'Run `npx @cachly-dev/mcp-server@latest autopilot` (browser sign-in) or export CACHLY_JWT=<cky_…>.',
+        };
+    }
+    const looksApiKey = jwt.startsWith('cky_');
+    const looksJwt = jwt.split('.').length === 3;
+    if (!looksApiKey && !looksJwt) {
+        return {
+            name: 'Credential',
+            status: 'warn',
+            detail: 'CACHLY_JWT is set but looks neither like a cky_… key nor a JWT',
+            hint: 'Re-copy the key from the dashboard (API Keys) — it may be truncated.',
+        };
+    }
+    return { name: 'Credential', status: 'ok', detail: looksApiKey ? 'API key (cky_…)' : 'JWT' };
+}
+/** API reachable at all (public /health — no auth involved). */
+export async function checkApiReachable(apiUrl, fetchFn = fetch) {
+    try {
+        const res = await fetchFn(`${apiUrl}/health`, { signal: AbortSignal.timeout(5000) });
+        if (res.ok)
+            return { name: 'API', status: 'ok', detail: `${apiUrl} reachable` };
+        return {
+            name: 'API',
+            status: 'fail',
+            detail: `${apiUrl}/health returned HTTP ${res.status}`,
+            hint: 'The API answered but is unhealthy — check https://cachly.dev/status or your CACHLY_API_URL.',
+        };
+    }
+    catch {
+        return {
+            name: 'API',
+            status: 'fail',
+            detail: `${apiUrl} not reachable`,
+            hint: 'Check your network/proxy. Self-hosted: is CACHLY_API_URL correct and the API running?',
+        };
+    }
+}
+/** Credential actually accepted by the API (authenticated list call). */
+export async function checkAuthAccepted(apiUrl, jwt, fetchFn = fetch) {
+    if (!jwt) {
+        return { name: 'Auth', status: 'fail', detail: 'skipped — no credential', hint: 'Fix the Credential check first.' };
+    }
+    try {
+        const res = await fetchFn(`${apiUrl}/api/v1/instances`, {
+            headers: { Authorization: `Bearer ${jwt}` },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok)
+            return { name: 'Auth', status: 'ok', detail: 'credential accepted' };
+        if (res.status === 401 || res.status === 403) {
+            return {
+                name: 'Auth',
+                status: 'fail',
+                detail: `API rejected the credential (HTTP ${res.status})`,
+                hint: 'The key is expired or revoked. Create a new one in the dashboard, or re-run autopilot.',
+            };
+        }
+        return { name: 'Auth', status: 'warn', detail: `unexpected HTTP ${res.status} from /api/v1/instances` };
+    }
+    catch {
+        return { name: 'Auth', status: 'warn', detail: 'could not verify (network error)' };
+    }
+}
+/** Brain instance configured (env or auto-provisioned default). */
+export function checkInstance(instanceId) {
+    if (!instanceId) {
+        return {
+            name: 'Instance',
+            status: 'warn',
+            detail: 'no CACHLY_BRAIN_INSTANCE_ID set and no default instance resolved',
+            hint: 'Run `npx @cachly-dev/mcp-server@latest init` in your project, or export CACHLY_BRAIN_INSTANCE_ID.',
+        };
+    }
+    const uuidish = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(instanceId);
+    return uuidish
+        ? { name: 'Instance', status: 'ok', detail: instanceId.slice(0, 8) + '…' }
+        : {
+            name: 'Instance',
+            status: 'warn',
+            detail: `"${instanceId.slice(0, 24)}" does not look like an instance UUID`,
+            hint: 'Copy the instance ID from the dashboard (Instances → your brain).',
+        };
+}
+/** Read-only look at .claude/ in projectDir — never throws. */
+export function inspectAmbientHooks(projectDir) {
+    const out = { settingsExists: false, wiredEvents: [], scriptFiles: [] };
+    try {
+        const settingsPath = resolve(projectDir, '.claude/settings.json');
+        out.settingsExists = existsSync(settingsPath);
+        if (out.settingsExists) {
+            const parsed = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+            for (const [event, groups] of Object.entries(parsed.hooks ?? {})) {
+                // Normalise Windows backslash paths so the marker match and the path
+                // extraction below work on every platform (node fs accepts / on Windows).
+                const norm = (c) => (c ?? '').replace(/\\/g, '/');
+                const ours = (groups ?? []).some((g) => (g.hooks ?? []).some((h) => norm(h.command).includes('.claude/hooks/cachly-ambient-')));
+                if (ours) {
+                    out.wiredEvents.push(event);
+                    for (const g of groups ?? []) {
+                        for (const h of g.hooks ?? []) {
+                            const cmd = norm(h.command);
+                            const m = cmd.match(/["']?([^"']*\.claude\/hooks\/cachly-ambient-[^"']+)["']?/);
+                            if (!m)
+                                continue;
+                            const scriptPath = m[1].replace('$CLAUDE_PROJECT_DIR', projectDir);
+                            const exists = existsSync(scriptPath);
+                            let version = 'unknown';
+                            if (exists) {
+                                try {
+                                    const body = readFileSync(scriptPath, 'utf-8');
+                                    version = body.includes(AMBIENT_HOOK_VERSION) ? 'current' : 'stale';
+                                }
+                                catch { /* keep unknown */ }
+                            }
+                            out.scriptFiles.push({ path: scriptPath, exists, version });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch { /* corrupt settings → report as not wired */ }
+    return out;
+}
+const AMBIENT_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop'];
+/** Ambient hooks wired, scripts present, version current. */
+export function checkHooks(inspection) {
+    if (!inspection.settingsExists || inspection.wiredEvents.length === 0) {
+        return {
+            name: 'Hooks',
+            status: 'warn',
+            detail: 'Ambient Recall hooks are not installed in this project',
+            hint: 'Run `npx @cachly-dev/mcp-server@latest init` here — memory then injects itself (no hooks = pull-only).',
+        };
+    }
+    const missingEvents = AMBIENT_EVENTS.filter((e) => !inspection.wiredEvents.includes(e));
+    const missingFiles = inspection.scriptFiles.filter((f) => !f.exists);
+    const stale = inspection.scriptFiles.filter((f) => f.exists && f.version === 'stale');
+    if (missingFiles.length > 0) {
+        return {
+            name: 'Hooks',
+            status: 'fail',
+            detail: `settings.json wires hooks whose script files are missing (${missingFiles.length})`,
+            hint: 'Re-run `npx @cachly-dev/mcp-server@latest init` to rewrite the scripts.',
+        };
+    }
+    if (stale.length > 0) {
+        return {
+            name: 'Hooks',
+            status: 'warn',
+            detail: `installed hooks are an older version (current: ${AMBIENT_HOOK_VERSION}); v1/v2 shell hooks never ran on native Windows`,
+            hint: 'Re-run `npx @cachly-dev/mcp-server@latest init` to upgrade in place.',
+        };
+    }
+    if (missingEvents.length > 0) {
+        return {
+            name: 'Hooks',
+            status: 'warn',
+            detail: `partial install — missing events: ${missingEvents.join(', ')}`,
+            hint: 'Re-run `npx @cachly-dev/mcp-server@latest init` to add the missing hooks.',
+        };
+    }
+    return { name: 'Hooks', status: 'ok', detail: `all 4 events wired, scripts ${AMBIENT_HOOK_VERSION}` };
+}
+/** Net-token ledger readable + backoff state. */
+export function checkLedger(entries, ledgerPath) {
+    const bal = netBalance(entries);
+    const backing = shouldBackoff(entries);
+    if (entries.length === 0) {
+        return {
+            name: 'Ledger',
+            status: 'ok',
+            detail: `empty (${ledgerPath}) — fills up once ambient hooks inject`,
+        };
+    }
+    if (backing) {
+        return {
+            name: 'Ledger',
+            status: 'warn',
+            detail: `${entries.length} entries, net ${bal.net} tokens — auto-backoff ACTIVE, injection paused`,
+            hint: 'The agent has not reported prevented tokens lately. This self-heals; `ambient-stats` shows details.',
+        };
+    }
+    return {
+        name: 'Ledger',
+        status: 'ok',
+        detail: `${entries.length} entries, net ${bal.net >= 0 ? '+' : ''}${bal.net} tokens`,
+    };
+}
+const ICON = { ok: '✅', warn: '⚠️ ', fail: '❌' };
+/** Render the report; deterministic, no colors (CI-friendly). */
+export function renderDoctorReport(checks) {
+    const lines = ['', '🩺 cachly doctor', ''];
+    for (const c of checks) {
+        lines.push(`   ${ICON[c.status]} ${c.name.padEnd(11)} ${c.detail}`);
+        if (c.hint && c.status !== 'ok')
+            lines.push(`      ↳ ${c.hint}`);
+    }
+    const fails = checks.filter((c) => c.status === 'fail').length;
+    const warns = checks.filter((c) => c.status === 'warn').length;
+    lines.push('');
+    lines.push(fails > 0
+        ? `   ${fails} problem${fails > 1 ? 's' : ''} to fix${warns ? `, ${warns} warning${warns > 1 ? 's' : ''}` : ''}.`
+        : warns > 0
+            ? `   No blockers — ${warns} warning${warns > 1 ? 's' : ''}.`
+            : '   Everything looks healthy. Your brain is wired.');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Exit code contract: 1 only on hard failures (warnings stay 0 for CI use). */
+export function doctorExitCode(checks) {
+    return checks.some((c) => c.status === 'fail') ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/src/first-contact.d.ts

@@ -0,0 +1,56 @@
+/**
+ * First-contact response builder for `brain_from_git` (roadmap P1-5:
+ * "Onboarding-Magie messen & polieren").
+ *
+ * The very first `brain_from_git` run is a new user's first contact with the
+ * Brain, and it decides whether they ever reach the "aha". The response must,
+ * in one message:
+ *   (a) summarize what was just learned (counts by category + severity),
+ *   (b) prove recall already works — show the top hit of a real search that
+ *       ran against a topic seeded seconds ago,
+ *   (c) hand the user 2-3 copy-pasteable next queries, and
+ *   (d) degrade gracefully for empty/small repos (clear guidance, not empty stats).
+ *
+ * Pure string building — no I/O, no schema/tool changes — so the onboarding
+ * bench and its CI test can assert the exact first-contact response shape.
+ */
+export interface FirstContactProof {
+    /** The query that was run internally against the freshly seeded lessons. */
+    query: string;
+    /** Topic of the top hit. */
+    topic: string;
+    /** Short snippet of the top hit's lesson. */
+    snippet: string;
+}
+export interface FirstContactReportInput {
+    repoDir: string;
+    revRange: string;
+    processed: number;
+    ingested: number;
+    skipped: number;
+    /** Wall-clock time the seeding run took. */
+    durationMs: number;
+    isIncremental: boolean;
+    lastSha?: string;
+    instanceId: string;
+    /** category → count, sorted descending by the caller. */
+    categories: Array<[string, number]>;
+    /** severity → count (optional), sorted descending by the caller. */
+    severities?: Array<[string, number]>;
+    /** Proof-of-value: top hit of an internal search against a just-seeded topic. */
+    proof?: FirstContactProof | null;
+    /** Copy-pasteable follow-up queries (see suggestRecallQueries). */
+    suggestedQueries: string[];
+    /** Optional context for the empty case (e.g. "No commits found on branch X"). */
+    emptyReason?: string;
+}
+/** Below this many ingested lessons we treat the repo as "small" and add growth guidance. */
+export declare const SMALL_SEED_THRESHOLD = 5;
+export declare function formatSeedDuration(ms: number): string;
+/**
+ * Turn seeded topics (`category:some-domain`) into up to `max` copy-pasteable
+ * `smart_recall` calls a brand-new user can paste as their literal next message.
+ * Deduplicates by domain so three "fix:*" topics don't yield three identical queries.
+ */
+export declare function suggestRecallQueries(topics: string[], instanceId: string, max?: number): string[];
+export declare function buildFirstContactReport(r: FirstContactReportInput): string;

package/dist/src/first-contact.js

@@ -0,0 +1,108 @@
+/**
+ * First-contact response builder for `brain_from_git` (roadmap P1-5:
+ * "Onboarding-Magie messen & polieren").
+ *
+ * The very first `brain_from_git` run is a new user's first contact with the
+ * Brain, and it decides whether they ever reach the "aha". The response must,
+ * in one message:
+ *   (a) summarize what was just learned (counts by category + severity),
+ *   (b) prove recall already works — show the top hit of a real search that
+ *       ran against a topic seeded seconds ago,
+ *   (c) hand the user 2-3 copy-pasteable next queries, and
+ *   (d) degrade gracefully for empty/small repos (clear guidance, not empty stats).
+ *
+ * Pure string building — no I/O, no schema/tool changes — so the onboarding
+ * bench and its CI test can assert the exact first-contact response shape.
+ */
+/** Below this many ingested lessons we treat the repo as "small" and add growth guidance. */
+export const SMALL_SEED_THRESHOLD = 5;
+export function formatSeedDuration(ms) {
+    if (ms < 1000)
+        return `${Math.max(ms, 1)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+}
+/**
+ * Turn seeded topics (`category:some-domain`) into up to `max` copy-pasteable
+ * `smart_recall` calls a brand-new user can paste as their literal next message.
+ * Deduplicates by domain so three "fix:*" topics don't yield three identical queries.
+ */
+export function suggestRecallQueries(topics, instanceId, max = 3) {
+    const seen = new Set();
+    const out = [];
+    for (const topic of topics) {
+        const domain = (topic.includes(':') ? topic.slice(topic.indexOf(':') + 1) : topic)
+            .replace(/[-_]+/g, ' ')
+            .trim();
+        if (!domain || seen.has(domain))
+            continue;
+        seen.add(domain);
+        out.push(`smart_recall(instance_id="${instanceId}", query="${domain}")`);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/** Steps that take an empty/tiny Brain to a first recall hit in under a minute. */
+function growthSteps(instanceId) {
+    return [
+        `  1. \`brain_seed_starter(instance_id="${instanceId}")\` — load 16 curated engineering lessons instantly`,
+        `  2. \`smart_recall(instance_id="${instanceId}", query="docker build slow")\` — see your first recall hit`,
+        `  3. \`learn_from_attempts(...)\` after your next fix — the Brain grows with every lesson from here on`,
+    ];
+}
+export function buildFirstContactReport(r) {
+    const lines = [];
+    lines.push(`🔁 **brain_from_git: ${r.repoDir}**`);
+    if (r.isIncremental && r.lastSha) {
+        lines.push(`🔄 Incremental mode — only new commits since \`${r.lastSha.slice(0, 8)}\` were processed`);
+    }
+    lines.push('');
+    lines.push(`📂 Branch: \`${r.revRange}\`  |  Processed: **${r.processed}** commits  |  ` +
+        `Ingested: **${r.ingested}** lessons  |  Skipped: ${r.skipped}  |  ` +
+        `⏱️ Seeding took ${formatSeedDuration(r.durationMs)}`);
+    lines.push('');
+    // ── Empty repo / nothing ingested — guidance instead of empty stats ─────────
+    if (r.ingested === 0) {
+        if (r.emptyReason)
+            lines.push(`⚠️ ${r.emptyReason}`);
+        lines.push(`🌱 **Nothing to learn from this git history yet** — normal for fresh, shallow, or squash-only repos.`);
+        lines.push(`Get to your first recall in under a minute:`);
+        lines.push(...growthSteps(r.instanceId));
+        return lines.join('\n');
+    }
+    // ── (a) Seeded summary — what the Brain just learned ────────────────────────
+    lines.push(`**What your Brain just learned (by category):**`);
+    lines.push(r.categories.map(([k, v]) => `  • **${k}** (${v})`).join('\n'));
+    if (r.severities && r.severities.length > 0) {
+        lines.push(`**By severity:** ${r.severities.map(([k, v]) => `${k} ${v}`).join(' · ')}`);
+    }
+    // ── (b) Proof of value — a real recall against a just-seeded topic ──────────
+    if (r.proof) {
+        lines.push('');
+        lines.push(`🎯 **Proof — your first recall already works.** We just searched your fresh Brain for:`);
+        lines.push(`   "${r.proof.query}"`);
+        lines.push(`   → Top hit: **${r.proof.topic}** — ${r.proof.snippet}`);
+    }
+    // ── (c) Suggested next queries — copy-pasteable ──────────────────────────────
+    if (r.suggestedQueries.length > 0) {
+        lines.push('');
+        lines.push(`**Try these next (copy-paste):**`);
+        for (const q of r.suggestedQueries)
+            lines.push(`  • \`${q}\``);
+    }
+    // ── (d) Small-repo guidance ──────────────────────────────────────────────────
+    if (r.ingested < SMALL_SEED_THRESHOLD) {
+        lines.push('');
+        lines.push(`🌱 **Small git history — only ${r.ingested} lesson${r.ingested === 1 ? '' : 's'} so far.** Top it up:`);
+        lines.push(...growthSteps(r.instanceId));
+    }
+    lines.push('');
+    lines.push(`💡 New lessons are stored with confidence 0.55 (auto-inferred).`);
+    lines.push(`💡 As you confirm them via \`learn_from_attempts\`, confidence rises automatically.`);
+    lines.push(`🔍 Explore: \`brain_search(query="fix")\`  |  \`ckg_inspect(concept="deploy")\``);
+    lines.push(`💾 Next run will automatically continue from the latest commit (incremental mode).`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=first-contact.js.map

package/dist/src/first-contact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-contact.js","sourceRoot":"","sources":["../../src/first-contact.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/brain.d.ts

@@ -13,6 +13,7 @@ export interface Instance {
     memory_mb: number;
     encryption_at_rest: boolean;
     created_at: string;
+    org_id?: string;
 }
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;

package/dist/src/handlers/brain.js

@@ -2,7 +2,7 @@ import { execSync } from 'node:child_process';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge, ckgUpsertPersonNode, ckgUpsertFileNode, ckgRecordCollaboration, ckgUpsertServiceNode } from '../ckg.js';
 import { safeJsonParse, scanKeys } from '../utils.js';
-import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope } from './team.js';
+import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope, reviewModeEnabled, storeLessonProposal } from './team.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
@@ -402,6 +402,21 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', visibility = 'team', service = '', service_kind = 'service', group = '', } = args;
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
+            // ── Lessons-Review workflow (P1-1) ─────────────────────────────────────
+            // When the org enabled pending-mode on this (shared) brain, team-visible
+            // lessons become proposals awaiting owner/admin approval instead of
+            // landing in the recall keyspace. Private notes stay direct — they never
+            // surface in team recall anyway. Flag absent = direct write, as before.
+            if (visibility !== 'private' && await reviewModeEnabled(redis, instance_id)) {
+                return storeLessonProposal(redis, topic, {
+                    topic, outcome, what_worked, what_failed, context: ctx, severity,
+                    file_paths, commands, tags, depends_on,
+                    ...(author ? { author } : {}),
+                    ...(service ? { service } : {}),
+                    ...(group ? { group: String(group).toLowerCase().trim() } : {}),
+                    visibility, recall_count: 0, ts, confidence: 1.0, version: 3,
+                });
+            }
             // ── Structured template hints ──────────────────────────────────────────
             const category = topic.split(':')[0];
             const template = STRUCTURED_TEMPLATES[category];
@@ -416,12 +431,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // ── Deduplication + audit trail ────────────────────────────────────────
             let isUpdate = false;
             let recallCount = 0;
+            let lastRecalledAt;
             let auditTrail = [];
             const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
             if (existingRaw) {
                 try {
                     const prev = JSON.parse(existingRaw);
                     recallCount = prev.recall_count ?? 0;
+                    lastRecalledAt = prev.last_recalled_at; // learn never stamps it — only recall does
                     auditTrail = prev.audit_trail ?? [];
                     auditTrail.push({ ts, action: 'updated', prev_outcome: prev.outcome });
                     if (auditTrail.length > 20)
@@ -521,6 +538,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 ...(group ? { group: String(group).toLowerCase().trim() } : {}),
                 visibility,
                 recall_count: recallCount,
+                ...(lastRecalledAt ? { last_recalled_at: lastRecalledAt } : {}),
                 ts,
                 verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
                 confidence: 1.0,
@@ -788,11 +806,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const ref = lesson.verified_at ?? lesson.ts;
                 const ageDays = (Date.now() - new Date(ref).getTime()) / 86400000;
                 const badge = confidenceBadge(confidence, ageDays);
-                // Recall resets verified_at (confidence clock restart)
+                // Recall resets verified_at (confidence clock restart) and stamps
+                // last_recalled_at so the recall-quality dashboard can measure recency.
+                const recalledAt = new Date().toISOString();
                 const updatedLesson = {
                     ...lesson,
                     recall_count: (lesson.recall_count ?? 0) + 1,
-                    verified_at: new Date().toISOString(),
+                    verified_at: recalledAt,
+                    last_recalled_at: recalledAt,
                     confidence: 1.0,
                 };
                 await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
@@ -837,7 +858,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     trustBadge,
                     `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
                     ``,
-                    `**What worked:** ${lesson.what_worked}`,
+                    // what_worked may be empty for unresolved failure lessons (the API
+                    // accepts empty what_worked when outcome=failure) — skip the line.
+                    lesson.what_worked ? `**What worked:** ${lesson.what_worked}` : '',
                     lesson.what_failed ? `**What failed (avoid this):** ${lesson.what_failed}` : '',
                     lesson.context ? `**Context:** ${lesson.context}` : '',
                     (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f) => `\`${f}\``).join(', ')}` : '',
@@ -906,6 +929,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Exclude archived lessons — they are kept for audit but must not surface in recall.
             const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
             let crossAuthorThisCall = 0;
+            let successRecallsThisCall = 0;
             for (const m of lessonMatches.slice(0, 5)) {
                 const existing = await redis.get(m.key).catch(() => null);
                 if (existing) {
@@ -914,7 +938,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     if (lesson?.state === 'archived')
                         continue;
                     if (lesson) {
-                        const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
+                        const recalledAt = new Date().toISOString();
+                        const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: recalledAt, last_recalled_at: recalledAt };
                         redis.set(m.key, JSON.stringify(updated)).catch(() => { });
                         const sev = lesson.severity;
                         const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
@@ -934,6 +959,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             ckgUpdateEdge(redis, reqPersonId, 'collaborates', authPersonId, true).catch(() => { });
                             ckgUpdateEdge(redis, authPersonId, 'collaborates', reqPersonId, true).catch(() => { });
                         }
+                        if (lesson.outcome === 'success')
+                            successRecallsThisCall++;
                         // Surface banner for proven successes (recall_count >= 1 means it's been validated)
                         if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
                             savedHere.push({
@@ -949,8 +976,11 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             // Metric 1 (time-to-first-recall): stamp the first time recall returned a
-            // proven lesson. SET NX so only the first successful recall wins.
-            if (savedHere.length > 0) {
+            // successful lesson. SET NX so only the first successful recall wins.
+            // Deliberately NOT gated on savedHere: savedHere requires a pre-existing
+            // recall_count >= 1, which would delay the stamp until the SECOND recall
+            // and inflate every TTFR percentile derived from it.
+            if (successRecallsThisCall > 0) {
                 redis.set(`cachly:stats:first_recall_at:${instance_id}`, new Date().toISOString(), 'EX', 365 * 86400, 'NX').catch(() => { });
             }
             // ── Layer 2: Semantic search (parallel, optional) ────────────────────────