@cachly-dev/mcp-server 0.10.127 → 0.10.129

package/dist/src/handlers/brain.js

@@ -3,9 +3,9 @@ import { createRequire } from 'node:module';
 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 { ersparteMinuten, istStarterLektion } from '../wertbeitrag.js';
+import { ersparteMinuten, istStarterLektion, zaehltAlsErsparnis } from '../wertbeitrag.js';
 import { lessonPreviewLines, trimTo } from '../lesson-preview.js';
-import { meldeEinmal, OHNE_VEKTOREN, OHNE_DIENST, OHNE_FRAGEVEKTOR } from '../aussetzer.js';
+import { meldeEinmal, meldeUndVermerke, fehlerText, OHNE_VEKTOREN, OHNE_DIENST, OHNE_FRAGEVEKTOR, SINNPFAD_ABBRUCH, OHNE_SCHREIBVEKTOR } from '../aussetzer.js';
 import { versuchStart, neueKennung, wendeZuteilungAn, schliesseVersuchAb } from '../versuch.js';
 /**
  * Preview for one smart_recall hit.
@@ -38,9 +38,10 @@ export function recallVorschau(key, content, maxChars) {
 import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope, reviewModeEnabled, storeLessonProposal } from './team.js';
 import { keywordSearch, wortindexEntwerten, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality, qualityMultiplier, extractLessonQuality } from '../rerank.js';
-import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+import { computeEmbedding, hasEmbedProvider, EMBED_PROVIDER } from '../embeddings.js';
+import { repariereFelder } from '../feldreparatur.js';
 import { VEKTOR_PRAEFIX, NAME_VEKTOR_PRAEFIX, packe, textFuerVektor, textFuerNamensVektor, Vektorbestand, } from '../bedeutung.js';
-import { schreibeEingaenge, Eingangsbestand, EINGANG_GEWICHT } from '../eingaenge.js';
+import { schreibeEingaenge, Eingangsbestand } from '../eingaenge.js';
 import { Seltenheitsbestand } from '../seltenheitsbestand.js';
 import { spurLegen } from '../spuren.js';
 import { bewerteTopf, spreizeImTopf, reichereAn, inhaltsWoerter, grobStamm, GEWICHTE, } from '../rangfolge.js';
@@ -54,10 +55,127 @@ import { bewerteTopf, spreizeImTopf, reichereAn, inhaltsWoerter, grobStamm, GEWI
 const vektorbestand = new Vektorbestand();
 /** Dieselbe Mechanik, andere Sicht: die Vektoren der Themennamen. */
 const namensbestand = new Vektorbestand(60_000, NAME_VEKTOR_PRAEFIX);
-/** Die Fehlertext-Eingaenge, je Lektion ihr bester. */
+/** Die Fehlertext-Eingaenge, je Lektion ihr bester. Sortiert mit, nominiert nicht. */
 const eingangsbestand = new Eingangsbestand();
 /** Die Wortstatistik des Bestands — stehend, nicht je Frage neu. */
 const seltenheitsbestand = new Seltenheitsbestand();
