opencode-rag-plugin 1.19.4 → 1.19.8

package/dist/cli/commands/init.js

@@ -11,12 +11,13 @@
  */
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
-import { loadConfig } from "../../core/config.js";
+import { loadConfig, findConfigFile } from "../../core/config.js";
 import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
 import { destroyAllPooledConnections } from "../../embedder/http.js";
 import { c } from "../format.js";
 import { getPackageMetadata, readJsonObject, writeJsonFile } from "../helpers.js";
 import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJson, generateSkillFile, generateWorkspacePluginFile, generateWorkspaceTuiPluginFile, installPluginFromGlobal, mergeAgentsMdContent, mergeGitignoreContent, } from "./init-helpers.js";
+import { detectOllamaBackend } from "./backend-detect.js";
 /**
  * Register the `init` command on the given Commander program.
  *
@@ -29,7 +30,14 @@ import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJs
 export function registerInitCommand(program) {
     program
         .command("init")
-        .description("Configure the current workspace for OpenCodeRAG")
+        .description("Configure this workspace (files + auto-tuned opencode-rag.json)")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time workspace setup: creates .opencode/, the RAG skill file, AGENTS.md\n" +
+        "    guidance, and opencode-rag.json with embedding batches auto-detected for the\n" +
+        "    Ollama backend (GPU vs CPU).\n" +
+        "  - Re-running in an existing workspace: re-syncs plugin/skill files and keeps the\n" +
+        "    existing opencode-rag.json (overwriting requires interactive confirmation).\n" +
+        "\nWorkspace-level step — run AFTER 'opencode-rag setup' on this machine, then 'opencode-rag index'.\n")
         .option("-f, --force", "overwrite existing files")
         .option("--skip-install", "skip installing workspace-local plugin dependencies")
         .option("--skip-health-check", "skip provider connectivity and model availability check")
@@ -37,7 +45,10 @@ export function registerInitCommand(program) {
         try {
             const cwd = process.cwd();
             const packageMetadata = getPackageMetadata();
-            const configPath = path.join(cwd, "opencode-rag.json");
+            // Use findConfigFile so an existing config in .opencode/rag.json (or
+            // .opencode/opencode-rag.json) is respected instead of being shadowed
+            // by a new root-level opencode-rag.json.
+            const configPath = findConfigFile(cwd) ?? path.join(cwd, "opencode-rag.json");
             const opencodeDir = path.join(cwd, ".opencode");
             const gitignorePath = path.join(opencodeDir, ".gitignore");
             const opencodeConfigPath = path.join(opencodeDir, "opencode.json");
@@ -186,8 +197,27 @@ export function registerInitCommand(program) {
                 console.log(`  ${c.exists("Exists:")}   .opencode/package.json`);
             }
             const configExists = existsSync(configPath);
+            // Detect the Ollama backend (CPU vs GPU) lazily — only when we are
+            // actually about to write a config — and tune embedding batches for it.
+            let detectedTuning;
+            const configContent = async () => {
+                if (!detectedTuning) {
+                    try {
+                        const info = await detectOllamaBackend();
+                        detectedTuning = info.tuning;
+                        const icon = info.backend === "gpu" ? c.success("GPU:") :
+                            info.backend === "cpu" ? c.warn("CPU:") :
+                                c.dim("Backend:");
+                        console.log(`  ${icon} ${info.message}`);
+                    }
+                    catch {
+                        detectedTuning = undefined;
+                    }
+                }
+                return generateDefaultConfigJson(detectedTuning);
+            };
             if (!configExists) {
-                writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                writeFileSync(configPath, await configContent(), "utf-8");
                 console.log(`  ${c.created("Created:")} opencode-rag.json`);
             }
             else {
@@ -205,7 +235,7 @@ export function registerInitCommand(program) {
                 if (overwrite) {
                     copyFileSync(configPath, `${configPath}.bak`);
                     console.log(`  ${c.dim("Backup:")}        opencode-rag.json.bak`);
-                    writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                    writeFileSync(configPath, await configContent(), "utf-8");
                     console.log(`  ${c.updated("Updated:")}  opencode-rag.json`);
                 }
                 else {
@@ -253,27 +283,34 @@ export function registerInitCommand(program) {
                         return { model: r.model, baseUrl: ragConfig.embedding.baseUrl, proxy: ragConfig.embedding.proxy };
                     });
                     console.log(`\n  ${c.warn("Models not found:")} ${pullEntries.map((e) => e.model).join(", ")}`);
-                    const readline = await import("node:readline");
-                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-                    const answer = await new Promise((resolve) => {
-                        rl.question(`  Pull ${pullEntries.length === 1 ? "this model" : "these models"} now? (y/n) `, resolve);
-                    });
-                    rl.close();
-                    if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
-                        console.log();
-                        try {
-                            await pullOllamaModels(pullEntries, (model, line) => {
-                                console.log(`  ${c.value(model)}: ${line}`);
-                            });
-                            console.log(`\n  ${c.success("Models pulled successfully.")}`);
-                        }
-                        catch (err) {
-                            console.error(`\n  ${c.error("Pull failed:")} ${err.message}`);
-                            console.log(`  ${c.dim("Pull manually with: ollama pull <model>")}`);
-                        }
+                    // Non-TTY guard: rl.question would block forever with a still-open
+                    // stdin pipe (e.g. `echo y | opencode-rag init`, CI runners).
+                    if (!process.stdin.isTTY) {
+                        console.log(`  ${c.dim("Non-interactive shell — skipping. Pull manually with: ollama pull <model>")}`);
                     }
                     else {
-                        console.log(`  ${c.dim("Skipped. Pull manually with: ollama pull <model>")}`);
+                        const readline = await import("node:readline");
+                        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                        const answer = await new Promise((resolve) => {
+                            rl.question(`  Pull ${pullEntries.length === 1 ? "this model" : "these models"} now? (y/n) `, resolve);
+                        });
+                        rl.close();
+                        if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+                            console.log();
+                            try {
+                                await pullOllamaModels(pullEntries, (model, line) => {
+                                    console.log(`  ${c.value(model)}: ${line}`);
+                                });
+                                console.log(`\n  ${c.success("Models pulled successfully.")}`);
+                            }
+                            catch (err) {
+                                console.error(`\n  ${c.error("Pull failed:")} ${err.message}`);
+                                console.log(`  ${c.dim("Pull manually with: ollama pull <model>")}`);
+                            }
+                        }
+                        else {
+                            console.log(`  ${c.dim("Skipped. Pull manually with: ollama pull <model>")}`);
+                        }
                     }
                 }
                 const hasErrors = results.some((r) => r.status === "error");

package/dist/cli/commands/quirk.js

@@ -16,6 +16,7 @@ export function registerQuirkCommand(program) {
         .option("-t, --type <type>", "quirk type: gotcha, preference, decision, environment-constraint")
         .option("--tag <tags...>", "tags for filtering")
         .option("--source-ref <path>", "source file path reference")
+        .option("-c, --config <path>", "path to config file")
         .action(async (content, options) => {
         try {
             const ctx = await resolveCliContext(options, resolveLogPath());
@@ -49,6 +50,11 @@ export function registerQuirkCommand(program) {
         .option("-c, --config <path>", "path to config file")
         .action(async (id, options) => {
         try {
+            const confidence = options.confidence;
+            if (confidence !== undefined && (Number.isNaN(confidence) || confidence < 0 || confidence > 1)) {
+                logCliError(resolveLogPath(), "quirk update", "Failed to update quirk: --confidence must be a number between 0 and 1");
+                process.exit(1);
+            }
             const ctx = await resolveCliContext(options, resolveLogPath());
             const { config, embedder, store, keywordIndex } = ctx;
             const tags = options.tag;
@@ -56,7 +62,7 @@ export function registerQuirkCommand(program) {
                 content: options.content,
                 quirkType: options.type,
                 tags: tags ? (Array.isArray(tags) ? tags : [tags]) : undefined,
-                confidence: options.confidence,
+                confidence,
                 sourceRef: options.sourceRef,
             });
             logCliInfo(ctx.logFilePath, "quirk update", `\n${c.success("Quirk updated:")}`);
@@ -148,7 +154,7 @@ export function registerQuirkCommand(program) {
             const { config, embedder, store, keywordIndex } = ctx;
             const results = await recallQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, content, { topK: 5 });
             if (results.length > 0) {
-                logCliInfo(ctx.logFilePath, "quirk test", c.success("\n✓ Quirk has been appended:\n"));
+                logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ Similar quirk(s) already exist — quirk has NOT been appended:\n"));
                 for (const r of results) {
                     const badge = r.chunk.metadata.quirkType ? `[${r.chunk.metadata.quirkType}] ` : "";
                     const tags = r.chunk.metadata.tags?.length ? ` (${r.chunk.metadata.tags.join(", ")})` : "";
@@ -159,7 +165,7 @@ export function registerQuirkCommand(program) {
                 }
             }
             else {
-                logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ No matching quirk found — quirk has not been appended\n"));
+                logCliInfo(ctx.logFilePath, "quirk test", c.success("\n✓ No matching quirk found — safe to append\n"));
             }
             await cleanupContext(ctx);
         }

package/dist/cli/commands/setup.js

@@ -36,7 +36,13 @@ function checkOpenCodeRunning() {
 export function registerSetupCommand(program) {
     program
         .command("setup")
-        .description("Set up the OpenCodeRAG runtime (~/.opencode/) for OpenCode plugin discovery")
+        .description("Install/update the OpenCodeRAG runtime once per machine")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time install: run once per machine to install the plugin runtime\n" +
+        "    into ~/.opencode/ so OpenCode can discover the RAG plugin.\n" +
+        "  - Updating: re-sync the runtime to the published plugin version.\n" +
+        "  - Troubleshooting: use --check to inspect the runtime, or --force to reinstall.\n" +
+        "\nMachine-level step — run BEFORE 'opencode-rag init' (init configures each workspace).\n")
         .option("--uninstall", "remove the runtime and cleanup")
         .option("-f, --force", "force re-setup even if up-to-date")
         .option("--check", "check whether the runtime is correctly installed")
@@ -81,9 +87,12 @@ export function registerSetupCommand(program) {
         if (options.uninstall) {
             console.log(`\n${c.heading("Removing OpenCodeRAG runtime...")}\n`);
             removeIfExists(runtimePluginDir);
-            removeIfExists(runtimeSdkDir);
+            // Only remove the @opencode-ai/plugin SDK package — the scope dir may
+            // be shared with other OpenCode plugins/tools.
+            removeIfExists(runtimeSdkPluginDir);
             removeIfExists(versionFile);
-            console.log(`  ${c.updated("Removed:")} ${c.file(runtimeDir)}`);
+            console.log(`  ${c.updated("Removed:")} ${c.file(runtimePluginDir)}`);
+            console.log(`  ${c.updated("Removed:")} ${c.file(runtimeSdkPluginDir)}`);
             console.log(`\n  ${c.success("Done.")} Run ${c.file("npm uninstall -g opencode-rag-plugin")} to remove the global package.\n`);
             return;
         }

package/dist/cli/commands/status.js

@@ -147,14 +147,23 @@ export function registerStatusCommand(program) {
                     logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.warn("version unknown — run `opencode-rag setup`")}`);
                 }
             }
-            // Async GitHub update check (fire-and-forget, 5s timeout).
-            // Runs unless autoUpdate is explicitly disabled.
+            // GitHub update check. Runs unless autoUpdate is explicitly disabled.
+            // Awaited (raced against 3s) so the result can actually print —
+            // process.exit(0) below would previously kill the promise before it
+            // resolved, making the Update: line dead code.
             if (config.autoUpdate?.enabled) {
-                checkForUpdate(pkg.version).then((info) => {
-                    if (info.updateAvailable) {
+                try {
+                    const info = await Promise.race([
+                        checkForUpdate(pkg.version),
+                        new Promise((resolve) => setTimeout(() => resolve(null), 3000)),
+                    ]);
+                    if (info && info.updateAvailable) {
                         process.stdout.write(`  ${c.label("Update:")}            ${c.warn(`v${info.latestVersion} available — run \`opencode-rag update\` to install`)}\n`);
                     }
-                }).catch(() => { });
+                }
+                catch {
+                    /* ignore network errors */
+                }
             }
             // Force exit — avoid LanceDB close() hanging on Windows native bindings.
             // Status is read-only so there's no state to lose.

