codesearch-mcp 0.1.0-alpha → 0.2.1-alpha

package/dist/src/services/SearcherService.js

@@ -40,11 +40,14 @@ const readline = __importStar(require("readline"));
 const child_process_1 = require("child_process");
 const file_utils_1 = require("../file-utils");
 const MonorepoAwareDiscoveryService_1 = require("./MonorepoAwareDiscoveryService");
+const legacy_ollama_index_1 = require("./legacy-ollama-index");
+const symbol_name_1 = require("../symbol-name");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
     warn() { },
     error() { },
+    metric() { },
 };
 const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
 const GREP_MAX_RESULTS = 200;
@@ -136,15 +139,28 @@ class SearcherService {
     /**
      * Refuse when the configured embedding model disagrees with the one that built
      * the index — embedding a query into a foreign vector space returns noise. A
-     * missing `index_meta` (un-migrated DB / not yet indexed) does not block.
+     * missing `index_meta` row with an empty (or altogether absent) `code_chunk`
+     * does not block — but a *populated* `code_chunk` with no `index_meta` row is a
+     * pre-`index_meta` install, treated as the legacy `ollama`/`bge-m3` index (same
+     * interpretation as the `rag-index` legacy-Ollama guard), read-only — this check
+     * never writes `index_meta`.
      */
     async assertIndexMatches() {
         const meta = await this.db.readIndexMeta();
-        if (!meta)
+        if (meta) {
+            this.compareIndexed(meta.provider, meta.model, meta.dimensions);
             return;
+        }
+        // No row — a missing code_chunk table counts as empty; any other DB error
+        // while counting propagates rather than being read as "not indexed".
+        if (await (0, legacy_ollama_index_1.hasIndexedChunks)(this.db)) {
+            this.compareIndexed(legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.provider, legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.model, null);
+        }
+    }
+    compareIndexed(indexedProvider, indexedModel, indexedDimensions) {
         const { provider, model } = this.config.embedding;
-        if (meta.provider !== provider || meta.model !== model) {
-            throw new Error(`Index was built with ${meta.provider}/${meta.model} but the config selects ${provider}/${model}. ` +
+        if (indexedProvider !== provider || indexedModel !== model) {
+            throw new Error(`Index was built with ${indexedProvider}/${indexedModel} but the config selects ${provider}/${model}. ` +
                 `Run \`rag-index --reindex\` to rebuild the index for the new model.`);
         }
         // Same model but a changed dimension (e.g. a Matryoshka `embedding.dimensions`
@@ -152,9 +168,12 @@ class SearcherService {
         // would throw an opaque "different vector dimensions" error mid-query. Catch
         // it here with the friendly hint. `embedder.dimensions` is 0 when the width is
         // only knowable by probing, in which case we skip (can't compare cheaply).
+        // `indexedDimensions` is null for the legacy-inferred identity, whose provider
+        // can never match a configured provider (ollama is no longer selectable), so
+        // this branch is unreached in that case.
         const dim = this.embedder.dimensions;
-        if (dim > 0 && dim !== meta.dimensions) {
-            throw new Error(`Index was built at ${meta.dimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
+        if (indexedDimensions != null && dim > 0 && dim !== indexedDimensions) {
+            throw new Error(`Index was built at ${indexedDimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
                 `Run \`rag-index --reindex\` to rebuild the index at the new dimension.`);
         }
     }
@@ -173,48 +192,112 @@ class SearcherService {
         const t0 = Date.now();
         await this.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
-        const fetchLimit = this.embedder.rerank
-            ? Math.min(limit * this.config.reranker.overfetch, 200)
+        const reranking = !!this.embedder.rerank;
+        // Candidate floor: decouple the pool size from `limit` so a small `limit`
+        // (e.g. the default 5) still gives the reranker a large-enough menu. Without
+        // a reranker the extra candidates are never reordered, so keep `limit`.
+        const fetchLimit = reranking
+            ? Math.min(Math.max(limit * this.config.reranker.overfetch, this.config.reranker.candidateFloor), 200)
             : limit;
+        // With metrics on, fetch one extra row to detect a saturated pool (more
+        // under-threshold candidates existed than the window took). The extra row is
+        // dropped before reranking so it never affects results.
+        const metricsOn = this.config.logging.searchMetrics;
+        const dbLimit = metricsOn ? fetchLimit + 1 : fetchLimit;
         this.logger.debug('SearcherService: searchChunks', {
             query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
+        const tEmbed0 = Date.now();
         const embedding = await this.embedder.embed(query, 'query');
-        const params = [`[${embedding}]`, effectiveThreshold, fetchLimit];
+        const embedMs = Date.now() - tEmbed0;
+        const params = [`[${embedding}]`, effectiveThreshold, dbLimit];
         let projectFilter = '';
         if (project) {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
-        const candidates = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
+        const tDb0 = Date.now();
+        const fetched = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
               ROUND((embedding <=> $1)::numeric, 4)::float8 AS score
        FROM code_chunk
        WHERE embedding <=> $1 < $2
        ${projectFilter}
        ORDER BY embedding <=> $1
        LIMIT $3`, params);
+        const dbMs = Date.now() - tDb0;
+        // Saturated iff the extra probe row came back — more candidates were under
+        // the threshold than `fetchLimit`. Trim the probe row before reranking.
+        const poolSaturated = metricsOn && fetched.length > fetchLimit;
+        const candidates = fetched.slice(0, fetchLimit);
         this.logger.debug('SearcherService: searchChunks candidates', {
             count: candidates.length,
             scores: candidates.map(r => r.score),
             files: candidates.map(r => r.filePath),
             ms: Date.now() - t0,
         });
-        if (!this.embedder.rerank || candidates.length === 0)
-            return candidates;
-        try {
-            const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
-            this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
-            // Cap at `limit`: some rerank servers ignore `top_n` and echo back every
-            // candidate, so slicing here keeps the result count within the request.
-            return indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
+        let results;
+        let rerankMs = 0;
+        if (!reranking || candidates.length === 0) {
+            results = candidates.slice(0, limit);
+        }
+        else {
+            const tRerank0 = Date.now();
+            try {
+                const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
+                rerankMs = Date.now() - tRerank0;
+                this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
+                // Cap at `limit`: some rerank servers ignore `top_n` and echo back every
+                // candidate, so slicing here keeps the result count within the request.
+                results = indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
+            }
+            catch (err) {
+                rerankMs = Date.now() - tRerank0;
+                this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
+                    reason: err instanceof Error ? err.message : String(err),
+                    ms: Date.now() - t0,
+                });
+                results = candidates.slice(0, limit);
+            }
         }
-        catch (err) {
-            this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
-                reason: err instanceof Error ? err.message : String(err),
-                ms: Date.now() - t0,
+        if (metricsOn) {
+            this.emitSearchMetrics(query, {
+                fetchLimit, candidates, results, poolSaturated, embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
             });
-            return candidates.slice(0, limit);
         }
+        return results;
+    }
+    /**
+     * Emit one structured search-tuning line (via `logger.metric`, at `info`
+     * regardless of `logging.level`). `candidates` are in cosine order, so a
+     * candidate's array index is its cosine rank — `maxCosineRankSurvived` is the
+     * deepest cosine position that survived reranking into the returned set. Read
+     * it alongside `poolSaturated` to tune `candidateFloor`/`overfetch`/threshold
+     * per hardware. Never logs chunk content, embeddings, or credentials.
+     */
+    emitSearchMetrics(query, m) {
+        const { candidates, results } = m;
+        const contentIndex = new Map(candidates.map((c, i) => [c, i]));
+        const maxCosineRankSurvived = results.reduce((max, r) => Math.max(max, contentIndex.get(r) ?? -1), -1);
+        const fileCounts = new Map();
+        for (const r of results)
+            fileCounts.set(r.filePath, (fileCounts.get(r.filePath) ?? 0) + 1);
+        const topFileCount = results.length ? Math.max(...fileCounts.values()) : 0;
+        this.logger.metric('search metrics', {
+            query: query.slice(0, 120),
+            fetchLimit: m.fetchLimit,
+            candidatesReturned: candidates.length,
+            poolSaturated: m.poolSaturated,
+            maxCosineRankSurvived,
+            resultCount: results.length,
+            distinctFilesInResult: fileCounts.size,
+            topFileShare: results.length ? +(topFileCount / results.length).toFixed(3) : 0,
+            bestResultScore: results.length ? Math.min(...results.map(r => r.score)) : null,
+            worstResultScore: results.length ? Math.max(...results.map(r => r.score)) : null,
+            embedMs: m.embedMs,
+            rerankMs: m.rerankMs,
+            dbMs: m.dbMs,
+            totalMs: m.totalMs,
+        });
     }
     async fetchNeighbors(results) {
         const t0 = Date.now();
@@ -390,7 +473,22 @@ class SearcherService {
     async getCallers(symbol, project, calleeFile = null) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: getCallers', { symbol, project, calleeFile });
-        const params = [symbol, project];
+        const parsed = (0, symbol_name_1.parseCallerSymbol)(symbol);
+        if (!parsed)
+            throw new Error('Invalid symbol name');
+        const params = [project];
+        let nameFilter;
+        if (parsed.form === 'bare') {
+            params.push(parsed.name);
+            nameFilter = `"calleeName" = $${params.length}`;
+        }
+        else {
+            params.push(`${parsed.container}.${parsed.name}`);
+            const exactParam = params.length;
+            params.push(`%.${(0, symbol_name_1.escapeLike)(parsed.container)}.${(0, symbol_name_1.escapeLike)(parsed.name)}`);
+            const suffixParam = params.length;
+            nameFilter = `("calleeSymbol" = $${exactParam} OR "calleeSymbol" LIKE $${suffixParam} ESCAPE '\\')`;
+        }
         let fileFilter = '';
         if (calleeFile) {
             params.push(calleeFile);
@@ -398,13 +496,32 @@ class SearcherService {
         }
         const rows = await this.db.query(`SELECT "fromFile", "fromSymbol", "calleeName", "calleeFile", line
        FROM code_call
-       WHERE "calleeName" = $1 AND project = $2
+       WHERE project = $1 AND ${nameFilter}
        ${fileFilter}
        ORDER BY "fromFile", line
        LIMIT 200`, params);
         this.logger.debug('SearcherService: getCallers result', { count: rows.length, ms: Date.now() - t0 });
         return rows;
     }
+    /**
+     * One-line warning when any project in `scope` (the given `project`, or
+     * every project with `code_chunk`/`code_symbol` rows) is outdated — shown
+     * first in `find_symbol`/`get_callers` output. Any failure to determine the
+     * scope or read markers only drops the notice (warn logged); the lookup
+     * itself is unaffected.
+     */
+    async outdatedNotice(project) {
+        try {
+            const outdated = await this.db.listOutdatedProjects(project ? [project] : null);
+            if (outdated.length === 0)
+                return null;
+            return `⚠ Indexed before member indexing: ${[...outdated].sort().join(', ')} — run rag-index --reindex; methods and qualified names may be missing.`;
+        }
+        catch (err) {
+            this.logger.warn('SearcherService: failed to determine outdated-index scope', { reason: err.message });
+            return null;
+        }
+    }
     async grepSymbol(symbol, project, excludeFile) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: grepSymbol', { symbol, project, excludeFile });
@@ -417,11 +534,11 @@ class SearcherService {
             symbol,
             projectDir,
         ]);
-        if (!result) {
+        if (!result.ok || result.output === null) {
             return { matches: [], truncated: false };
         }
         const excludeAbsPath = path.join(this.config.workspaceRoot, excludeFile);
-        const all = result.split('\n').flatMap(line => {
+        const all = result.output.split('\n').flatMap(line => {
             const match = line.match(/^(.+?):(\d+):/);
             if (!match)
                 return [];
@@ -435,19 +552,29 @@ class SearcherService {
         return { matches: all.slice(0, GREP_MAX_RESULTS), truncated };
     }
     // Sync wrapper: validates name (throws synchronously), then returns Promise.
-    // Methods are never indexed — always resolved via grep. Other kinds use index with grep fallback.
+    // Every kind, including 'method', is looked up in the index first.
     findSymbol(name, project, kind) {
-        if (!/^[\w$]+$/.test(name))
+        const parsed = (0, symbol_name_1.parseFindSymbolName)(name);
+        if (!parsed)
             throw new Error('Invalid symbol name');
-        if (kind === 'method')
-            return this.grepFindSymbol(name, project, kind);
-        return this.findSymbolFromIndex(name, project, kind);
+        return this.findSymbolFromIndex(parsed, project, kind);
     }
-    async findSymbolFromIndex(name, project, kind) {
+    async findSymbolFromIndex(parsed, project, kind) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'index' });
+        this.logger.debug('SearcherService: findSymbol', { parsed, project, kind, source: 'index' });
+        const container = 'container' in parsed ? parsed.container : null;
         try {
-            const params = [name];
+            const params = [parsed.name];
+            let nameFilter = 'name = $1';
+            let orderPrefix = '';
+            if (container !== null) {
+                params.push(container);
+                const exactParam = params.length;
+                params.push(`%.${(0, symbol_name_1.escapeLike)(container)}`);
+                const suffixParam = params.length;
+                nameFilter += ` AND (container = $${exactParam} OR container LIKE $${suffixParam} ESCAPE '\\')`;
+                orderPrefix = `(CASE WHEN container = $${exactParam} THEN 0 ELSE 1 END), `;
+            }
             let projectFilter = '';
             if (project) {
                 params.push(project);
@@ -459,11 +586,11 @@ class SearcherService {
                 kindFilter = `AND kind = $${params.length}`;
             }
             params.push(FIND_SYMBOL_LIMIT + 1);
-            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col
-           FROM code_symbol
-           WHERE name = $1 ${projectFilter} ${kindFilter}
-           ORDER BY project, "filePath"
-           LIMIT $${params.length}`, params);
+            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col, container, "isStatic"
+         FROM code_symbol
+         WHERE ${nameFilter} ${projectFilter} ${kindFilter}
+         ORDER BY ${orderPrefix}project, "filePath", line
+         LIMIT $${params.length}`, params);
             const truncated = rows.length > FIND_SYMBOL_LIMIT;
             const hits = rows.slice(0, FIND_SYMBOL_LIMIT).map(row => ({
                 filePath: row.filePath,
@@ -471,22 +598,34 @@ class SearcherService {
                 column: row.col ?? 1,
                 kind: row.kind,
                 signature: row.signature ?? row.name,
+                qualified: row.container ? `${row.container}.${row.name}` : row.name,
+                isStatic: !!row.isStatic,
+                source: 'index',
             }));
             this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
-            return { hits, truncated };
+            if (hits.length > 0)
+                return { hits, truncated, grepFailed: false };
+            if (parsed.form === 'quoted' || parsed.form === 'computed')
+                return { hits: [], truncated: false, grepFailed: false };
+            return this.grepFindSymbol(parsed, project, kind);
         }
-        catch {
-            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { name, project, ms: Date.now() - t0 });
-            return this.grepFindSymbol(name, project, kind);
+        catch (err) {
+            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { reason: err.message, ms: Date.now() - t0 });
+            if (parsed.form === 'quoted' || parsed.form === 'computed')
+                return { hits: [], truncated: false, grepFailed: false };
+            return this.grepFindSymbol(parsed, project, kind);
         }
     }
-    async grepFindSymbol(name, project, kind) {
+    async grepFindSymbol(parsed, project, kind) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'grep' });
+        const grepName = parsed.name; // qualified names are grepped by their last segment, no container filter
+        this.logger.debug('SearcherService: findSymbol', { grepName, project, kind, source: 'grep' });
+        const pattern = this.buildFindSymbolPattern(grepName, kind);
+        if (pattern === null)
+            return { hits: [], truncated: false, grepFailed: false };
         const searchDir = project
             ? this.resolveProjectRoot(project)
             : this.config.workspaceRoot;
-        const pattern = this.buildFindSymbolPattern(name, kind);
         const result = await this.spawnGrep([
             '-rn', '-E',
             '-m', String(FIND_SYMBOL_RAW_LIMIT),
@@ -495,12 +634,14 @@ class SearcherService {
             pattern,
             searchDir,
         ]);
-        if (!result)
-            return { hits: [], truncated: false };
-        const hits = [];
-        for (const raw of result.split('\n')) {
-            if (hits.length >= FIND_SYMBOL_LIMIT)
-                break;
+        if (!result.ok) {
+            this.logger.warn('SearcherService: findSymbol grep failed', { grepName, project });
+            return { hits: [], truncated: false, grepFailed: true };
+        }
+        if (result.output === null)
+            return { hits: [], truncated: false, grepFailed: false };
+        const parsedHits = [];
+        for (const raw of result.output.split('\n')) {
             const m = raw.match(/^(.+?):(\d+):(.*)$/);
             if (!m)
                 continue;
@@ -508,19 +649,23 @@ class SearcherService {
             const lineNum = parseInt(lineNumStr, 10);
             if (isNaN(lineNum))
                 continue;
-            const col = matchedLine.indexOf(name);
+            const col = SearcherService.wholeWordIndex(matchedLine, grepName);
             if (col === -1)
                 continue;
-            hits.push({
+            parsedHits.push({
                 filePath: path.relative(this.config.workspaceRoot, absFile),
                 line: lineNum,
                 column: col + 1,
-                kind: this.inferKind(matchedLine, name),
+                kind: this.inferKind(matchedLine, grepName),
                 signature: matchedLine.trim(),
+                qualified: grepName,
+                isStatic: false,
+                source: 'grep',
             });
         }
-        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: hits.length, truncated: hits.length >= FIND_SYMBOL_LIMIT, ms: Date.now() - t0 });
-        return { hits, truncated: hits.length >= FIND_SYMBOL_LIMIT };
+        const truncated = parsedHits.length > FIND_SYMBOL_LIMIT;
+        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: Math.min(parsedHits.length, FIND_SYMBOL_LIMIT), truncated, ms: Date.now() - t0 });
+        return { hits: parsedHits.slice(0, FIND_SYMBOL_LIMIT), truncated, grepFailed: false };
     }
     listFiles(relativePath, project, depth, pattern) {
         const t0 = Date.now();
@@ -658,36 +803,67 @@ class SearcherService {
             }
         }
     }
+    /**
+     * ERE pattern for a grep-fallback kind, or null when that kind is never
+     * grepped (`function_property`/`method_signature` are index-only; a bare
+     * `constructor` search only makes sense when the name itself is `constructor`).
+     */
     buildFindSymbolPattern(name, kind) {
+        if (kind === 'function_property' || kind === 'method_signature')
+            return null;
+        if (kind === 'constructor')
+            return name === 'constructor' ? `(^|[[:space:]])constructor[[:space:]]*\\(` : null;
+        const esc = name.replace(/\$/g, '\\$'); // ERE end-of-line metachar
+        const MODIFIER = '(public|private|protected|static|abstract|async|override)';
+        const BOUNDARY = '(^|[^[:alnum:]_$])';
         const patterns = {
-            function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${name}[[:space:](<]`,
-            class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${name}[[:space:]{<]`,
-            type: `(export[[:space:]]+)?type[[:space:]]+${name}[[:space:]=<]`,
-            interface: `(export[[:space:]]+)?interface[[:space:]]+${name}[[:space:]{<]`,
-            variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${name}[[:space:]=:]`,
-            method: `(public[[:space:]]+|async[[:space:]]+|static[[:space:]]+|override[[:space:]]+)+(async[[:space:]]+)?${name}[[:space:]]*[(<]`,
+            function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${esc}[[:space:](<]`,
+            class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${esc}[[:space:]{<]`,
+            type: `(export[[:space:]]+)?type[[:space:]]+${esc}[[:space:]=<]`,
+            interface: `(export[[:space:]]+)?interface[[:space:]]+${esc}[[:space:]{<]`,
+            variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${esc}[[:space:]=:]`,
+            method: `${BOUNDARY}(${MODIFIER}[[:space:]]+)+\\*?[[:space:]]*${esc}[[:space:]]*[(<]`,
+            get_accessor: `(^|[[:space:]])get[[:space:]]+${esc}[[:space:]]*\\(`,
+            set_accessor: `(^|[[:space:]])set[[:space:]]+${esc}[[:space:]]*\\(`,
         };
         if (kind === 'all')
             return Object.values(patterns).join('|');
         return patterns[kind];
     }
+    /** 1-based index of the first whole-word occurrence of `name` in `line`, or -1. */
+    static wholeWordIndex(line, name) {
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const re = new RegExp(`(?<![\\w$#])${escaped}(?![\\w$#])`);
+        const m = re.exec(line);
+        return m ? m.index : -1;
+    }
     inferKind(line, name) {
-        const before = line.slice(0, line.indexOf(name));
-        if (/\bfunction\s+$/.test(before))
+        if (name === 'constructor')
+            return 'constructor';
+        const idx = SearcherService.wholeWordIndex(line, name);
+        const before = idx === -1 ? line : line.slice(0, idx);
+        const tokens = before.trim().split(/\s+/).filter(Boolean);
+        const last = (tokens[tokens.length - 1] ?? '').replace(/\*$/, '');
+        if (last === 'get')
+            return 'get_accessor';
+        if (last === 'set')
+            return 'set_accessor';
+        if (last === 'function')
             return 'function';
-        if (/\bclass\s+$/.test(before))
+        if (last === 'class')
             return 'class';
-        if (/\binterface\s+$/.test(before))
+        if (last === 'interface')
             return 'interface';
-        if (/\btype\s+$/.test(before))
+        if (last === 'type')
             return 'type';
-        if (/\b(public|async|static|override)\s+$/.test(before))
+        if (['public', 'private', 'protected', 'static', 'abstract', 'async', 'override'].includes(last))
             return 'method';
         return 'variable';
     }
     /**
-     * Async wrapper around grep to avoid blocking the event loop.
-     * Returns stdout as a string, or null if grep returned no results or errored.
+     * Async wrapper around grep to avoid blocking the event loop. `ok: false`
+     * means grep could not be spawned or exited with status ≥ 2 (distinguishable
+     * from a clean "no matches", which is `ok: true, output: null`).
      */
     spawnGrep(args) {
         return new Promise((resolve) => {
@@ -704,19 +880,16 @@ class SearcherService {
             proc.stderr.on('data', () => { });
             proc.on('error', (err) => {
                 this.logger.error('SearcherService: grep spawn failed', { reason: err.message });
-                resolve(null);
+                resolve({ ok: false });
             });
             proc.on('close', (code) => {
-                // grep returns 1 for "no matches" — not an error
-                if (code !== 0 && code !== 1) {
+                // grep returns 1 for "no matches" — not an error; 2+ is a real failure
+                if (code !== null && code >= 2) {
                     this.logger.warn('SearcherService: grep exited with code', { code });
+                    resolve({ ok: false });
+                    return;
                 }
-                if (chunks.length === 0) {
-                    resolve(null);
-                }
-                else {
-                    resolve(Buffer.concat(chunks).toString('utf-8'));
-                }
+                resolve({ ok: true, output: chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8') });
             });
         });
     }

package/dist/src/services/WebServerService.d.ts

@@ -1,13 +1,34 @@
-import type { Config } from '../config';
+import { Config } from '../config';
 import type { ISearcher } from '../interfaces';
 import type { IEmbedder } from '../interfaces';
 import type { ILogger } from '../interfaces';
 import { type JsonConfig } from '../config-store';
+import { type ProvisioningDeps } from './infinity-provisioning';
+export type BackendActionKind = 'started' | 'already-running' | 'not-needed' | 'manual-required' | 'failed';
+export interface BackendActionResult {
+    action: BackendActionKind;
+    message: string | null;
+}
+export type BackendStatusState = 'idle' | 'recreating' | 'ready' | 'failed';
+export interface BackendStatus {
+    state: BackendStatusState;
+    message: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface WebServerDeps {
+    /** Path to the managed docker-compose.yml. Defaults to `CONFIG_DIR/docker-compose.yml`. */
+    composePath?: string;
+    /** Injection seams (fetchImpl/runCommand/pollIntervalMs/readinessTimeoutMs) for the readiness primitive. */
+    provisioning?: ProvisioningDeps;
+    /** Reads the just-saved config back — defaults to `() => new Config()`. Injectable for tests. */
+    readSavedConfig?: () => Config;
+}
 /**
  * Per-field choice lists for the config form. `strict` → render a dropdown that
  * only accepts a listed value (e.g. the embedding model, tied to the vector
  * dimension). Non-strict → a combobox: the values are suggestions but free text
- * is still allowed (e.g. any Ollama model the user has pulled).
+ * is still allowed (e.g. any model served by a self-hosted backend).
  */
 export interface FieldOption {
     values: string[];
@@ -41,7 +62,13 @@ export declare class WebServer {
     private readonly logger;
     private readonly embedder;
     private server?;
-    constructor(searcher: ISearcher, config: Config, logger: ILogger, embedder: IEmbedder);
+    private readonly composePath;
+    private readonly provisioningDeps;
+    private readonly readSavedConfig;
+    private backendStatus;
+    private taskInFlight;
+    private pending;
+    constructor(searcher: ISearcher, config: Config, logger: ILogger, embedder: IEmbedder, deps?: WebServerDeps);
     start(port: number, host: string): Promise<void>;
     stop(): Promise<void>;
     /** The bound address once started (e.g. `.port` after listen(0)); null otherwise. */
@@ -51,6 +78,17 @@ export declare class WebServer {
     private handle;
     private maskedConfig;
     private saveConfig;
+    /**
+     * After a successful config write, decide the Infinity backend action per
+     * the first-match decision table (`local-backend-provisioning`). Computes
+     * the required set from the SAVED config (a fresh `Config` re-read from the
+     * file just written — never the server's startup config/embedder). Never
+     * throws — an unexpected error becomes `{ action: 'failed', message }`; the
+     * saved config and `GET /api/backend-status` are unaffected either way.
+     */
+    private evaluateBackendAfterSave;
+    /** Kick off (or continue, via a follow-up) a background Infinity recreate. */
+    private startBackgroundTask;
     /**
      * Choice lists for model fields. Both are non-strict comboboxes (free text
      * allowed): the embedding model suggests the known registry models plus any