opencode-rag-plugin 1.21.1 → 1.22.0

package/dist/cli/commands/ui.js

@@ -32,7 +32,11 @@ export function registerUiCommand(program) {
             const port = parseInt(options.port ?? String(config.ui?.port ?? 3210), 10);
             const openBrowser = options.open !== false && (config.ui?.openBrowser ?? true);
             const { startWebUi } = await import("../../web/server.js");
-            const server = await startWebUi(storePath, port, cwd, config.embedding.vectorDimension ?? 384, config);
+            const { findConfigFile } = await import("../../core/config.js");
+            const configPath = options.config
+                ? path.resolve(cwd, options.config)
+                : findConfigFile(cwd);
+            const server = await startWebUi(storePath, port, cwd, config.embedding.vectorDimension ?? 384, config, configPath);
             const url = `http://127.0.0.1:${server.port}/?token=${server.token}`;
             logCliInfo(logFilePath, "ui", `\n${c.heading("OpenCodeRAG Web UI")}`);
             logCliInfo(logFilePath, "ui", `  ${c.label("URL:")} ${c.value(url)}`);

package/dist/content/reader.d.ts

@@ -3,7 +3,7 @@
  */
 import type { RagConfig } from "../core/config.js";
 import { type FileManifest } from "../core/manifest.js";
-import { type ExcludeMatcher } from "../core/exclude.js";
+import { type ExcludeMatcher, type IncludedMatcher } from "../core/exclude.js";
 import { DescriptionCache } from "../core/desc-cache.js";
 import { type ImageVisionProvider } from "../chunker/image.js";
 /** Metadata and extracted content for a single workspace file discovered during scanning. */
@@ -28,7 +28,7 @@ interface Logger {
  * Recursively walk a directory tree and collect paths matching the given extension set,
  * respecting exclusion lists and configurable limits for max directories and results.
  */
-export declare function walkFiles(dir: string, extensions: Set<string>, excludeDirs: ExcludeMatcher, excludeFiles?: ExcludeMatcher, rootDir?: string, logger?: Logger, dirCount?: {
+export declare function walkFiles(dir: string, extensions: Set<string>, excludeDirs: ExcludeMatcher, excludeFiles?: ExcludeMatcher, includeDirs?: IncludedMatcher, rootDir?: string, logger?: Logger, dirCount?: {
     value: number;
 }, maxDirs?: number, maxResults?: number): Promise<string[]>;
 /**

package/dist/content/reader.js

@@ -5,7 +5,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import pLimit from "p-limit";
 import { computeFileHash, computeDescriptionConfigHash, normalizeFilePath } from "../core/manifest.js";
-import { createExcludeMatcher } from "../core/exclude.js";
+import { createExcludeMatcher, createIncludeMatcher } from "../core/exclude.js";
 import { DescriptionCache } from "../core/desc-cache.js";
 import { createImageVisionProvider, } from "../chunker/image.js";
 import * as pdfExtractor from "./pdf.js";
@@ -17,13 +17,14 @@ import * as imageExtractor from "./image.js";
  * Recursively walk a directory tree and collect paths matching the given extension set,
  * respecting exclusion lists and configurable limits for max directories and results.
  */
-export async function walkFiles(dir, extensions, excludeDirs, excludeFiles, rootDir = dir, logger, dirCount, maxDirs = 10_000, maxResults = 100_000) {
+export async function walkFiles(dir, extensions, excludeDirs, excludeFiles, includeDirs, rootDir = dir, logger, dirCount, maxDirs = 10_000, maxResults = 100_000) {
     const results = [];
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            if (excludeDirs.excluded(path.relative(rootDir, fullPath)))
+            const rel = path.relative(rootDir, fullPath);
+            if ((includeDirs && !includeDirs.included(rel)) || excludeDirs.excluded(rel))
                 continue;
             if (dirCount) {
                 dirCount.value++;
@@ -39,7 +40,7 @@ export async function walkFiles(dir, extensions, excludeDirs, excludeFiles, root
                 logger?.warn(`Exceeded ${maxResults} matching files — truncating walk at ${fullPath}`);
                 return results;
             }
-            results.push(...(await walkFiles(fullPath, extensions, excludeDirs, excludeFiles, rootDir, logger, dirCount, maxDirs, maxResults)));
+            results.push(...(await walkFiles(fullPath, extensions, excludeDirs, excludeFiles, includeDirs, rootDir, logger, dirCount, maxDirs, maxResults)));
         }
         else if (entry.isFile()) {
             if (results.length >= maxResults) {
@@ -104,6 +105,7 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
     }
     const excludeDirMatcher = createExcludeMatcher(config.indexing.excludeDirs);
     const excludeFileMatcher = createExcludeMatcher(config.indexing.excludeFiles ?? []);
+    const includeDirMatcher = createIncludeMatcher(config.indexing.includeDirs ?? []);
     let files;
     if (filterPaths && filterPaths.length > 0) {
         files = filterPaths
@@ -116,14 +118,14 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             const rel = path.relative(cwd, fp);
             if (rel.startsWith(".."))
                 return false;
-            return !excludeDirMatcher.excluded(rel) && !excludeFileMatcher.excluded(rel);
+            return includeDirMatcher.included(rel) && !excludeDirMatcher.excluded(rel) && !excludeFileMatcher.excluded(rel);
         });
     }
     else {
         logger?.info("Walking directory tree...");
         const walkStart = Date.now();
         const dirCount = { value: 0 };
-        files = await walkFiles(cwd, extensions, excludeDirMatcher, excludeFileMatcher, cwd, logger, dirCount);
+        files = await walkFiles(cwd, extensions, excludeDirMatcher, excludeFileMatcher, includeDirMatcher, cwd, logger, dirCount);
         const walkSec = ((Date.now() - walkStart) / 1000).toFixed(1);
         logger?.info(`Found ${files.length} matching files in ${walkSec}s (${dirCount.value} dirs traversed)`);
     }

package/dist/core/config.d.ts

@@ -265,6 +265,21 @@ export interface RagConfig {
          * patterns are anchored to the workspace root.
          */
         excludeFiles?: string[];
+        /**
+         * Workspace-relative folder paths to **restrict indexing to**.
+         *
+         * When non-empty, only files inside these folders (and their
+         * subfolders) are indexed; files directly in the workspace root are
+         * NOT indexed. `excludeDirs`/`excludeFiles` still apply inside the
+         * included folders. Empty or omitted = whole workspace (default).
+         *
+         * Semantics:
+         * - Entries are **anchored to the workspace root** (unlike
+         *   `excludeDirs`, plain names do NOT match at any depth).
+         * - Supports globs (`docs/**`, `src/{a,b}`); use `/` as separator
+         *   (converted automatically). Matching is case-insensitive.
+         */
+        includeDirs?: string[];
         /** Number of overlapping lines between adjacent chunks. */
         chunkOverlap: number;
         /** Minimum file size in bytes to index (0 = no minimum). */
@@ -415,3 +430,15 @@ export declare function loadConfig(filePath: string, validate?: boolean): RagCon
  * @param dimension - The vector dimension to persist.
  */
 export declare function persistProbedDimension(configPath: string, dimension: number): void;
+/**
+ * Set a value at a dotted path inside the config JSON file, creating
+ * intermediate objects as needed, and write it back with 2-space
+ * indentation. Reads/writes the raw file, so comments or formatting of
+ * unrelated keys are preserved as parsed (the file is re-serialized).
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param path       - Dotted path segments, e.g. `["indexing", "includeDirs"]`.
+ * @param value      - Value to write at the target path.
+ * @returns `true` when the file was updated, `false` on any error.
+ */
+export declare function updateConfigValue(configPath: string, path: string[], value: unknown): boolean;

package/dist/core/config.js

@@ -617,4 +617,37 @@ export function persistProbedDimension(configPath, dimension) {
         // best-effort
     }
 }
+/**
+ * Set a value at a dotted path inside the config JSON file, creating
+ * intermediate objects as needed, and write it back with 2-space
+ * indentation. Reads/writes the raw file, so comments or formatting of
+ * unrelated keys are preserved as parsed (the file is re-serialized).
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param path       - Dotted path segments, e.g. `["indexing", "includeDirs"]`.
+ * @param value      - Value to write at the target path.
+ * @returns `true` when the file was updated, `false` on any error.
+ */
+export function updateConfigValue(configPath, path, value) {
+    try {
+        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];
+            if (!target[key] || typeof target[key] !== "object") {
+                target[key] = {};
+            }
+            target = target[key];
+        }
+        target[path[path.length - 1]] = value;
+        writeFileSync(configPath, JSON.stringify(data, null, 2), "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=config.js.map

package/dist/core/exclude.d.ts

@@ -1,4 +1,18 @@
 export interface ExcludeMatcher {
     excluded(relPath: string): boolean;
 }
+export interface IncludedMatcher {
+    included(relPath: string): boolean;
+}
 export declare function createExcludeMatcher(patterns: string[]): ExcludeMatcher;
+/**
+ * Create a matcher for `indexing.includeDirs`.
+ *
+ * Semantics differ from {@link createExcludeMatcher}: every pattern is
+ * **anchored to the workspace root** — it is matched as a glob against each
+ * ancestor prefix of the path, so `docs` includes `<root>/docs` and all its
+ * contents, but never a nested `docs` elsewhere in the tree. The workspace
+ * root itself (`""`) is always included so a walk can descend into it.
+ * Empty pattern lists include everything.
+ */
+export declare function createIncludeMatcher(patterns: string[]): IncludedMatcher;

package/dist/core/exclude.js

@@ -42,4 +42,41 @@ export function createExcludeMatcher(patterns) {
     }
     return { excluded };
 }
+/**
+ * Create a matcher for `indexing.includeDirs`.
+ *
+ * Semantics differ from {@link createExcludeMatcher}: every pattern is
+ * **anchored to the workspace root** — it is matched as a glob against each
+ * ancestor prefix of the path, so `docs` includes `<root>/docs` and all its
+ * contents, but never a nested `docs` elsewhere in the tree. The workspace
+ * root itself (`""`) is always included so a walk can descend into it.
+ * Empty pattern lists include everything.
+ */
+export function createIncludeMatcher(patterns) {
+    const matchers = [];
+    for (const pattern of patterns) {
+        const pat = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+        if (!pat)
+            continue;
+        matchers.push(new Minimatch(pat, { nocase: true, dot: true }));
+    }
+    if (matchers.length === 0) {
+        return { included: () => true };
+    }
+    function included(relPath) {
+        const normalized = relPath.replace(/\\/g, "/");
+        if (!normalized)
+            return true;
+        let prefix = "";
+        for (const seg of normalized.split("/")) {
+            prefix = prefix ? `${prefix}/${seg}` : seg;
+            for (const mm of matchers) {
+                if (mm.match(prefix) || mm.match(`${prefix}/`))
+                    return true;
+            }
+        }
+        return false;
+    }
+    return { included };
+}
 //# sourceMappingURL=exclude.js.map

package/dist/indexer/watch.d.ts

@@ -28,7 +28,9 @@ export declare function createWatchPassScheduler(runPass: (filterPaths?: string[
 /**
  * Build a predicate that returns `true` for paths that should be ignored by
  * a file watcher (store directory, manifest file, and configured exclude
- * directories).
+ * directories). When `indexing.includeDirs` is non-empty, any path outside
+ * the included folders is ignored as well, so out-of-scope changes never
+ * trigger re-index passes.
  *
  * @param cwd       - Workspace root directory.
  * @param config    - RAG configuration containing `indexing.excludeDirs`.

package/dist/indexer/watch.js

@@ -3,7 +3,7 @@
  */
 import path from "node:path";
 import { manifestPathFor } from "../core/manifest.js";
-import { createExcludeMatcher } from "../core/exclude.js";
+import { createExcludeMatcher, createIncludeMatcher } from "../core/exclude.js";
 /**
  * Create a scheduler that debounces calls to a re-index pass. While a pass is
  * running, subsequent notifications queue a single rerun. Useful for watching
@@ -108,7 +108,9 @@ export function createWatchPassScheduler(runPass, onError, debounceMs = 300) {
 /**
  * Build a predicate that returns `true` for paths that should be ignored by
  * a file watcher (store directory, manifest file, and configured exclude
- * directories).
+ * directories). When `indexing.includeDirs` is non-empty, any path outside
+ * the included folders is ignored as well, so out-of-scope changes never
+ * trigger re-index passes.
  *
  * @param cwd       - Workspace root directory.
  * @param config    - RAG configuration containing `indexing.excludeDirs`.
@@ -120,6 +122,7 @@ export function createWatchIgnore(cwd, config, storePath) {
     const manifestPath = manifestPathFor(storePath);
     const dirMatcher = createExcludeMatcher(config.indexing.excludeDirs);
     const fileMatcher = createExcludeMatcher(config.indexing.excludeFiles ?? []);
+    const includeMatcher = createIncludeMatcher(config.indexing.includeDirs ?? []);
     // Prefix check with a trailing separator so sibling dirs like
     // `<storePath>2` are NOT ignored; case-insensitive on win32 so a
     // differently-cased store path cannot cause self-triggering watch loops.
@@ -136,7 +139,7 @@ export function createWatchIgnore(cwd, config, storePath) {
         const relative = path.relative(cwd, resolved);
         if (!relative || relative.startsWith(".."))
             return false;
-        return dirMatcher.excluded(relative) || fileMatcher.excluded(relative);
+        return !includeMatcher.included(relative) || dirMatcher.excluded(relative) || fileMatcher.excluded(relative);
     };
 }
 //# sourceMappingURL=watch.js.map

package/dist/tui.js

@@ -8,7 +8,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadRuntimeOverrides, saveRuntimeOverride } from "./core/runtime-overrides.js";
 import { PROVIDER_DEFAULTS } from "./core/provider-defaults.js";
-import { loadConfig } from "./core/config.js";
+import { loadConfig, updateConfigValue } from "./core/config.js";
 import { setPendingRagInjection } from "./core/rag-injection-flag.js";
 /** Cached plugin version string from package.json. */
 let _version;
@@ -275,26 +275,6 @@ function resolveProviderBaseUrl(provider) {
  * Write a single config value at a dotted path into the opencode-rag.json file.
  * Creates intermediate objects as needed.
  */
-function saveConfigValue(configPath, path, value) {
-    try {
-        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];
-            if (!target[key] || typeof target[key] !== "object") {
-                target[key] = {};
-            }
-            target = target[key];
-        }
-        target[path[path.length - 1]] = value;
-        writeFileSync(configPath, JSON.stringify(data, null, 2), "utf-8");
-    }
-    catch {
-    }
-}
 /**
  * Mirror the watcher status file that the server plugin maintains, so the
  * sidebar reflects a watcher toggle from the settings dialog immediately:
@@ -334,12 +314,12 @@ function saveModelSelection(storePath, configPath, selectionValue, path, provide
     const ragProvider = providerIdToRagProvider(providerId);
     const baseUrl = provider ? resolveProviderBaseUrl(provider) : "";
     saveRuntimeOverride(storePath, [section, "provider"], ragProvider);
-    saveConfigValue(configPath, [section, "provider"], ragProvider);
+    updateConfigValue(configPath, [section, "provider"], ragProvider);
     saveRuntimeOverride(storePath, [section, "model"], modelId);
-    saveConfigValue(configPath, [section, "model"], modelId);
+    updateConfigValue(configPath, [section, "model"], modelId);
     if (baseUrl) {
         saveRuntimeOverride(storePath, [section, "baseUrl"], baseUrl);
-        saveConfigValue(configPath, [section, "baseUrl"], baseUrl);
+        updateConfigValue(configPath, [section, "baseUrl"], baseUrl);
     }
     const apiKey = provider?.options?.apiKey ?? "";
     if (apiKey) {
@@ -704,7 +684,7 @@ async function openSettingsDialog(api) {
                 else if (entry.type === "boolean") {
                     const newVal = !entry.currentValue;
                     saveRuntimeOverride(storePath, entry.path, newVal);
-                    saveConfigValue(configPath, entry.path, newVal);
+                    updateConfigValue(configPath, entry.path, newVal);
                     api.ui.toast({
                         variant: "success",
                         title: "Settings",
@@ -730,7 +710,7 @@ async function openSettingsDialog(api) {
                             const num = parseFloat(input);
                             if (!isNaN(num)) {
                                 saveRuntimeOverride(storePath, entry.path, num);
-                                saveConfigValue(configPath, entry.path, num);
+                                updateConfigValue(configPath, entry.path, num);
                                 api.ui.toast({
                                     variant: "success",
                                     title: "Settings",
@@ -763,7 +743,7 @@ async function openSettingsDialog(api) {
                                     return;
                                 }
                                 saveRuntimeOverride(storePath, entry.path, parsed);
-                                saveConfigValue(configPath, entry.path, parsed);
+                                updateConfigValue(configPath, entry.path, parsed);
                                 api.ui.toast({
                                     variant: "success",
                                     title: "Settings",
@@ -792,7 +772,7 @@ async function openSettingsDialog(api) {
                         value: String(entry.currentValue),
                         onConfirm: (input) => {
                             saveRuntimeOverride(storePath, entry.path, input);
-                            saveConfigValue(configPath, entry.path, input);
+                            updateConfigValue(configPath, entry.path, input);
                             api.ui.toast({
                                 variant: "success",
                                 title: "Settings",
@@ -828,7 +808,7 @@ async function openSettingsDialog(api) {
                             }
                             else if (input) {
                                 saveRuntimeOverride(storePath, entry.path, input);
-                                saveConfigValue(configPath, entry.path, input);
+                                updateConfigValue(configPath, entry.path, input);
                                 entry.currentValue = input;
                             }
                             api.onSettingsChanged?.();

package/dist/vectorstore/lancedb.d.ts

@@ -7,10 +7,28 @@ export type StoreWarn = (message: string) => void;
  * store holds one per built index, while a store whose index commits fail
  * accumulates one per attempt (and eventually degrades / corrupts).
  *
+ * Empty directories are the husks of pruned versions (Lance removes the files
+ * but leaves the directory behind) and are harmless — they must not count
+ * toward the corruption threshold.
+ *
  * @param tablePath - Filesystem path of the table directory (e.g. `.../chunks.lance`).
+ * @param options - `withFiles: true` counts only directories that still contain index files.
  * @returns The number of index-version directories, or 0 when unavailable.
  */
-export declare function countIndexVersionDirs(tablePath: string): number;
+export declare function countIndexVersionDirs(tablePath: string, options?: {
+    withFiles?: boolean;
+}): number;
+/**
+ * Remove stale empty index-version directories (husks of versions whose files
+ * Lance already pruned). Empty directories are never referenced by the index,
+ * so removing them is safe; only husks older than `MIN_HUSK_AGE_MS` are swept
+ * so a concurrent createIndex from another process can never lose its
+ * freshly-created (and momentarily empty) version directory.
+ *
+ * @param tablePath - Filesystem path of the table directory (e.g. `.../chunks.lance`).
+ * @returns The number of removed directories.
+ */
+export declare function sweepEmptyIndexVersionDirs(tablePath: string): number;
 /**
  * L2-normalize a vector to unit length. Cosine models require unit vectors
  * for the dot product to equal cosine similarity.

package/dist/vectorstore/lancedb.js

@@ -30,18 +30,75 @@ const MAX_STALE_INDEX_VERSIONS = 40;
  * store holds one per built index, while a store whose index commits fail
  * accumulates one per attempt (and eventually degrades / corrupts).
  *
+ * Empty directories are the husks of pruned versions (Lance removes the files
+ * but leaves the directory behind) and are harmless — they must not count
+ * toward the corruption threshold.
+ *
  * @param tablePath - Filesystem path of the table directory (e.g. `.../chunks.lance`).
+ * @param options - `withFiles: true` counts only directories that still contain index files.
  * @returns The number of index-version directories, or 0 when unavailable.
  */
-export function countIndexVersionDirs(tablePath) {
+export function countIndexVersionDirs(tablePath, options) {
     try {
         const entries = fsSync.readdirSync(path.join(tablePath, "_indices"), { withFileTypes: true });
-        return entries.filter((e) => e.isDirectory()).length;
+        const dirs = entries.filter((e) => e.isDirectory());
+        if (!options?.withFiles)
+            return dirs.length;
+        let count = 0;
+        for (const dir of dirs) {
+            try {
+                if (fsSync.readdirSync(path.join(tablePath, "_indices", dir.name)).length > 0)
+                    count++;
+            }
+            catch {
+                // unreadable dir — count it conservatively
+                count++;
+            }
+        }
+        return count;
     }
     catch {
         return 0;
     }
 }
+/**
+ * Remove stale empty index-version directories (husks of versions whose files
+ * Lance already pruned). Empty directories are never referenced by the index,
+ * so removing them is safe; only husks older than `MIN_HUSK_AGE_MS` are swept
+ * so a concurrent createIndex from another process can never lose its
+ * freshly-created (and momentarily empty) version directory.
+ *
+ * @param tablePath - Filesystem path of the table directory (e.g. `.../chunks.lance`).
+ * @returns The number of removed directories.
+ */
+export function sweepEmptyIndexVersionDirs(tablePath) {
+    const MIN_HUSK_AGE_MS = 10 * 60 * 1000;
+    let removed = 0;
+    try {
+        const indicesDir = path.join(tablePath, "_indices");
+        for (const name of fsSync.readdirSync(indicesDir)) {
+            const full = path.join(indicesDir, name);
+            try {
+                const stat = fsSync.statSync(full);
+                if (!stat.isDirectory())
+                    continue;
+                if (Date.now() - stat.mtimeMs < MIN_HUSK_AGE_MS)
+                    continue;
+                if (fsSync.readdirSync(full).length > 0)
+                    continue;
+                fsSync.rmdirSync(full);
+                removed++;
+            }
+            catch {
+                // best-effort — skip unreadable/racing entries
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return removed;
+}
 /**
  * L2-normalize a vector to unit length. Cosine models require unit vectors
  * for the dot product to equal cosine similarity.
@@ -873,15 +930,16 @@ export class LanceDbStore {
         };
         try {
             // Guard against a store that never converges: each failed createIndex
-            // leaves a new index-version directory behind. If many stale versions
-            // accumulated, building yet another index only entrenches the problem.
-            // The store must be rebuilt instead (see doc/troubleshooting.md).
-            const staleVersions = this.dbPath.startsWith("memory://")
+            // leaves a new index-version directory behind. Empty directories are
+            // the husks of already-pruned versions and are harmless — only
+            // versions that still carry index files count (see countIndexVersionDirs).
+            const activeVersions = this.dbPath.startsWith("memory://")
                 ? 0
-                : countIndexVersionDirs(path.join(this.dbPath, TABLE_NAME + ".lance"));
-            if (staleVersions > MAX_STALE_INDEX_VERSIONS) {
-                report(`[lancedb] ${staleVersions} stale index versions detected in ${this.dbPath} — ` +
-                    `skipping index rebuild (the store is corrupted). Delete the rag_db directory and re-index.`);
+                : countIndexVersionDirs(path.join(this.dbPath, TABLE_NAME + ".lance"), { withFiles: true });
+            if (activeVersions > MAX_STALE_INDEX_VERSIONS) {
+                report(`[lancedb] ${activeVersions} active index versions detected in ${this.dbPath} — ` +
+                    `index rebuild skipped to avoid retrain churn. The store cannot converge; ` +
+                    `delete the rag_db directory and re-index.`);
                 // Resolve the memo so no further attempts run this process.
                 return;
             }
@@ -906,6 +964,16 @@ export class LanceDbStore {
                         // race a background index-creation from another process.
                         waitTimeoutSeconds: 120,
                     });
+                    // Verify the index actually registered. On a store whose index
+                    // commits never register, createIndex can return successfully
+                    // while leaving the table without a visible index — the failure
+                    // mode that caused constant retraining and "partition N is empty,
+                    // skipping" warning spam. Detect it and stop retraining.
+                    const verify = await table.indexStats(idxName).catch(() => undefined);
+                    if (!verify || verify.distanceType !== "cosine") {
+                        throw new Error(`index build did not register (store cannot converge) — ` +
+                            `delete the rag_db directory and re-index`);
+                    }
                     this.indexRepairFailures = 0;
                     return;
                 }
@@ -957,6 +1025,17 @@ export class LanceDbStore {
                     const threshold = new Date(Date.now() - 60 * 60 * 1000);
                     await table.optimize({ cleanupOlderThan: threshold, deleteUnverified: false });
                 }
+                // Remove stale empty index-version directories (husks Lance leaves
+                // behind after pruning a version's files). Keeps the directory count
+                // from growing unboundedly and prevents false positives in the
+                // index-repair stale-version guard.
+                if (!this.dbPath.startsWith("memory://")) {
+                    const swept = sweepEmptyIndexVersionDirs(path.join(this.dbPath, TABLE_NAME + ".lance"));
+                    if (swept > 0) {
+                        const message = `[lancedb] swept ${swept} stale index-version directories`;
+                        (options?.logger ?? console.warn)(message);
+                    }
+                }
                 // Build the ANN vector index — without it every vectorSearch() is a
                 // brute-force O(N) flat scan (slow at 50k+ chunks). Skips early when
                 // an index with the correct cosine metric already exists, and can be

package/dist/web/api.d.ts

@@ -4,7 +4,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { LanceDbStore } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
-import type { RagConfig } from "../core/config.js";
+import { type RagConfig } from "../core/config.js";
 import { type EmbeddingProvider } from "../core/interfaces.js";
 /** Internal shape for a JSON API response: an HTTP status code and a serialisable body. */
 interface ApiResponse {
@@ -26,9 +26,12 @@ interface ApiResponse {
  * @param storePath    - Filesystem path to the store directory (used by eval endpoints).
  * @param cwd          - Optional workspace root for resolving file paths.
  * @param cfg          - Active RAG configuration (used by quirk endpoints).
+ * @param getEmbedder  - Lazily-created embedder for /api/retrieve and reindex passes.
+ * @param token        - Per-run auth token required on every request.
+ * @param configPath   - Path to the opencode-rag.json config file, used by PUT /api/config.
  * @returns An async handler that returns `true` when a route matched or `false` otherwise.
  */
-export declare function createApiHandler(store: LanceDbStore, keywordIndex: KeywordIndex, storePath: string, cwd?: string, cfg?: RagConfig, getEmbedder?: () => Promise<EmbeddingProvider>, token?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+export declare function createApiHandler(store: LanceDbStore, keywordIndex: KeywordIndex, storePath: string, cwd?: string, cfg?: RagConfig, getEmbedder?: () => Promise<EmbeddingProvider>, token?: string, configPath?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
 /**
  * Perform token-usage analysis for a single evaluation session.
  *