package/dist/cli/commands/ui.js

@@ -5,7 +5,7 @@
  * `ui` command — starts a local web UI for browsing the vector database.
  */
 import path from "node:path";
-import { c, resolveCliContext, logCliError, logCliInfo } from "../format.js";
+import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo } from "../format.js";
 /**
  * Register the `ui` command on the given Commander program.
  *
@@ -33,9 +33,10 @@ export function registerUiCommand(program) {
             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 url = `http://127.0.0.1:${server.port}`;
+            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)}`);
+            logCliInfo(logFilePath, "ui", `  ${c.dim("The token in the URL authenticates this session — keep it private.")}`);
             logCliInfo(logFilePath, "ui", `  ${c.dim("Press Ctrl+C to stop")}\n`);
             if (openBrowser) {
                 const { spawn } = await import("node:child_process");
@@ -52,14 +53,27 @@ export function registerUiCommand(program) {
                     console.error(c.dim(`Could not open browser automatically. Open ${url} manually.`));
                 }
             }
-            process.on("SIGINT", async () => {
-                await server.close();
-                process.exit(0);
-            });
-            process.on("SIGTERM", async () => {
-                await server.close();
+            let shuttingDown = false;
+            const shutdown = async () => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                try {
+                    await server.close();
+                }
+                catch {
+                    // best-effort — the process is exiting anyway
+                }
+                try {
+                    await cleanupContext(ctx);
+                }
+                catch {
+                    // best-effort cleanup
+                }
                 process.exit(0);
-            });
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
         }
         catch (err) {
             const message = err.message || String(err);

package/dist/cli/commands/update.js

@@ -24,11 +24,10 @@ export function registerUpdateCommand(program) {
         console.log(`\n${c.heading("OpenCodeRAG Update")}\n`);
         console.log(`  ${c.label("Current version:")} ${c.value(currentVersion)}`);
         console.log(`  ${c.label("Checking...")}     `);
-        let info;
-        try {
-            info = await checkForUpdate(currentVersion);
-        }
-        catch {
+        // checkForUpdate never throws (all failures collapse to "no update"),
+        // so the try/catch below is defensive only.
+        const info = await checkForUpdate(currentVersion).catch(() => null);
+        if (!info) {
             console.log(`\n  ${c.warn("Could not reach the update server. Check your network and try again.")}\n`);
             process.exit(1);
             return;

package/dist/cli/format.d.ts

@@ -60,7 +60,7 @@ export declare const c: {
  * @param message - Human-readable error message.
  * @param error - Optional error object for structured logging.
  */