+/**
+ * Wie viele Lektionen die Bedeutungs-Tuer in den Topf nominiert.
+ *
+ * Stand bis zum 21.08.2026 auf 25, ohne dass die Zahl je gemessen worden
+ * waere. Sie war der Grund fuer die "Decke", die am 20.08. fuer eine
+ * Naturkonstante gehalten wurde ("kein Sortierer kommt ueber 84/90 Prozent").
+ * Gemessen am eingefrorenen Korpus (src/bench/topfgroesse.ts):
+ *
+ *   POOL   Platz 1     @3    Top 10   Topf    ms/Frage
+ *     25     39,0     51,0    71,0    90,0      57
+ *     50     38,0     52,0    71,0    95,0      50
+ *     75     38,0     53,0    71,0    97,0      52
+ *    100     38,0     52,0    70,0    99,0      54
+ *    150     37,0     53,0    70,0    99,0      57
+ *
+ * 75 ist der Punkt, an dem die Findequote@3 ihr Maximum hat (53 statt 51) und
+ * die Decke von 90 auf 97 Prozent steigt. Der Preis ist EIN Punkt auf Platz 1.
+ * Fuer den Nutzer zaehlt @3: er sieht drei Lektionen, nicht eine.
+ *
+ * Warum die Decke wichtiger ist als die Kopfzahl: was nicht im Topf ist, kann
+ * keine spaetere Stufe zurueckholen. Jede kuenftige Verbesserung der
+ * Sortierung hat damit 59 Punkte Spielraum (97 minus 38) statt 51.
+ *
+ * Die Rechenzeit bleibt im Rauschen: die Vorauswahl rechnet ohnehin ueber ALLE
+ * Lektionen: nur die Sortierung bekommt mehr Kandidaten, und die kostet je
+ * Kandidat vier Zahlen.
+ */
+const SINN_TOPF = 75;
+/**
+ * Ab welcher Naehe eine Fehlertext-Tuer als Signal zaehlt.
+ *
+ * ── Die Geschichte, weil sie die Zahl erklaert ──────────────────────────────
+ *
+ * Am 21.08.2026 wurden die Tueren ausgebaut: sie kosteten zwei Punkte auf
+ * Platz 1 und vier auf die Topfdeckung. Ein paar Stunden spaeter fiel bei der
+ * Resonanz-Messung der wahre Grund auf, und er lag nicht an der Idee.
+ *
+ * `spreizeImTopf` gibt einem fehlenden Wert (-2) eine NULL — den schlechtesten
+ * Wert im Bereich [0,1]. Wer das Merkmal hat, kann also nur gewinnen; wer es
+ * nicht hat, nur verlieren. Bei den Tueren betraf das 108 von 507 Lektionen
+ * ohne Fehlertext: sie wurden systematisch nach unten gedrueckt, unabhaengig
+ * davon, ob die Tueren der anderen ueberhaupt passten.
+ *
+ * Mit Schwelle zaehlt eine Tuer nur, wenn sie WIRKLICH nahe ist. Darunter
+ * meldet sie -2 und ist damit "kein Wert" statt "schlechter Wert" — und der
+ * Vergleich laeuft nur noch zwischen Lektionen, bei denen das Merkmal etwas
+ * aussagt.
+ *
+ * ── Warum 0,5 und nicht der beste Wert ──────────────────────────────────────
+ *
+ * Gemessen ueber alle 100 Fragen (src/bench/schwelle-abtasten.ts):
+ *
+ *   Schwelle   0,35   0,40   0,45   0,50   0,55   0,60   0,70
+ *   Platz 1    39,0   38,0   40,0   40,0   41,0   39,0   38,0
+ *   @3         53,0   54,0   53,0   55,0   55,0   55,0   53,0
+ *   (ohne Merkmal: 38,0 / 53,0)
+ *
+ * 0,55 waere der hoechste Punkt. Genommen wird 0,50, weil der Gewinn dort
+ * MITTIG in einem breiten Band liegt (0,45 bis 0,60 gewinnen alle). Ein Wert
+ * am Rand des Bandes ist eine Eigenschaft des Pruefsatzes — genau daran ist am
+ * 19.08. die alte Rangfolge-Formel gescheitert.
+ *
+ * Kreuzweise geprueft (auf einer Haelfte gesucht, auf der anderen gemessen):
+ * Platz 1 41,0 gegen 38,0 Prozent. Der Gewinn haelt, wenn er nie dieselben
+ * Fragen sieht, an denen er gefunden wurde.
+ *
+ * Die Tueren nominieren weiter NICHT — dort haben sie die richtige Antwort
+ * fuenfmal ganz aus dem Topf gedraengt und einmal hineingeholt.
+ */
+const EINGANG_SCHWELLE = 0.5;
+/**
+ * Wie stark die Tuer mitsortiert.
+ *
+ * NICHT EINGANG_GEWICHT (0,5) aus eingaenge.js: der Wert wurde fuer die alte
+ * Bauform OHNE Schwelle bemessen. Mit Schwelle ist er zu hoch — gemessen ueber
+ * alle 100 Fragen (src/bench/schwelle-abtasten.ts, Schwelle 0,5):
+ *
+ *   Gewicht    0,10   0,15   0,20   0,30   0,40   0,50
+ *   Platz 1    39,0   41,0   40,0   40,0   41,0   41,0
+ *   @3         55,0   55,0   55,0   55,0   54,0   52,0
+ *
+ * Bei 0,5 bricht die Findequote@3 auf 52 ein — das Merkmal draengt dann
+ * Treffer von Platz 2 und 3 weg, um einen auf Platz 1 zu heben. Fuer den
+ * Nutzer zaehlt @3: er sieht drei Lektionen.
+ *
+ * 0,2 liegt mittig im Band, in dem BEIDE Kennzahlen ihr Maximum halten.
+ */
+const EINGANG_SORTIER_GEWICHT = 0.2;
+/*
+ * ── Ein ZWEITES Tuer-Merkmal wurde gemessen und NICHT eingebaut ─────────────
+ *
+ * Damit es niemand in vier Wochen neu baut. Der Kandidat: der MITTELWERT ueber
+ * alle Tueren einer Lektion, als sechstes Merkmal NEBEN dem Maximum oben
+ * (Eingangsbestand.mittelNaehe, samt Begruendung, warum die beiden
+ * entgegengesetzt ziehen). Abgetastet in src/bench/mittel-gewicht-abtasten.ts.
+ *
+ * Er haengt vollstaendig davon ab, WELCHE Tueren im Speicher liegen:
+ *
+ *   Bestand                              Tueren   Abdeckung   @3 ohne -> mit
+ *   echter Speicher (Fehlertexte)          965      78,4 %     55,0 -> 51,0
+ *   volle Impfung (Fragewolken)           2462     100,0 %     58,0 -> 63,0
+ *   dasselbe, unabhaengiger Fragensatz    2462     100,0 %     63,0 -> 67,0
+ *
+ * Auf dem heutigen Speicher SCHADET er also, auf dem geimpften nuetzt er. Die
+ * naheliegende Erklaerung — Lektionen ohne Tuer bekommen ueber spreizeImTopf
+ * eine Null, also den schlechtesten Platz — wurde geprueft und ist NICHT der
+ * Grund: mit mittiger statt schlechtester Einstufung faellt @3 genauso
+ * (55,0 -> 52,0, dabei 14 Fragen besser und 30 schlechter).
+ *
+ * Ehrlich bleibt eine Unschaerfe: die beiden Bestaende unterscheiden sich in
+ * ZWEI Dingen zugleich — Abdeckung (78 gegen 100 Prozent) UND Art der Tuer
+ * (Fehlertext gegen handgeschriebene Fragewolke). Welches davon den Ausschlag
+ * gibt, ist mit diesen Daten nicht zu trennen.
+ *
+ * Bedingung fuer einen zweiten Anlauf: die Fragewolken liegen im echten
+ * Speicher. Dann neu abtasten — nicht die 0,3 von damals uebernehmen.
+ */
 import { upgradeNudge } from '../upgrade-nudge.js';
 import { recallTiefe, TIEFE_VOLL, TIEFE_VOLL_MEHRTHEMIG } from '../recall-tiefe.js';
 import { nutzungInWorten, nutzungsSchluessel, verdichte } from '../werkzeug-nutzung.js';
