opencode-rag-plugin 1.19.4 → 1.19.8

package/dist/quirks/quirk-store.js

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { retrieve } from "../retriever/retriever.js";
@@ -11,15 +11,33 @@ function jsonlPath(storePath) {
 function isMemoryStore(storePath) {
     return storePath.startsWith("memory:");
 }
-/** In-memory backup for memory:// stores. */
-const memQuirks = new Map();
+/** In-memory backup for memory:// stores, keyed by store path. */
+const memQuirksByStore = new Map();
+function memQuirksFor(storePath) {
+    let store = memQuirksByStore.get(storePath);
+    if (!store) {
+        store = new Map();
+        memQuirksByStore.set(storePath, store);
+    }
+    return store;
+}
 function readJsonl(filePath) {
     if (!existsSync(filePath))
         return [];
     const raw = readFileSync(filePath, "utf-8").trim();
     if (!raw)
         return [];
-    return raw.split("\n").map((l) => JSON.parse(l));
+    const quirks = [];
+    for (const line of raw.split("\n")) {
+        try {
+            quirks.push(JSON.parse(line));
+        }
+        catch {
+            // Skip corrupt lines — a single bad line must never break
+            // every quirk operation (readJsonl feeds get/update/remove/list).
+        }
+    }
+    return quirks;
 }
 function appendJsonl(filePath, q) {
     const dir = path.dirname(filePath);
@@ -33,7 +51,24 @@ function rewriteJsonl(filePath, quirks) {
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
-    writeFileSync(filePath, quirks.map((q) => JSON.stringify(q)).join("\n") + "\n", "utf-8");
+    // Atomic write: tmp file + rename, so a crash or concurrent process
+    // can never leave a truncated/empty quirks.jsonl behind.
+    const tmpPath = `${filePath}.tmp`;
+    writeFileSync(tmpPath, quirks.map((q) => JSON.stringify(q)).join("\n") + "\n", "utf-8");
+    try {
+        renameSync(tmpPath, filePath);
+    }
+    catch {
+        // Windows: rename can fail with EPERM when another process holds the file;
+        // fall back to a direct write (best-effort) rather than losing data.
+        writeFileSync(filePath, quirks.map((q) => JSON.stringify(q)).join("\n") + "\n", "utf-8");
+        try {
+            renameSync(tmpPath, `${filePath}.bak`);
+        }
+        catch {
+            // ignore
+        }
+    }
 }
 function nowISO() {
     return new Date().toISOString();
@@ -62,7 +97,7 @@ export async function getQuirk(deps, id) {
         }
         return undefined;
     }
-    return memQuirks.get(id);
+    return memQuirksFor(deps.storePath).get(id);
 }
 /**
  * Update an existing quirk by ID. Fields in `patch` override the stored values.
@@ -100,8 +135,9 @@ export async function updateQuirk(deps, id, patch) {
         sourceRef,
     };
     const filePath = QUIRK_FILE_PREFIX + id;
-    await deps.store.deleteByFilePath(filePath);
-    deps.keywordIndex.removeByFilePath(filePath);
+    // Embed FIRST — if embedding fails, the old index entries are untouched
+    // (previously the delete happened before the embed, permanently removing
+    // the quirk from search while the JSONL still listed it).
     const prefix = deps.cfg.embedding.documentPrefix ?? "";
     const chunkContent = prefix + content;
     const embeddings = await deps.embedder.embed([chunkContent], "document");
@@ -109,6 +145,8 @@ export async function updateQuirk(deps, id, patch) {
     if (!embedding || embedding.length === 0) {
         throw new Error("Embedding returned empty vector for quirk content");
     }
+    await deps.store.deleteByFilePath(filePath);
+    deps.keywordIndex.removeByFilePath(filePath);
     const chunk = {
         id,
         content,
@@ -134,7 +172,7 @@ export async function updateQuirk(deps, id, patch) {
         rewriteJsonl(jp, all);
     }
     else {
-        memQuirks.set(id, updated);
+        memQuirksFor(deps.storePath).set(id, updated);
     }
     return updated;
 }
@@ -186,7 +224,7 @@ export async function addQuirk(deps, input) {
         appendJsonl(jsonlPath(deps.storePath), quirk);
     }
     else {
-        memQuirks.set(id, quirk);
+        memQuirksFor(deps.storePath).set(id, quirk);
     }
     return quirk;
 }
@@ -205,7 +243,7 @@ export async function removeQuirk(deps, id) {
         rewriteJsonl(jp, all);
     }
     else {
-        memQuirks.delete(id);
+        memQuirksFor(deps.storePath).delete(id);
     }
 }
 /** List all quirks sorted by lastObserved descending. */
@@ -238,7 +276,7 @@ export async function listQuirks(deps) {
         result.sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
         return result;
     }
-    const all = [...memQuirks.values()];
+    const all = [...memQuirksFor(deps.storePath).values()];
     all.sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
     return all;
 }