-export declare function logCliError(_logFilePath: string, _scope: string, message: string, _error: unknown): void;
+export declare function logCliError(logFilePath: string, scope: string, message: string, error?: unknown): void;
 /**
  * Log an informational message to stdout and optionally append to the debug log.
  *
@@ -68,7 +68,7 @@ export declare function logCliError(_logFilePath: string, _scope: string, messag
  * @param scope - Logical scope (e.g. "index", "query") for log filtering.
  * @param message - Human-readable info message.
  */
-export declare function logCliInfo(_logFilePath: string, _scope: string, message: string): void;
+export declare function logCliInfo(logFilePath: string, scope: string, message: string): void;
 /**
  * Resolve a full `RagContext` from CLI options and log the config details.
  *
@@ -82,6 +82,9 @@ export declare function resolveCliContext(opt: CliOptions, logFilePath: string,
 /**
  * Gracefully close a `RagContext` — closes the vector store and destroys pooled HTTP connections.
  *
+ * The store close is raced against a timeout because LanceDB's native `close()`
+ * can hang indefinitely on Windows; callers must never be blocked forever.
+ *
  * @param ctx - The `RagContext` to clean up.
  */
 export declare function cleanupContext(ctx: RagContext): Promise<void>;

package/dist/cli/format.js

@@ -8,6 +8,7 @@
 import pc from "picocolors";
 import { resolveRagContext } from "../core/bootstrap.js";
 import { destroyAllPooledConnections } from "../embedder/http.js";