@@ -539,7 +657,29 @@ async function getRecallGate(instanceId, apiFetch) {
 export async function handleBrainTool(name, args, getConnection, apiFetch) {
     switch (name) {
         case 'learn_from_attempts': {
-            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 { instance_id, topic, outcome, what_worked: rohWorked, what_failed: rohFailed = '', context: rohCtx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', visibility = 'team', service = '', service_kind = 'service', group = '', } = args;
+            /*
+             * Verklebte Felder trennen, BEVOR irgendetwas geschrieben wird.
+             *
+             * Wer ein Feld mit dem falschen Tag schliesst, uebergibt den ganzen
+             * Rest — samt der Marke des naechsten Feldes — als what_worked. Das
+             * Ergebnis sieht aus wie eine volle Lektion, hat aber ein leeres
+             * what_failed und Steuerzeichen im Fliesstext.
+             *
+             * Belegt am 22.08.2026 an derselben Lektion zweimal hintereinander,
+             * beide Male unbemerkt: die Rueckmeldung zeigte den kaputten Text an
+             * und sah trotzdem aus wie ein Erfolg.
+             *
+             * ohneMarkierungen() in eingaenge.ts raeumt dasselbe beim EINBETTEN
+             * weg. Das rettet den Vektor, aber nicht den Bestand — im Speicher
+             * bleibt der Text falsch und what_failed leer. Deshalb hier, an der
+             * einzigen Stelle, an der der Fehler entsteht.
+             */
+            const { what_worked, what_failed = '', context: ctx = '' } = repariereFelder({
+                what_worked: rohWorked,
+                what_failed: rohFailed,
+                context: rohCtx,
+            });
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
             /*
@@ -756,7 +896,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         if (v?.length)
                             await redis.set(`${VEKTOR_PRAEFIX}${topic}`, packe(v));
                     }
-                    catch { /* kein Vektor ist besser als keine Lektion */ }
+                    catch (e) {
+                        // Kein Vektor ist besser als keine Lektion — aber der GRUND darf
+                        // nicht verlorengehen. Vor dem 22.08.2026 stand hier ein leeres
+                        // catch, und drei Kundeninstanzen hatten Lektionen ohne Vektoren,
+                        // ohne dass irgendwo stand, warum (siehe OHNE_SCHREIBVEKTOR).
+                        meldeEinmal(OHNE_SCHREIBVEKTOR, `Volltext-Vektor nicht geschrieben (${EMBED_PROVIDER}): ${fehlerText(e)}`
+                            + ' — die Lektion ist gespeichert, der Bedeutungsabgleich uebergeht sie.');
+                    }
                     // Der Themenname als eigene Sicht.
                     //
                     // Er ist kurz und frageaehnlich; eine 60-Zeichen-Frage gegen 60
@@ -769,7 +916,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         if (nv?.length)
                             await redis.set(`${NAME_VEKTOR_PRAEFIX}${topic}`, packe(nv));
                     }
-                    catch { /* siehe oben */ }
+                    catch (e) {
+                        meldeEinmal(OHNE_SCHREIBVEKTOR, `Namens-Vektor nicht geschrieben (${EMBED_PROVIDER}): ${fehlerText(e)}`
+                            + ' — siehe oben, die Lektion selbst ist gespeichert.');
+                    }
                     // Die zweite Tuer: woertliche Fehlertexte als eigene Eingaenge.
                     //
                     // Gemessen am 20.08.2026 an 499 Lektionen mit zwei unabhaengigen
@@ -783,7 +933,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     try {
                         await schreibeEingaenge(redis, topic, gelesen, computeEmbedding);
                     }
-                    catch { /* keine Eingaenge ist besser als keine Lektion */ }
+                    catch (e) {
+                        meldeEinmal(OHNE_SCHREIBVEKTOR, `Eingaenge nicht geschrieben (${EMBED_PROVIDER}): ${fehlerText(e)}`
+                            + ' — siehe oben, die Lektion selbst ist gespeichert.');
+                    }
                 })();
             }
             // Track in decision log for session replay
