context-mode 1.0.87 → 1.0.89

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.87"
+    "version": "1.0.89"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.87",
+      "version": "1.0.89",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.87",
+  "version": "1.0.89",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.87",
+  "version": "1.0.89",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.87",
+  "version": "1.0.89",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/adapters/claude-code/index.js

@@ -421,7 +421,21 @@ export class ClaudeCodeAdapter {
         if (pluginHooks) {
             const allCovered = REQUIRED_HOOKS.every((ht) => this.checkHookType(undefined, pluginHooks, ht));
             if (allCovered) {
-                // Still write cleaned settings (stale removal) but don't add new entries
+                // Remove ALL existing context-mode hooks from settings.json — hooks.json
+                // is the source of truth. Keeping them causes duplicate concurrent hook
+                // processes (one from settings.json, one from hooks.json), which triggers
+                // "non-blocking hook error" warnings on every tool call.
+                for (const hookType of Object.keys(hooks)) {
+                    const entries = hooks[hookType];
+                    if (!Array.isArray(entries))
+                        continue;
+                    const filtered = entries.filter((entry) => !isAnyContextModeHook(entry));
+                    const removed = entries.length - filtered.length;
+                    if (removed > 0) {
+                        hooks[hookType] = filtered;
+                        changes.push(`Removed ${removed} duplicate ${hookType} hook(s) — covered by plugin hooks.json`);
+                    }
+                }
                 settings.hooks = hooks;
                 this.writeSettings(settings);
                 changes.push("Skipped settings.json registration — plugin hooks.json is sufficient");

package/build/cli.js

@@ -360,55 +360,108 @@ async function doctor() {
  * Insight — analytics dashboard
  * ------------------------------------------------------- */
 async function insight(port) {
-    const { execSync, spawn } = await import("node:child_process");
-    const { statSync, mkdirSync, cpSync } = await import("node:fs");
-    const insightSource = resolve(getPluginRoot(), "insight");
-    // Adapter-agnostic cache: use ~/.claude/context-mode/insight-cache as default
-    // (matches server.ts pattern but CLI doesn't have adapter detection)
-    const cacheDir = join(homedir(), ".claude", "context-mode", "insight-cache");
-    if (!existsSync(join(insightSource, "server.mjs"))) {
-        console.error("Error: Insight source not found. Try upgrading context-mode.");
+    try {
+        const { execSync, spawn } = await import("node:child_process");
+        const { statSync, mkdirSync, cpSync } = await import("node:fs");
+        const insightSource = resolve(getPluginRoot(), "insight");
+        // Detect platform + adapter for correct session/content paths
+        const detection = detectPlatform();
+        const adapter = await getAdapter(detection.platform);
+        const sessDir = adapter.getSessionDir();
+        const contentDir = join(dirname(sessDir), "content");
+        const cacheDir = join(dirname(sessDir), "insight-cache");
+        if (!existsSync(join(insightSource, "server.mjs"))) {
+            console.error("Error: Insight source not found. Try upgrading context-mode.");
+            process.exit(1);
+        }
+        mkdirSync(cacheDir, { recursive: true });
+        // Copy source if newer
+        const srcMtime = statSync(join(insightSource, "server.mjs")).mtimeMs;
+        const cacheMtime = existsSync(join(cacheDir, "server.mjs"))
+            ? statSync(join(cacheDir, "server.mjs")).mtimeMs : 0;
+        if (srcMtime > cacheMtime) {
+            console.log("Copying Insight source...");
+            cpSync(insightSource, cacheDir, { recursive: true, force: true });
+        }
+        // Install deps
+        if (!existsSync(join(cacheDir, "node_modules"))) {
+            console.log("Installing dependencies (first run)...");
+            try {
+                execSync("npm install --production=false", { cwd: cacheDir, stdio: "inherit", timeout: 300000 });
+            }
+            catch {
+                // Clean up partial install so next run retries fresh
+                try {
+                    rmSync(join(cacheDir, "node_modules"), { recursive: true, force: true });
+                }
+                catch { }
+                throw new Error("npm install failed — please retry");
+            }
+            // Sentinel check: verify install completed (cold cache can timeout leaving partial node_modules)
+            if (!existsSync(join(cacheDir, "node_modules", "vite")) || !existsSync(join(cacheDir, "node_modules", "better-sqlite3"))) {
+                rmSync(join(cacheDir, "node_modules"), { recursive: true, force: true });
+                throw new Error("npm install incomplete — please retry");
+            }
+        }
+        // Build
+        console.log("Building dashboard...");
+        execSync("npx vite build", { cwd: cacheDir, stdio: "pipe", timeout: 60000 });
+        // Start server
+        const url = `http://localhost:${port}`;
+        console.log(`\n  context-mode Insight\n  ${url}\n`);
+        const child = spawn("node", [join(cacheDir, "server.mjs")], {
+            cwd: cacheDir,
+            env: {
+                ...process.env,
+                PORT: String(port),
+                INSIGHT_SESSION_DIR: sessDir,
+                INSIGHT_CONTENT_DIR: contentDir,
+            },
+            stdio: "inherit",
+        });
+        child.on("error", () => { }); // prevent unhandled error crash
+        // Wait for server to be ready, then verify it started
+        await new Promise(r => setTimeout(r, 1500));
+        try {
+            const { request } = await import("node:http");
+            await new Promise((resolve, reject) => {
+                const req = request(`http://127.0.0.1:${port}/api/overview`, { timeout: 3000 }, (res) => {
+                    resolve();
+                    res.resume();
+                });
+                req.on("error", reject);
+                req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+                req.end();
+            });
+        }
+        catch {
+            console.error(`\nError: Port ${port} appears to be in use. Either a previous dashboard is still running, or another service is using this port.`);
+            console.error(`\nTo fix:`);
+            console.error(`  Kill the existing process: ${process.platform === "win32" ? `netstat -ano | findstr :${port}` : `lsof -ti:${port} | xargs kill`}`);
+            console.error(`  Or use a different port:   context-mode insight ${port + 1}`);
+            child.kill();
+            process.exit(1);
+        }
+        // Open browser
+        const platform = process.platform;
+        try {
+            if (platform === "darwin")
+                execSync(`open "${url}"`, { stdio: "pipe" });
+            else if (platform === "win32")
+                execSync(`start "" "${url}"`, { stdio: "pipe" });
+            else
+                execSync(`xdg-open "${url}" 2>/dev/null || sensible-browser "${url}" 2>/dev/null`, { stdio: "pipe" });
+        }
+        catch { /* best effort */ }
+        // Keep alive until Ctrl+C
+        process.on("SIGINT", () => { child.kill(); process.exit(0); });
+        process.on("SIGTERM", () => { child.kill(); process.exit(0); });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nInsight error: ${msg}`);
         process.exit(1);
     }
-    mkdirSync(cacheDir, { recursive: true });
-    // Copy source if newer
-    const srcMtime = statSync(join(insightSource, "server.mjs")).mtimeMs;
-    const cacheMtime = existsSync(join(cacheDir, "server.mjs"))
-        ? statSync(join(cacheDir, "server.mjs")).mtimeMs : 0;
-    if (srcMtime > cacheMtime) {
-        console.log("Copying Insight source...");
-        cpSync(insightSource, cacheDir, { recursive: true, force: true });
-    }
-    // Install deps
-    if (!existsSync(join(cacheDir, "node_modules"))) {
-        console.log("Installing dependencies (first run)...");
-        execSync("npm install --production=false", { cwd: cacheDir, stdio: "inherit", timeout: 120000 });
-    }
-    // Build
-    console.log("Building dashboard...");
-    execSync("npx vite build", { cwd: cacheDir, stdio: "pipe", timeout: 30000 });
-    // Start server
-    const url = `http://localhost:${port}`;
-    console.log(`\n  context-mode Insight\n  ${url}\n`);
-    const child = spawn("node", [join(cacheDir, "server.mjs")], {
-        cwd: cacheDir,
-        env: { ...process.env, PORT: String(port) },
-        stdio: "inherit",
-    });
-    // Open browser
-    const platform = process.platform;
-    try {
-        if (platform === "darwin")
-            execSync(`open "${url}"`, { stdio: "pipe" });
-        else if (platform === "win32")
-            execSync(`start "" "${url}"`, { stdio: "pipe" });
-        else
-            execSync(`xdg-open "${url}" 2>/dev/null || sensible-browser "${url}" 2>/dev/null`, { stdio: "pipe" });
-    }
-    catch { /* best effort */ }
-    // Keep alive until Ctrl+C
-    process.on("SIGINT", () => { child.kill(); process.exit(0); });
-    process.on("SIGTERM", () => { child.kill(); process.exit(0); });
 }
 /* -------------------------------------------------------
  * Upgrade — adapter-aware hook configuration

package/build/pi-extension.js

@@ -110,6 +110,20 @@ function buildStatsText(db, sessionId) {
         return "context-mode stats unavailable (session DB error)";
     }
 }
+function resolveCommandContext(argsOrCtx, ctx) {
+    if (ctx !== undefined)
+        return ctx;
+    if (argsOrCtx && typeof argsOrCtx === "object")
+        return argsOrCtx;
+    return undefined;
+}
+function handleCommandText(text, ctx) {
+    if (ctx?.hasUI) {
+        ctx.ui.notify(text, "info");
+        return;
+    }
+    return { text };
+}
 // ── Extension entry point ────────────────────────────────
 /** Pi extension default export. Called once by Pi runtime with the extension API. */
 export default function piExtension(pi) {
@@ -300,16 +314,18 @@ export default function piExtension(pi) {
     // ── 8. Slash commands ──────────────────────────────────
     pi.registerCommand("ctx-stats", {
         description: "Show context-mode session statistics",
-        handler: () => {
-            if (!_db || !_sessionId) {
-                return { text: "context-mode: no active session" };
-            }
-            return { text: buildStatsText(_db, _sessionId) };
+        handler: async (argsOrCtx, maybeCtx) => {
+            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
+            const text = !_db || !_sessionId
+                ? "context-mode: no active session"
+                : buildStatsText(_db, _sessionId);
+            return handleCommandText(text, ctx);
         },
     });
     pi.registerCommand("ctx-doctor", {
         description: "Run context-mode diagnostics",
-        handler: () => {
+        handler: async (argsOrCtx, maybeCtx) => {
+            const ctx = resolveCommandContext(argsOrCtx, maybeCtx);
             const dbPath = getDBPath();
             const dbExists = existsSync(dbPath);
             const lines = [
@@ -334,7 +350,8 @@ export default function piExtension(pi) {
                     lines.push("- DB query error");
                 }
             }
-            return { text: lines.join("\n") };
+            const text = lines.join("\n");
+            return handleCommandText(text, ctx);
         },
     });
 }

package/build/server.js

@@ -502,7 +502,7 @@ server.registerTool("ctx_execute", {
             .string()
             .describe("Source code to execute. Use console.log (JS/TS), print (Python/Ruby/Perl/R), echo (Shell), echo (PHP), fmt.Println (Go), or IO.puts (Elixir) to output a summary to context."),
         timeout: z
-            .number()
+            .coerce.number()
             .optional()
             .default(30000)
             .describe("Max execution time in ms"),
@@ -798,7 +798,7 @@ server.registerTool("ctx_execute_file", {
             .string()
             .describe("Code to process FILE_CONTENT (file_content in Elixir). Print summary via console.log/print/echo/IO.puts."),
         timeout: z
-            .number()
+            .coerce.number()
             .optional()
             .default(30000)
             .describe("Max execution time in ms"),
@@ -1399,7 +1399,7 @@ server.registerTool("ctx_batch_execute", {
             "Each returns top 5 matching sections with full content. " +
             "This is your ONLY chance — put ALL your questions here. No follow-up calls needed.")),
         timeout: z
-            .number()
+            .coerce.number()
             .optional()
             .default(60000)
             .describe("Max execution time in ms (default: 60s)"),
@@ -1862,7 +1862,7 @@ server.registerTool("ctx_insight", {
         "parallel work patterns, project focus, and actionable insights. " +
         "First run installs dependencies (~30s). Subsequent runs open instantly.",
     inputSchema: z.object({
-        port: z.number().optional().describe("Port to serve on (default: 4747)"),
+        port: z.coerce.number().optional().describe("Port to serve on (default: 4747)"),
     }),
 }, async ({ port: userPort }) => {
     const port = userPort || 4747;
@@ -1895,11 +1895,26 @@ server.registerTool("ctx_insight", {
         const hasNodeModules = existsSync(join(cacheDir, "node_modules"));
         if (!hasNodeModules) {
             steps.push("Installing dependencies (first run, ~30s)...");
-            execSync("npm install --production=false", {
-                cwd: cacheDir,
-                stdio: "pipe",
-                timeout: 120000,
-            });
+            try {
+                execSync("npm install --production=false", {
+                    cwd: cacheDir,
+                    stdio: "pipe",
+                    timeout: 300000,
+                });
+            }
+            catch {
+                // Clean up partial install so next run retries fresh
+                try {
+                    rmSync(join(cacheDir, "node_modules"), { recursive: true, force: true });
+                }
+                catch { }
+                throw new Error("npm install failed — please retry");
+            }
+            // Sentinel check: verify install completed (cold cache can timeout leaving partial node_modules)
+            if (!existsSync(join(cacheDir, "node_modules", "vite")) || !existsSync(join(cacheDir, "node_modules", "better-sqlite3"))) {
+                rmSync(join(cacheDir, "node_modules"), { recursive: true, force: true });
+                throw new Error("npm install incomplete — please retry");
+            }
             steps.push("Dependencies installed.");
         }
         // Build
@@ -1907,20 +1922,81 @@ server.registerTool("ctx_insight", {
         execSync("npx vite build", {
             cwd: cacheDir,
             stdio: "pipe",
-            timeout: 30000,
+            timeout: 60000,
         });
         steps.push("Build complete.");
+        // Pre-check: is port already in use? (prevents orphan zombie processes)
+        try {
+            const { request } = await import("node:http");
+            await new Promise((resolve, reject) => {
+                const req = request(`http://127.0.0.1:${port}/api/overview`, { timeout: 2000 }, (res) => {
+                    res.resume();
+                    resolve(); // port is responding = already running
+                });
+                req.on("error", () => reject()); // port free
+                req.on("timeout", () => { req.destroy(); reject(); });
+                req.end();
+            });
+            // If we get here, port is already responding
+            steps.push("Dashboard already running.");
+            // Open browser anyway
+            const url = `http://localhost:${port}`;
+            const platform = process.platform;
+            try {
+                if (platform === "darwin")
+                    execSync(`open "${url}"`, { stdio: "pipe" });
+                else if (platform === "win32")
+                    execSync(`start "" "${url}"`, { stdio: "pipe" });
+                else
+                    execSync(`xdg-open "${url}" 2>/dev/null || sensible-browser "${url}" 2>/dev/null`, { stdio: "pipe" });
+            }
+            catch { /* browser open is best-effort */ }
+            return trackResponse("ctx_insight", {
+                content: [{ type: "text", text: `Dashboard already running at http://localhost:${port}` }],
+            });
+        }
+        catch {
+            // Port is free, proceed with spawn
+        }
         // Start server in background
         const { spawn } = await import("node:child_process");
         const child = spawn("node", [join(cacheDir, "server.mjs")], {
             cwd: cacheDir,
-            env: { ...process.env, PORT: String(port) },
+            env: {
+                ...process.env,
+                PORT: String(port),
+                INSIGHT_SESSION_DIR: getSessionDir(),
+                INSIGHT_CONTENT_DIR: join(dirname(getSessionDir()), "content"),
+            },
             detached: true,
             stdio: "ignore",
         });
+        child.on("error", () => { }); // prevent unhandled error crash
         child.unref();
         // Wait for server to be ready
         await new Promise(r => setTimeout(r, 1500));
+        // Verify server is actually running
+        try {
+            const { request } = await import("node:http");
+            await new Promise((resolve, reject) => {
+                const req = request(`http://127.0.0.1:${port}/api/overview`, { timeout: 3000 }, (res) => {
+                    resolve();
+                    res.resume();
+                });
+                req.on("error", reject);
+                req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+                req.end();
+            });
+        }
+        catch {
+            // Server didn't start — likely port in use
+            return trackResponse("ctx_insight", {
+                content: [{
+                        type: "text",
+                        text: `Port ${port} appears to be in use. Either a previous dashboard is still running, or another service is using this port.\n\nTo fix:\n- Kill the existing process: ${process.platform === "win32" ? `netstat -ano | findstr :${port}` : `lsof -ti:${port} | xargs kill`}\n- Or use a different port: ctx_insight({ port: ${port + 1} })`,
+                    }],
+            });
+        }
         // Open browser (cross-platform)
         const url = `http://localhost:${port}`;
         const platform = process.platform;
@@ -1937,7 +2013,7 @@ server.registerTool("ctx_insight", {
         return trackResponse("ctx_insight", {
             content: [{
                     type: "text",
-                    text: steps.map(s => `- ${s}`).join("\n") + `\n\nOpen: ${url}\nPID: ${child.pid} · Stop: kill ${child.pid}`,
+                    text: steps.map(s => `- ${s}`).join("\n") + `\n\nOpen: ${url}\nPID: ${child.pid} · Stop: ${process.platform === "win32" ? `taskkill /PID ${child.pid} /F` : `kill ${child.pid}`}`,
                 }],
         });
     }

package/build/store.d.ts

@@ -10,6 +10,8 @@
 type SourceMatchMode = "like" | "exact";
 import type { IndexResult, SearchResult, StoreStats } from "./types.js";
 export type { IndexResult, SearchResult, StoreStats } from "./types.js";
+export declare function sanitizeQuery(query: string, mode?: "AND" | "OR"): string;
+export declare function sanitizeTrigramQuery(query: string, mode?: "AND" | "OR"): string;
 /**
  * Remove stale DB files from previous sessions whose processes no longer exist.
  */
@@ -24,6 +26,7 @@ export declare function cleanupStaleContentDBs(contentDir: string, maxAgeDays: n
 export declare class ContentStore {
     #private;
     static readonly OPTIMIZE_EVERY = 50;
+    static readonly FUZZY_CACHE_SIZE = 256;
     constructor(dbPath?: string);
     /** Delete this session's DB files. Call on process exit. */
     cleanup(): void;

package/build/store.js

@@ -33,12 +33,30 @@ const STOPWORDS = new Set([
 // ─────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────
-function sanitizeQuery(query, mode = "AND") {
-    const words = query
+/**
+ * Remove case-insensitive duplicate tokens while preserving the first
+ * occurrence's original casing. FTS5's unicode61 tokenizer lowercases on
+ * both sides, so `"Error" OR "error"` produces no extra recall — just
+ * redundant index lookups. Dedup keeps the compiled query minimal.
+ */
+function dedupeTokens(tokens) {
+    const seen = new Set();
+    const out = [];
+    for (const t of tokens) {
+        const key = t.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(t);
+        }
+    }
+    return out;
+}
+export function sanitizeQuery(query, mode = "AND") {
+    const words = dedupeTokens(query
         .replace(/['"(){}[\]*:^~]/g, " ")
         .split(/\s+/)
         .filter((w) => w.length > 0 &&
-        !["AND", "OR", "NOT", "NEAR"].includes(w.toUpperCase()));
+        !["AND", "OR", "NOT", "NEAR"].includes(w.toUpperCase())));
     if (words.length === 0)
         return '""';
     // Filter stopwords to improve BM25 ranking — common terms like "update",
@@ -48,11 +66,11 @@ function sanitizeQuery(query, mode = "AND") {
     const final = meaningful.length > 0 ? meaningful : words;
     return final.map((w) => `"${w}"`).join(mode === "OR" ? " OR " : " ");
 }
-function sanitizeTrigramQuery(query, mode = "AND") {
+export function sanitizeTrigramQuery(query, mode = "AND") {
     const cleaned = query.replace(/["'(){}[\]*:^~]/g, "").trim();
     if (cleaned.length < 3)
         return "";
-    const words = cleaned.split(/\s+/).filter((w) => w.length >= 3);
+    const words = dedupeTokens(cleaned.split(/\s+/).filter((w) => w.length >= 3));
     if (words.length === 0)
         return "";
     const meaningful = words.filter((w) => !STOPWORDS.has(w.toLowerCase()));
@@ -280,6 +298,13 @@ export class ContentStore {
     // search performance. SQLite's built-in 'optimize' merges b-tree segments.
     #insertCount = 0;
     static OPTIMIZE_EVERY = 50;
+    // Fuzzy correction cache (process-local LRU). fuzzyCorrect() hits the vocab
+    // DB and runs levenshtein against every candidate within length tolerance,
+    // which is CPU-linear in |candidates|. Repeated queries ("erro", "erro" …)
+    // recompute the same answer. The vocabulary table is insert-only, so cache
+    // entries only become stale when new words enter — we clear on actual insert.
+    #fuzzyCache = new Map();
+    static FUZZY_CACHE_SIZE = 256;
     constructor(dbPath) {
         const Database = loadDatabase();
         this.#dbPath =
@@ -733,20 +758,38 @@ export class ContentStore {
         const word = query.toLowerCase().trim();
         if (word.length < 3)
             return null;
+        // Cache hit: promote to tail (Map preserves insertion order → LRU).
+        if (this.#fuzzyCache.has(word)) {
+            const cached = this.#fuzzyCache.get(word) ?? null;
+            this.#fuzzyCache.delete(word);
+            this.#fuzzyCache.set(word, cached);
+            return cached;
+        }
         const maxDist = maxEditDistance(word.length);
         const candidates = this.#stmtFuzzyVocab.all(word.length - maxDist, word.length + maxDist);
         let bestWord = null;
         let bestDist = maxDist + 1;
+        let exactMatch = false;
         for (const { word: candidate } of candidates) {
-            if (candidate === word)
-                return null; // exact match — no correction
+            if (candidate === word) {
+                exactMatch = true;
+                break;
+            }
             const dist = levenshtein(word, candidate);
             if (dist < bestDist) {
                 bestDist = dist;
                 bestWord = candidate;
             }
         }
-        return bestDist <= maxDist ? bestWord : null;
+        const result = exactMatch ? null : bestDist <= maxDist ? bestWord : null;
+        // Evict the oldest entry before insert if we hit the size cap.
+        if (this.#fuzzyCache.size >= _a.FUZZY_CACHE_SIZE) {
+            const oldestKey = this.#fuzzyCache.keys().next().value;
+            if (oldestKey !== undefined)
+                this.#fuzzyCache.delete(oldestKey);
+        }
+        this.#fuzzyCache.set(word, result);
+        return result;
     }
     // ── Reciprocal Rank Fusion (Cormack et al. 2009) ──
     #rrfSearch(query, limit, source, contentType, sourceMatchMode = "like") {
@@ -955,11 +998,18 @@ export class ContentStore {
             .split(/[^\p{L}\p{N}_-]+/u)
             .filter((w) => w.length >= 3 && !STOPWORDS.has(w));
         const unique = [...new Set(words)];
+        let inserted = 0;
         this.#db.transaction(() => {
             for (const word of unique) {
-                this.#stmtInsertVocab.run(word);
+                const info = this.#stmtInsertVocab.run(word);
+                inserted += info.changes;
             }
         })();
+        // Invalidate fuzzy cache when new vocab words actually land. INSERT OR
+        // IGNORE reports changes=0 for duplicates, so re-indexing identical
+        // content does not thrash the cache during iterative workflows.
+        if (inserted > 0)
+            this.#fuzzyCache.clear();
     }
     // ── Chunking ──
     #chunkMarkdown(text, maxChunkBytes = MAX_CHUNK_BYTES) {

package/build/truncate.d.ts

@@ -11,6 +11,9 @@
  * "... [truncated]" is appended. The result is NOT guaranteed to be valid
  * JSON after truncation — it is suitable only for display/logging.
  *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the marker, the marker itself is byte-safely truncated.
+ *
  * @param value    - Any JSON-serializable value.
  * @param maxBytes - Maximum byte length of the returned string.
  * @param indent   - JSON indentation spaces (default 2). Pass 0 for compact.
@@ -30,6 +33,9 @@ export declare function escapeXML(str: string): string;
  * byte-safe slice with an ellipsis appended. Useful for single-value fields
  * (e.g., tool response strings) where head+tail splitting is not needed.
  *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the ellipsis marker, the marker itself is byte-safely truncated.
+ *
  * @param str      - Input string.
  * @param maxBytes - Hard byte cap.
  */