@@ -246,10 +284,11 @@ export async function listQuirks(deps) {
 export async function recallQuirks(deps, query, options) {
     const topK = options?.topK ?? 10;
     const minConfidence = deps.cfg.memory?.minConfidence ?? 0.5;
+    // NOTE: do NOT put quirkType into `filter.languages` — quirk chunks store
+    // the type in metadata.quirkType, not metadata.language ("quirk").
+    // A languages filter would exclude every quirk chunk and return zero hits.
+    // Type filtering happens in the post-filter below instead.
     const filter = { kinds: ["quirk"] };
-    if (options?.quirkType) {
-        filter.languages = [options.quirkType];
-    }
     const recallMinScore = options?.minScore ?? deps.cfg.memory?.recallMinScore ?? 0.72;
     const raw = await retrieve(query, deps.embedder, deps.store, {
         topK: topK * 3,
@@ -304,7 +343,7 @@ export async function lintQuirks(deps) {
         for (let j = i + 1; j < quirks.length; j++) {
             const sim = lexicalSimilarity(quirks[i].content, quirks[j].content);
             if (sim > 0.85) {
-                issues.push(`Near-duplicate (${(sim * 100).toFixed(0)}% similar): "${quirks[i].content}" ↔ "${quirks[j].content}"`);
+                issues.push(`Near-duplicate (${(sim * 100).toFixed(0)}% similar): "${quirks[i].content}" ↔ "${quirks[j].content}"`);
             }
         }
     }
@@ -322,7 +361,7 @@ export function lexicalSimilarity(a, b) {
  * Count of meaningful word tokens shared between two texts (Jaccard numerator).
  *
  * Tokens are whitespace/punctuation-split, lowercased, and filtered to those
- * with length ≥ `minTokenLen` (default 3 — skips short filler like "the").
+ * with length ≥ `minTokenLen` (default 3 — skips short filler like "the").
  *
  * Used by the quirk auto-inject gate: candidate quirks that share no tokens
  * with the user's *current* message (i.e. they matched only against the prior

package/dist/retriever/context-optimizer.js

@@ -26,10 +26,20 @@ function toOptimized(r) {
 }
 /**
  * Compute Jaccard similarity between two strings based on their token sets.
+ * Accepts a per-call token cache so repeated comparisons (the dedup loop is
+ * O(n²) over same-file pairs) don't re-tokenize the same content every time.
  */
-function jaccardSimilarity(a, b) {
-    const tokensA = new Set(tokenize(a));
-    const tokensB = new Set(tokenize(b));
+function jaccardSimilarity(a, b, tokenCache) {
+    let tokensA = tokenCache.get(a);
+    if (!tokensA) {
+        tokensA = new Set(tokenize(a));
+        tokenCache.set(a, tokensA);
+    }
+    let tokensB = tokenCache.get(b);
+    if (!tokensB) {
+        tokensB = new Set(tokenize(b));
+        tokenCache.set(b, tokensB);
+    }
     if (tokensA.size === 0 && tokensB.size === 0)
         return 1;
     let intersection = 0;
@@ -99,12 +109,16 @@ function dedupeSimilar(results, threshold) {
     if (results.length <= 1)
         return results;
     const kept = [...results];
+    // Token cache shared across all pair comparisons of this group — the
+    // dedup loop is O(n²) over pairs and was re-tokenizing full chunk
+    // contents on every comparison.
+    const tokenCache = new Map();
     let changed = true;
     while (changed) {
         changed = false;
         for (let i = 0; i < kept.length; i++) {
             for (let j = i + 1; j < kept.length; j++) {
-                const sim = jaccardSimilarity(kept[i].chunk.content, kept[j].chunk.content);
+                const sim = jaccardSimilarity(kept[i].chunk.content, kept[j].chunk.content, tokenCache);
                 if (sim > threshold) {
                     const [keepIdx, removeIdx] = kept[i].score >= kept[j].score ? [i, j] : [j, i];
                     const removedId = kept[removeIdx].chunk.id;

package/dist/retriever/keyword-index.d.ts

@@ -18,6 +18,8 @@ export declare class KeywordIndex {
     private invertedIndex;
     private chunkMap;
     private readonly storePath?;
+    /** filePath (normalized) → chunk IDs, for O(chunks-in-file) removal. */
+    private fileToIds;
     constructor(storePath?: string);
     addChunks(chunks: Chunk[]): void;
     getMatchedTerms(query: string, chunkId: string): string[];

package/dist/retriever/keyword-index.js

@@ -1,3 +1,4 @@
+import { normalizeFilePath } from "../core/manifest.js";
 const INDEX_VERSION = 2;
 /** Suffix-stripping stemmer. Only stems words >= 6 characters to reduce false positives. */
 function stem(word) {
@@ -71,6 +72,8 @@ export class KeywordIndex {
     invertedIndex = new Map();
     chunkMap = new Map();
     storePath;
+    /** filePath (normalized) → chunk IDs, for O(chunks-in-file) removal. */
+    fileToIds = new Map();
     constructor(storePath) {
         this.storePath = storePath;
     }
@@ -78,6 +81,13 @@ export class KeywordIndex {
         for (const chunk of chunks) {
             const id = chunk.id;
             this.chunkMap.set(id, chunk);
+            const fileKey = normalizeFilePath(chunk.metadata.filePath);
+            let ids = this.fileToIds.get(fileKey);
+            if (!ids) {
+                ids = new Set();
+                this.fileToIds.set(fileKey, ids);
+            }
+            ids.add(id);
             const tokens = tokenize(chunk.content);
             for (const token of tokens) {
                 let docs = this.invertedIndex.get(token);
@@ -101,10 +111,21 @@ export class KeywordIndex {
         return matched;
     }
     removeByFilePath(filePath) {
-        const idsToRemove = [];
-        for (const [id, chunk] of this.chunkMap) {
-            if (chunk.metadata.filePath === filePath) {
-                idsToRemove.push(id);
+        const fileKey = normalizeFilePath(filePath);
+        // Fast path: per-file id index. Falls back to a full chunkMap scan when
+        // the path is not tracked (entries loaded from an older persisted index).
+        let idsToRemove;
+        const tracked = this.fileToIds.get(fileKey);
+        if (tracked) {
+            idsToRemove = [...tracked];
+            this.fileToIds.delete(fileKey);
+        }
+        else {
+            idsToRemove = [];
+            for (const [id, chunk] of this.chunkMap) {
+                if (normalizeFilePath(chunk.metadata.filePath) === fileKey) {
+                    idsToRemove.push(id);
+                }
             }
         }
         for (const id of idsToRemove) {
@@ -155,10 +176,12 @@ export class KeywordIndex {
     close() {
         this.invertedIndex.clear();
         this.chunkMap.clear();
+        this.fileToIds.clear();
     }
     clear() {
         this.invertedIndex.clear();
         this.chunkMap.clear();
+        this.fileToIds.clear();
     }
     count() {
         return this.chunkMap.size;
@@ -241,6 +264,17 @@ export class KeywordIndex {
                 },
             });
         }
+        // Rebuild the per-file id index from the loaded chunk map so removals
+        // work even for entries persisted by older versions.
+        for (const [id, chunk] of index.chunkMap) {
+            const fileKey = normalizeFilePath(chunk.metadata.filePath);
+            let ids = index.fileToIds.get(fileKey);
+            if (!ids) {
+                ids = new Set();
+                index.fileToIds.set(fileKey, ids);
+            }
+            ids.add(id);
+        }
         return index;
     }
     static async clearFile(storePath) {

package/dist/retriever/retriever.js

@@ -96,7 +96,12 @@ export async function retrieve(query, embedder, store, options = {}) {
             .slice(0, topK);
         return combinedResults;
     }
-    catch {
+    catch (err) {
+        // Never silently mask retrieval failures as "no results" — an embedder
+        // outage or store bug must be visible, not indistinguishable from an
+        // empty index.
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[retriever] retrieve() failed (returning []): ${message}`);
         return [];
     }
 }

package/dist/tui.js

@@ -3,7 +3,7 @@
  * settings dialog for editing config values, and model selection picker.
  */
 import { createElement, insert, setProp } from "@opentui/solid";
-import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadRuntimeOverrides, saveRuntimeOverride } from "./core/runtime-overrides.js";
@@ -277,7 +277,10 @@ function resolveProviderBaseUrl(provider) {
  */
 function saveConfigValue(configPath, path, value) {
     try {
-        const data = JSON.parse(readFileSync(configPath, "utf-8"));
+        let raw = readFileSync(configPath, "utf-8");
+        if (raw.charCodeAt(0) === 0xfeff)
+            raw = raw.slice(1);
+        const data = JSON.parse(raw);
         let target = data;
         for (let i = 0; i < path.length - 1; i++) {
             const key = path[i];
@@ -292,6 +295,26 @@ function saveConfigValue(configPath, path, value) {
     catch {
     }
 }
+/**
+ * Mirror the watcher status file that the server plugin maintains, so the
+ * sidebar reflects a watcher toggle from the settings dialog immediately:
+ * - enabled  → write the same initial status the background indexer writes on startup
+ * - disabled → remove the file (same cleanup the plugin does when auto-index is off)
+ */
+function syncWatcherStatusFile(storePath, enabled) {
+    const statusPath = join(storePath, "watcher-status.json");
+    try {
+        if (enabled) {
+            writeFileSync(statusPath, JSON.stringify({ running: false }, null, 2), "utf-8");
+        }
+        else if (existsSync(statusPath)) {
+            unlinkSync(statusPath);
+        }
+    }
+    catch {
+        // best-effort mirror; the server plugin reconciles on its next load
+    }
+}
 /**
  * Save a model selection to both runtime overrides and the config file.
  * Resolves the RAG provider name and API base URL automatically.
@@ -320,8 +343,9 @@ function saveModelSelection(storePath, configPath, selectionValue, path, provide
     }
     const apiKey = provider?.options?.apiKey ?? "";
     if (apiKey) {
+        // Persist the key only in the store-dir overrides, never in the workspace
+        // config file — `opencode-rag.json` is routinely committed to git.
         saveRuntimeOverride(storePath, [section, "apiKey"], apiKey);
-        saveConfigValue(configPath, [section, "apiKey"], apiKey);
     }
     return selectionValue;
 }
@@ -689,7 +713,12 @@ async function openSettingsDialog(api) {
                     if (entry.path[0] === "indexing" || entry.path[0] === "chunking") {
                         api.ui.toast({ variant: "warning", title: "Settings", message: "Chunking changed. Re-index required." });
                     }
+                    if (entry.path.join(".") === "openCode.autoIndex.enabled") {
+                        syncWatcherStatusFile(storePath, newVal);
+                        api.ui.toast({ variant: "warning", title: "Settings", message: "Watcher changes take effect after an OpenCode restart" });
+                    }
                     entry.currentValue = newVal;
+                    api.onSettingsChanged?.();
                     showSettingMenu(cat);
                 }
                 else if (entry.type === "number") {
@@ -711,6 +740,7 @@ async function openSettingsDialog(api) {
                                     api.ui.toast({ variant: "warning", title: "Settings", message: "Chunking changed. Re-index required." });
                                 }
                                 entry.currentValue = num;
+                                api.onSettingsChanged?.();
                             }
                             showSettingMenu(cat);
                         },
@@ -743,6 +773,7 @@ async function openSettingsDialog(api) {
                                     api.ui.toast({ variant: "warning", title: "Settings", message: "Chunking changed. Re-index required." });
                                 }
                                 entry.currentValue = parsed;
+                                api.onSettingsChanged?.();
                             }
                             catch {
                                 api.ui.toast({ variant: "error", title: "Settings", message: "Invalid JSON" });
@@ -768,6 +799,7 @@ async function openSettingsDialog(api) {
                                 message: `${entry.label}: ${input}`,
                             });
                             entry.currentValue = input;
+                            api.onSettingsChanged?.();
                             showSettingMenu(cat);
                         },
                         onCancel: () => {
@@ -799,6 +831,7 @@ async function openSettingsDialog(api) {
                                 saveConfigValue(configPath, entry.path, input);
                                 entry.currentValue = input;
                             }
+                            api.onSettingsChanged?.();
                             showSettingMenu(cat);
                         },
                         onCancel: () => showSettingMenu(cat),
@@ -821,6 +854,7 @@ async function openSettingsDialog(api) {
                             message: "Embedding changed. Re-index may be required. Restart OpenCode for changes.",
                         });
                     }
+                    api.onSettingsChanged?.();
                 }
                 showSettingMenu(cat);
             },
@@ -840,7 +874,7 @@ const plugin = {
         const version = meta.version ?? getVersion();
         let cachedStatus = DEFAULT_STATUS;
         let lastRefresh = 0;
-        const REFRESH_INTERVAL_MS = Number(process.env.OPENCODE_RAG_TUI_REFRESH_MS) || 3600000;
+        const REFRESH_INTERVAL_MS = Number(process.env.OPENCODE_RAG_TUI_REFRESH_MS) || 30000;
         // Load tui config for keybinding display
         let tuiConfig;
         const worktree = api.state.path.worktree;
@@ -948,6 +982,9 @@ const plugin = {
                             openSettingsDialog({
                                 ui: api.ui,
                                 state: api.state,
+                                onSettingsChanged: () => {
+                                    refreshStatus();
+                                },
                             });
                             return undefined;
                         },

package/dist/vectorstore/lancedb.d.ts

@@ -32,6 +32,16 @@ export declare function isTransientConflictError(err: unknown): boolean;
  * @param realPath - Path to the current store (destination, will be replaced).
  */
 export declare function swapStoreDirectories(tempPath: string, realPath: string): Promise<void>;
+/**
+ * A single file's chunk payload for a bulk store write.
+ * `dedup: true` removes prior-revision rows for the same file path that are
+ * not part of this write; `dedup: false` appends only (safe when writing into
+ * a freshly-created store where no rows can collide).
+ */
+export interface BulkChunkWrite {
+    chunks: Chunk[];
+    dedup: boolean;
+}
 /**
  * A LanceDB-backed vector store with persistent on-disk storage, vector search,
  * and chunk metadata queries. Supports automatic corruption recovery by falling
@@ -44,6 +54,14 @@ export declare class LanceDbStore implements VectorStore {
     private table;
     private tableInit;
     private writeLock;
+    /**
+     * Memoized once-per-process index-metric repair. Stores built by versions
+     * before the cosine search switch carry an IVF index trained with the
+     * default L2 metric, which makes every cosine query log
+     * "Requested metric Cosine is incompatible with index metric L2" and fall
+     * back to brute-force. This repairs that stale index on first search.
+     */
+    private indexRepairPromise;
     /**
      * Execute an async function under an exclusive write lock.
      *
@@ -81,13 +99,36 @@ export declare class LanceDbStore implements VectorStore {
     private ensureColumnsNullable;
     /**
      * Store chunks in the LanceDB table. New rows are inserted first, then
-     * any old rows at the same (filePath, startLine) with different IDs are
-     * removed. This ensures no data is lost if the process aborts between
-     * insert and cleanup. Automatically attempts repair on corruption errors.
+     * old rows for the same file that are not part of this write are removed
+     * in a single delete per file. This ensures no data is lost if the process
+     * aborts between insert and cleanup. Automatically attempts repair on
+     * corruption errors.
+     *
+     * When `options.dedup` is `false` the cleanup step is skipped entirely —
+     * a pure append. Use this when writing into a store that provably has no
+     * prior rows for these files (e.g. a freshly-created rebuild store).
+     *
      * @param chunks - The chunks to add.
+     * @param options - Optional write options (`dedup`, default `true`).
      */
-    addChunks(chunks: Chunk[]): Promise<void>;
+    addChunks(chunks: Chunk[], options?: {
+        dedup?: boolean;
+    }): Promise<void>;
+    /**
+     * Store chunks for many files in a single transaction: one `table.add`
+     * across all items, then one `table.delete` per item that needs dedup.
+     * This collapses what used to be a per-file add + per-startLine deletes
+     * (K+2 LanceDB versions per file) into ~1 + M versions per batch.
+     *
+     * @param items - Per-file chunk payloads with their dedup flags.
+     */
+    addChunksBulk(items: BulkChunkWrite[]): Promise<void>;
+    /** Map a chunk to its internal row shape, or null if it has no embedding. */
+    private chunkToRow;
+    /** Group new rows by file path for dedup deletes. */
+    private rowsByFilePath;
     private addChunksInternal;
+    private addChunksBulkInternal;
     /**
      * Perform ANN (approximate nearest neighbor) search using LanceDB's native vector index.
      * Returns results scored as cosine similarity (0-1). Falls back to repair on corruption.
@@ -120,6 +161,24 @@ export declare class LanceDbStore implements VectorStore {
      * @returns An array of chunk summaries.
      */
     getChunks(offset: number, limit: number): Promise<ChunkSummary[]>;
+    /**
+     * Retrieve a paginated list of chunks without embeddings, with optional
+     * language and file-path filters pushed into the SQL WHERE clause.
+     *
+     * @param offset - Number of rows to skip (for pagination).
+     * @param limit - Maximum number of rows to return.
+     * @param lang - Optional exact language filter.
+     * @param filePrefix - Optional filePath prefix filter.
+     * @returns The page of chunks plus the total count of matching rows.
+     */
+    getChunksFiltered(offset: number, limit: number, lang?: string, filePrefix?: string): Promise<{
+        chunks: ChunkSummary[];
+        total: number;
+    }>;
+    /** Look up a single chunk by its ID. Returns undefined when not found. */
+    getChunkById(id: string): Promise<ChunkSummary | undefined>;
+    /** Fetch chunks by their IDs (for the compare view). Bounded to 100 ids. */
+    getChunksByIds(ids: string[]): Promise<ChunkSummary[]>;
     /**
      * Fetch chunks with their embedding vectors included (for embedding projection).
      * @param limit - Maximum number of rows to return.
@@ -150,12 +209,43 @@ export declare class LanceDbStore implements VectorStore {
      * @returns The chunk count, or 0 if the table does not exist or times out.
      */
     count(): Promise<number>;
+    /**
+     * Ensure the ANN index on the `embedding` column uses the cosine metric,
+     * matching the `distanceType` requested by searchInternal.
+     *
+     * Older stores built the IVF index with the ivfFlat default (L2), so every
+     * cosine query hit "Requested metric Cosine is incompatible with index
+     * metric L2" and silently fell back to brute-force O(N) scans. This lazily
+     * replaces such an index with a cosine one — once per process.
+     *
+     * Callers must hold the write lock (searchInternal wraps the call in
+     * withWriteLock; optimize runs under it already).
+     */
+    private ensureCosineIndex;
+    /**
+     * Perform a single index-metric repair pass. Skips stores that have no
+     * index and fewer than 1000 rows (brute-force is optimal there). Uses a
+     * single `createIndex` with `replace: true` — a dropIndex + createIndex
+     * sequence races in LanceDB ("Retryable commit conflict") and leaves the
+     * stale index in place. On failure the memo is cleared so the next
+     * search/optimize retries.
+     */
+    private repairIndexMetricOnce;
     /**
      * Compact fragments and prune old version manifests to prevent the
-     * version-manifest accumulation that causes countRows() to hang.
-     * Should be called at the end of a successful index pass.
+     * version-manifest accumulation that causes countRows() to hang and the
+     * store phase to slow down as the index grows. Should be called at the
+     * end of a successful index pass, and periodically during long passes.
+     *
+     * @param options - `aggressive: true` prunes every version but the current
+     *   one with `deleteUnverified`. Only safe for a private store that no other
+     *   process reads (e.g. a temporary rebuild store). For the shared store,
+     *   versions newer than 1 hour are retained so in-flight queries (Web UI,
+     *   background auto-index) can finish before their data files are reclaimed.
      */
-    optimize(): Promise<void>;
+    optimize(options?: {
+        aggressive?: boolean;
+    }): Promise<void>;
     /**
      * Return all unique file paths currently stored in the index.
      * @returns An array of normalized file paths.
@@ -169,7 +259,13 @@ export declare class LanceDbStore implements VectorStore {
      * @param newPath - Optional new filesystem path for the LanceDB database.
      */
     reopen(newPath?: string): Promise<void>;
-    /** Close the database connection and release resources. */
+    /**
+     * Close the database connection and release resources.
+     *
+     * The native LanceDB `close()` can hang indefinitely on Windows, so the
+     * whole close is raced against a timeout — callers (CLI commands, plugin
+     * reload, web server) must never block forever on shutdown.
+     */
     close(): Promise<void>;
     /**
      * Back up the chunks.lance directory before a destructive operation.