@@ -1059,8 +1212,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 // as a broad smart_recall — the user asked the brain a question either way.
                 void bumpRecallQuota(redis);
                 // Track estimated time saved (30m minor · 60m major · 240m critical).
-                // Starter-Lektionen zaehlen 0 — siehe wertbeitrag.ts.
-                const savedMins = ersparteMinuten(lesson);
+                // Nur der ERSTE Abruf zaehlt, und der Startvorrat gar nicht — die
+                // Begruendung fuer beides steht in wertbeitrag.ts. `lesson` ist hier
+                // noch der Stand VOR dieser Erhoehung, das ist Absicht.
+                const savedMins = zaehltAlsErsparnis(lesson) ? ersparteMinuten(lesson) : 0;
                 if (savedMins > 0) {
                     redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
                 }
@@ -1220,29 +1375,41 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         .map((m) => m.key.slice('cachly:lesson:best:'.length));
                     // ── Die Vorauswahl ────────────────────────────────────────────────
                     //
-                    // Woerter (Top 25) vereinigt mit Bedeutung (Top 25). Bei vorhandenen
-                    // Eingaengen zaehlt je Lektion ihr BESTER Eingang statt des
-                    // Volltextvektors — gemessen am 20.08.2026 hebt das die Findequote@3
-                    // von 52 auf 56 Prozent, und mit dem Merkmal unten auf 58.
+                    // Woerter (Top 25) vereinigt mit Bedeutung (Top 25). Zwei Tueren je
+                    // Lektion: Volltext und Themenname.
                     //