+import { appendDebugLog } from "../core/fileLogger.js";
 // ── Color palette ───────────────────────────────────────────────
 /**
  * Semantic color helpers for consistent CLI output styling.
@@ -61,9 +62,9 @@ export const c = {
  * @param message - Human-readable error message.
  * @param error - Optional error object for structured logging.
  */
-export function logCliError(_logFilePath, _scope, message, _error) {
+export function logCliError(logFilePath, scope, message, error) {
     console.error(c.error(message));
-    //appendDebugLog(logFilePath, { scope, message, error });
+    appendDebugLog(logFilePath, { scope, message, error });
 }
 /**
  * Log an informational message to stdout and optionally append to the debug log.
@@ -72,9 +73,9 @@ export function logCliError(_logFilePath, _scope, message, _error) {
  * @param scope - Logical scope (e.g. "index", "query") for log filtering.
  * @param message - Human-readable info message.
  */
-export function logCliInfo(_logFilePath, _scope, message) {
+export function logCliInfo(logFilePath, scope, message) {
     console.log(message);
-    //appendDebugLog(logFilePath, { scope, message });
+    appendDebugLog(logFilePath, { scope, message });
 }
 // ── Context resolution ──────────────────────────────────────────
 /**
@@ -109,10 +110,18 @@ function logConfigDetails(logFilePath, config) {
 /**
  * Gracefully close a `RagContext` — closes the vector store and destroys pooled HTTP connections.
  *
+ * The store close is raced against a timeout because LanceDB's native `close()`
+ * can hang indefinitely on Windows; callers must never be blocked forever.
+ *
  * @param ctx - The `RagContext` to clean up.
  */
 export async function cleanupContext(ctx) {
-    await ctx.store.close();
+    await Promise.race([
+        ctx.store.close(),
+        new Promise((resolve) => {
+            setTimeout(resolve, 5000).unref();
+        }),
+    ]);
     destroyAllPooledConnections();
 }
 // ── Formatting helpers ──────────────────────────────────────────

package/dist/content/image.js

@@ -95,25 +95,47 @@ export async function resizeImage(buffer, filePath, maxDimension) {
             const { pixels, width, height, channels } = decodeBmp(buffer);
             const ch = channels;
             if (width <= maxDimension && height <= maxDimension) {
-                return sharp(pixels, { raw: { width, height, channels: ch } })
-                    .jpeg({ quality: 80 })
-                    .toBuffer();
+                const pipeline = sharp(pixels, { raw: { width, height, channels: ch } })
+                    .jpeg({ quality: 80 });
+                try {
+                    return await pipeline.toBuffer();
+                }
+                finally {
+                    pipeline.destroy();
+                }
             }
-            return sharp(pixels, { raw: { width, height, channels: ch } })
+            const pipeline = sharp(pixels, { raw: { width, height, channels: ch } })
                 .resize({ width: maxDimension, fit: "inside", withoutEnlargement: true })
-                .jpeg({ quality: 80 })
-                .toBuffer();
+                .jpeg({ quality: 80 });
+            try {
+                return await pipeline.toBuffer();
+            }
+            finally {
+                pipeline.destroy();
+            }
         }
-        const meta = await sharp(buffer).metadata();
+        const metaPipeline = sharp(buffer);
+        const meta = await metaPipeline.metadata().finally(() => metaPipeline.destroy());
         const w = meta.width ?? 0;
         const h = meta.height ?? 0;
         if (w <= maxDimension && h <= maxDimension) {
-            return sharp(buffer).jpeg({ quality: 80 }).toBuffer();
+            const pipeline = sharp(buffer).jpeg({ quality: 80 });
+            try {
+                return await pipeline.toBuffer();
+            }
+            finally {
+                pipeline.destroy();
+            }
         }
-        return sharp(buffer)
+        const pipeline = sharp(buffer)
             .resize({ width: maxDimension, fit: "inside", withoutEnlargement: true })
-            .jpeg({ quality: 80 })
-            .toBuffer();
+            .jpeg({ quality: 80 });
+        try {
+            return await pipeline.toBuffer();
+        }
+        finally {
+            pipeline.destroy();
+        }
     }
     catch (err) {
         throw new Error(`Image resize failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/content/reader.js

@@ -145,13 +145,57 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
                 const stat = await fs.stat(filePath);
                 const entry = manifest.files[normalizedPath];
                 if (entry.mtime === stat.mtimeMs && entry.size === stat.size) {
+                    // Fast path — BUT only when the description config is unchanged:
+                    // when descHash differs, the worker needs the full content to
+                    // re-chunk and re-describe the file. Returning empty content here
+                    // would make chunkFile() yield zero chunks and the pipeline would
+                    // DELETE the file from the index instead of re-describing it.
+                    // Mirrors pipeline.ts: `descriptionProvider ? computeDescriptionConfigHash(config) : undefined`.
+                    const currentDescHash = config.description?.enabled
+                        ? (computeDescriptionConfigHash(config) ?? "")
+                        : "";
+                    if (!currentDescHash || entry.descHash === currentDescHash) {
+                        completed++;
+                        return {
+                            filePath,
+                            normalizedPath,
+                            content: "",
+                            hash: entry.hash,
+                            isEmpty: false,
+                            isTooSmall: false,
+                            extractionStatus: "ok",
+                            mtime: stat.mtimeMs,
+                            size: stat.size,
+                        };
+                    }
+                }
+            }
+            catch {
+                /* stat failed, fall through to full read */
+            }
+        }
+        const isImage = imageVisionProvider !== null && imageExtractor.isImageFile(filePath);
+        const ext = path.extname(filePath).toLowerCase();
+        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(ext) ||
+            docxExtractor.DOCX_EXTENSIONS.has(ext) ||
+            docExtractor.DOC_EXTENSIONS.has(ext) ||
+            excelExtractor.EXCEL_EXTENSIONS.has(ext) ||
+            isImage;
+        // Reject oversized binaries BEFORE buffering them — a 2 GB PDF was
+        // previously read fully into memory only to be rejected by the
+        // 100 MB check inside the PDF extractor.
+        if (isBinary && pdfExtractor.PDF_EXTENSIONS.has(ext)) {
+            try {
+                const stat = await fs.stat(filePath);
+                if (stat.size > 100 * 1024 * 1024) {
+                    logger?.warn(`  ${filePath} (PDF exceeds 100 MB — skipping)`);
                     completed++;
                     return {
                         filePath,
                         normalizedPath,
                         content: "",
-                        hash: entry.hash,
-                        isEmpty: false,
+                        hash: computeFileHash(""),
+                        isEmpty: true,
                         isTooSmall: false,
                         extractionStatus: "ok",
                         mtime: stat.mtimeMs,
@@ -160,17 +204,10 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
                 }
             }
             catch {
-                /* stat failed, fall through to full read */
+                /* stat failed, fall through to read */
             }
         }
-        const isImage = imageVisionProvider !== null && imageExtractor.isImageFile(filePath);
-        const ext = path.extname(filePath).toLowerCase();
-        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(ext) ||
-            docxExtractor.DOCX_EXTENSIONS.has(ext) ||
-            docExtractor.DOC_EXTENSIONS.has(ext) ||
-            excelExtractor.EXCEL_EXTENSIONS.has(ext) ||
-            isImage;
-        logger?.info(`Reading: ${filePath}`);
+        logger?.debug(`Reading: ${filePath}`);
         const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
         // For images, check the persistent description cache before calling the vision provider
         if (isImage && descCache && imageDescConfigHash) {
@@ -206,15 +243,39 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             logger?.info(`  Describing image: ${filePath}`);
         }
         const result = await dispatchExtraction(filePath, buffer, imageVisionProvider, imagePrompt, imageResizeMaxDimension);
-        // Cache the image description for future runs
+        // Cache the image description for future runs. Saves are throttled —
+        // a full cache rewrite per image was O(n²) I/O for image-heavy workspaces.
+        // The pipeline saves the cache again at the end of a pass.
         if (isImage && result.ok && descCache && imageDescConfigHash) {
             const imageBytesHash = computeFileHash(buffer.toString("base64"));
             const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
             descCache.set(cacheKey, result.content);
-            await descCache.save();
+            if (completed % 25 === 0) {
+                await descCache.save();
+            }
         }
         if (!result.ok) {
             logger?.warn(`  ${filePath} (extraction failed: ${result.error})`);
+            // A transient extraction failure (file lock, antivirus, timeout) must
+            // NOT delete a previously-good index entry. Report the file as
+            // unchanged with the OLD hash so the worker keeps the old chunks;
+            // the entry stays and the file is re-attempted on a later pass.
+            const previous = manifest?.files[normalizedPath];
+            if (previous) {
+                completed++;
+                return {
+                    filePath,
+                    normalizedPath,
+                    content: "",
+                    hash: previous.hash,
+                    isEmpty: false,
+                    isTooSmall: false,
+                    extractionStatus: "failed",
+                    extractionError: result.error,
+                    mtime: previous.mtime,
+                    size: previous.size,
+                };
+            }
         }
         const content = result.content;
         const byteLength = Buffer.byteLength(content, "utf-8");

package/dist/core/bootstrap.js

@@ -3,7 +3,7 @@
  * creates embedder, vector store, keyword index, and description provider.
  */
 import path from "node:path";
-import { loadConfig, findConfigFile, DEFAULT_CONFIG } from "./config.js";
+import { loadConfig, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
 import { resolveApiKey } from "./resolve-api-key.js";
 import { loadChunkersFromConfig } from "../chunker/loader.js";
 import { createEmbedder } from "../embedder/factory.js";
@@ -21,6 +21,10 @@ async function probeDimension(embedder) {
     catch {
         // fallback to 384
     }
+    // A wrong dimension is only discovered later as cryptic LanceDB errors —
+    // surface the fallback loudly so misconfigured providers are easy to spot.
+    console.warn("[bootstrap] Could not probe embedding dimension — falling back to 384. " +
+        "If indexing later fails with dimension errors, set embedding.vectorDimension explicitly.");
     return 384;
 }
 /** Load the keyword index from disk, or create a new empty one if loading fails. */
@@ -50,9 +54,12 @@ export async function resolveRagContext(opts = {}) {
         await loadChunkersFromConfig(cfg, path.dirname(configPath));
     }
     else {
-        cfg = { ...DEFAULT_CONFIG };
+        // Deep-clone so resolveApiKey (below) cannot mutate the shared
+        // DEFAULT_CONFIG singleton.
+        cfg = structuredClone(DEFAULT_CONFIG);
+        resolveApiKey(cfg, workDir);
     }
-    const logFilePath = path.resolve(workDir, cfg.logging?.logFilePath ?? ".opencode/opencode-rag.log");
+    const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
     const embedder = createEmbedder(cfg);
     const dimension = opts.skipProbe ? 384 : await probeDimension(embedder);
     const storePath = path.resolve(workDir, cfg.vectorStore.path);