-                    // Der Preis steht offen im Ergebnisdokument: dieselben Eingaenge
-                    // SENKEN die Decke von 89 auf 86 Prozent. Fuer den Nutzer zaehlt die
-                    // Findequote — er sieht drei Lektionen, nicht 25.
+                    // Die DRITTE Tuer — woertliche Fehlertexte als eigene Eingaenge —
+                    // stand hier vom 20.08. bis zum 21.08.2026 und ist AUSGEBAUT.
+                    // Die Begruendung, mit der sie kam ("hebt die Findequote@3 von 52
+                    // auf 56/58"), reproduzierte auf dem eingefrorenen 100-Fragen-Satz
+                    // nicht mehr. Dort, je Frage nachgemessen (tueren-vergleich.ts):
                     //
-                    // WICHTIG: das Maximum ueber ALLE Tueren — Volltext, Themenname UND
-                    // Fehlertext. Der erste Versuch am 20.08. hat die Volltext-Auswahl
-                    // durch die Eingangs-Auswahl ERSETZT. Das war falsch: nur 399 von 507
-                    // Lektionen tragen einen Fehlertext, die uebrigen 108 fielen damit
-                    // aus der Vorauswahl. Am echten Bestand gemessen fiel die Trefferlage
-                    // von 90 auf 70 Prozent und die Findequote@3 von 50 auf 48.
-                    const naeheBesteTuer = (t) => Math.max(vektorbestand.naehe(frageVektor, t), namensbestand.naehe(frageVektor, t), eingangsbestand.besteNaehe(frageVektor, t));
+                    //   Bauform         Platz 1    @3     Top 10   im Topf
+                    //   mit Tueren        37,0    52,0    70,0     86,0
+                    //   ohne Tueren       39,0    51,0    71,0     90,0
+                    //   nur sortieren     35,0    50,0    71,0     90,0
+                    //
+                    // Der eigentliche Schaden sass in der Vorauswahl: die Tueren
+                    // draengten die richtige Antwort FUENFMAL ganz aus dem Topf und
+                    // retteten sie EINMAL. Ein schlechter Platz ist ein
+                    // Schoenheitsfehler — ein Rauswurf aus dem Topf ist ein
+                    // Totalausfall, den keine spaetere Stufe heilen kann. Und die
+                    // Decke des Topfes ist die harte Grenze jeder kuenftigen besseren
+                    // Sortierung: 90 statt 86 Prozent ist der wertvollere Rohstoff.
+                    //
+                    // Die Eingaenge werden weiter GESCHRIEBEN (siehe schreibeEingaenge
+                    // weiter oben): die Daten kosten einen Einbettungsaufruf je Lektion
+                    // und sind der natuerliche Speicherplatz fuer den naechsten Anlauf —
+                    // gemessene Frage-Vektoren echter Treffer statt geratener
+                    // Fehlertexte.
+                    const naeheBesteTuer = (t) => Math.max(vektorbestand.naehe(frageVektor, t), namensbestand.naehe(frageVektor, t));
                     const alleThemen = [...seltenheitsbestand.themen()];
                     const sinnThemen = (alleThemen.length > 0
                         ? alleThemen
                         : vektorbestand.aehnlichste(frageVektor, 500).map((x) => x.topic))
                         .map((t) => ({ t, n: naeheBesteTuer(t) }))
                         .sort((a, b) => b.n - a.n)
-                        .slice(0, 25)
+                        .slice(0, SINN_TOPF)
                         .map((x) => x.t);
                     // ── Die Sortierung ───────────────────────────────────────────────
                     //
@@ -1258,10 +1425,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     //     bewerteTopf                              52 %
                     //     bewerteTopf + Eingaenge                  58 %
                     //
-                    // Faellt ein Merkmal aus (kein Namensvektor, kein Eingang), meldet es
-                    // -2 und `spreizeImTopf` macht daraus fuer alle dieselbe Null — die
-                    // Sortierung faellt dann auf die uebrigen Merkmale zurueck, statt
-                    // falsch zu werden.
+                    // KORREKTUR 21.08.2026: die 58 % reproduzieren auf dem EINGEFRORENEN
+                    // 100-Fragen-Satz nicht (dieselben Fragen!): dort bringt die
+                    // Eingangs-Sortierung 52 statt 51 — ein Punkt, nicht sechs — und
+                    // kostet zwei Punkte auf Platz 1. Die Eingaenge sind deshalb aus
+                    // Vorauswahl UND Sortierung ausgebaut; Messung und alle drei
+                    // Bauformen in src/bench/tueren-vergleich.ts. Die Tabelle oben
+                    // bleibt als Beleg, wie eine Zahl aussieht, die eine Pipeline
+                    // beschreibt, die es nicht mehr gibt.
+                    //
+                    // Faellt ein Merkmal aus (kein Namensvektor), meldet es -2 und
+                    // `spreizeImTopf` (in bewerteTopf) macht daraus fuer alle dieselbe
+                    // Null — die Sortierung faellt dann auf die uebrigen Merkmale
+                    // zurueck, statt falsch zu werden.
                     const topf = [...new Set([...wortThemen, ...sinnThemen])];
                     const besteDrei = sinnThemen.slice(0, 3)
                         .map((t) => vektorbestand.rohvektor(t)).filter(Boolean);
@@ -1277,10 +1453,21 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             : 0,
                     }));
                     let punkte = bewerteTopf(bewertbar, GEWICHTE);
+                    // Die Fehlertext-Tuer als fuenftes Merkmal — mit Schwelle.
+                    //
+                    // Sie NOMINIERT nicht (siehe Vorauswahl oben), sie sortiert nur mit.
+                    // Und sie zaehlt nur, wo sie wirklich nahe ist: unterhalb von
+                    // EINGANG_SCHWELLE meldet sie -2, und spreizeImTopf behandelt das
+                    // als "kein Wert" statt als "schlechter Wert". Ohne diese Schwelle
+                    // bekamen die 108 Lektionen ohne Fehlertext systematisch Abzug —
+                    // das war der ganze gemessene Schaden, nicht die Idee.
                     if (eingangsbestand.groesse > 0) {
-                        const naehen = topf.map((t) => eingangsbestand.besteNaehe(frageVektor, t));
+                        const naehen = topf.map((t) => {
+                            const n = eingangsbestand.besteNaehe(frageVektor, t);
+                            return n >= EINGANG_SCHWELLE ? n : -2;
+                        });
                         const gespreizt = spreizeImTopf(naehen);
-                        punkte = punkte.map((pkt, i) => pkt + EINGANG_GEWICHT * gespreizt[i]);
+                        punkte = punkte.map((pkt, i) => pkt + EINGANG_SORTIER_GEWICHT * gespreizt[i]);
                     }
                     const reihenfolge = topf
                         .map((t, i) => ({ t, p: punkte[i] }))
@@ -1309,7 +1496,23 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     sinnAngewandt = true;
                     return sortiert;
                 }
-                catch {
+                catch (e) {
+                    // Der Auffang. Bis zum 21.08.2026 stand hier `catch { return
+                    // kwMatches; }` — ohne Meldung, ohne Zaehler.
+                    //
+                    // Gefunden vom ersten Lauf der Gegenrede (Rolle: Der Wettbewerber),
+                    // aus einer fremden Narbe: ein Abruf hinter einem Zeitlimit gegen
+                    // einen Einbettungsdienst, der bei Inaktivitaet kalt startete. Der
+                    // erste Aufruf nach einer Pause riss das Limit, wurde hier gefangen
+                    // und lieferte dieselbe Antwort wie eine Suche ohne Treffer. Rund
+                    // 40 Prozent der Rueckrufe in der ersten Stunde nach jedem
+                    // Kaltstart waren stille Zeitueberlaeufe — bemerkt Wochen spaeter.
+                    //
+                    // Die drei Ausstiege darueber melden sich seit PR #424. Dieser ist der
+                    // gefaehrlichste von allen, weil er das UNERWARTETE faengt: die drei
+                    // anderen sind Luecken, das hier ist ein Fehler.
+                    await meldeUndVermerke(redis, SINNPFAD_ABBRUCH, `der Bedeutungspfad brach ab (${e instanceof Error ? e.message : String(e)}) `
+                        + '— diese Suche lief nur ueber Woerter');
                     return kwMatches;
                 }
             })();
@@ -1355,8 +1558,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         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(() => { });
-                        // Starter-Lektionen zaehlen 0 — siehe wertbeitrag.ts.
-                        const savedMins = ersparteMinuten(lesson);
+                        // Nur der ERSTE Abruf zaehlt — siehe wertbeitrag.ts. Diese
+                        // Schleife lief ueber bis zu FUENF Lektionen je Aufruf und schrieb
+                        // jeder die volle Recherchezeit gut, bei jedem Aufruf erneut.
+                        const savedMins = zaehltAlsErsparnis(lesson) ? ersparteMinuten(lesson) : 0;
                         if (savedMins > 0) {
                             redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
                         }
@@ -1889,11 +2094,22 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             if (streakMessage)
                 lines.push(streakMessage, '');
             // Time saved (only show when meaningful — 30+ minutes)
+            //
+            // Die Zahl nennt ihre Grundlage. Bis zum 22.08.2026 stand hier nur
+            // "~1664h total" — eine Zahl, die niemand nachrechnen konnte und die auf
+            // diesem 82 Tage alten Brain mehr Stunden behauptete, als eine Person in
+            // dieser Zeit ueberhaupt haette arbeiten koennen. Jetzt steht daneben,
+            // WORAUS sie entsteht: so viele eigene Lektionen, jede einmal gezaehlt.
+            // Wer will, kann sie abzaehlen.
             if (timeSavedMins >= 30) {
                 const h = Math.floor(timeSavedMins / 60);
                 const m = Math.round(timeSavedMins % 60);
                 const timeStr = h > 0 ? `${h}h${m > 0 ? ` ${m}m` : ''}` : `${m}m`;
-                lines.push(`⏱️ **Brain saved you ~${timeStr} total** (time not re-researching known fixes)`, '');
+                const zaehlende = lessons.filter((l) => !istStarterLektion(l) && (l.recall_count ?? 0) > 0).length;
+                const grundlage = zaehlende > 0
+                    ? ` — ${zaehlende} of your own lessons that already helped, counted once each`
+                    : ' (time not re-researching known fixes)';
+                lines.push(`⏱️ **Brain saved you ~${timeStr} total**${grundlage}`, '');
             }
             // Upgrade nudge — surfaces the free-tier quota BEFORE the wall, once
             // per session and right next to the value it just proved.