opencode-codebase-index 0.19.1 → 0.20.0

package/dist/cli.js

@@ -781,6 +781,7 @@ function getDefaultIndexingConfig() {
     autoIndexMaxRetries: 5,
     autoIndexRetryDelayMs: 100,
     watchFiles: true,
+    pauseBackgroundIndexingOnBattery: false,
     maxFileSize: 1048576,
     maxChunksPerFile: 100,
     semanticOnly: false,
@@ -912,6 +913,7 @@ function parseConfig(raw) {
     autoIndexMaxRetries: typeof rawIndexing.autoIndexMaxRetries === "number" ? Math.min(10, Math.max(0, Math.floor(rawIndexing.autoIndexMaxRetries))) : defaultIndexing.autoIndexMaxRetries,
     autoIndexRetryDelayMs: typeof rawIndexing.autoIndexRetryDelayMs === "number" ? Math.min(1e4, Math.max(10, Math.floor(rawIndexing.autoIndexRetryDelayMs))) : defaultIndexing.autoIndexRetryDelayMs,
     watchFiles: typeof rawIndexing.watchFiles === "boolean" ? rawIndexing.watchFiles : defaultIndexing.watchFiles,
+    pauseBackgroundIndexingOnBattery: typeof rawIndexing.pauseBackgroundIndexingOnBattery === "boolean" ? rawIndexing.pauseBackgroundIndexingOnBattery : defaultIndexing.pauseBackgroundIndexingOnBattery,
     maxFileSize: typeof rawIndexing.maxFileSize === "number" ? rawIndexing.maxFileSize : defaultIndexing.maxFileSize,
     maxChunksPerFile: typeof rawIndexing.maxChunksPerFile === "number" ? Math.max(1, rawIndexing.maxChunksPerFile) : defaultIndexing.maxChunksPerFile,
     semanticOnly: typeof rawIndexing.semanticOnly === "boolean" ? rawIndexing.semanticOnly : defaultIndexing.semanticOnly,
@@ -1085,6 +1087,18 @@ function metricDelta(current, baseline) {
   };
 }
 function compareSummaries(current, baseline, againstPath) {
+  const hasCurrentFingerprint = current.datasetFingerprint !== void 0;
+  const hasBaselineFingerprint = baseline.datasetFingerprint !== void 0;
+  if (hasCurrentFingerprint !== hasBaselineFingerprint) {
+    throw new Error(
+      `Cannot compare evaluation summaries with mismatched dataset fingerprint presence: current=${hasCurrentFingerprint ? "present" : "missing"}, baseline=${hasBaselineFingerprint ? "present" : "missing"} at ${againstPath}`
+    );
+  }
+  if (hasCurrentFingerprint && hasBaselineFingerprint && current.datasetFingerprint !== baseline.datasetFingerprint) {
+    throw new Error(
+      `Cannot compare incompatible evaluation datasets by fingerprint: current=${current.datasetFingerprint}, baseline=${baseline.datasetFingerprint} at ${againstPath}`
+    );
+  }
   if (current.datasetName !== baseline.datasetName || current.datasetVersion !== baseline.datasetVersion || current.queryCount !== baseline.queryCount) {
     throw new Error(
       `Cannot compare incompatible evaluation datasets: current=${current.datasetName}@${current.datasetVersion} (${current.queryCount} queries), baseline=${baseline.datasetName}@${baseline.datasetVersion} (${baseline.queryCount} queries) at ${againstPath}`
@@ -1388,6 +1402,7 @@ function buildPerQueryArtifact(perQuery) {
 }
 
 // src/eval/runner.ts
+import * as crypto from "crypto";
 import { existsSync as existsSync13 } from "fs";
 import * as path21 from "path";
 import { performance as performance3 } from "perf_hooks";
@@ -4024,9 +4039,21 @@ function parseFiles(files) {
   return result.map((f) => ({
     path: f.path,
     chunks: f.chunks.map(mapChunk),
+    symbols: (f.symbols ?? []).map(mapParsedSymbol),
     hash: f.hash
   }));
 }
+function mapParsedSymbol(symbol) {
+  return {
+    name: symbol.name,
+    kind: symbol.kind,
+    startLine: symbol.startLine ?? symbol.start_line,
+    startCol: symbol.startCol ?? symbol.start_col,
+    endLine: symbol.endLine ?? symbol.end_line,
+    endCol: symbol.endCol ?? symbol.end_col,
+    language: symbol.language
+  };
+}
 function mapChunk(c) {
   return {
     content: c.content,
@@ -6847,6 +6874,7 @@ var INDEX_METADATA_VERSION = "1";
 var EMBEDDING_STRATEGY_VERSION = "2";
 var SWIFT_PARSER_VERSION = "1";
 var METAL_PARSER_VERSION = "1";
+var SYMBOL_EXTRACTOR_VERSION = "1";
 var RANKING_TOKEN_CACHE_LIMIT = 4096;
 var RANK_HYBRID_CACHE_LIMIT = 256;
 function createPendingChunkStorageText(texts) {
@@ -7148,7 +7176,7 @@ function classifyQueryIntentRaw(query) {
   return "neutral";
 }
 function isImplementationChunkType(chunkType) {
-  return [
+  return CALL_GRAPH_SYMBOL_CHUNK_TYPES.has(chunkType) || [
     "export_statement",
     "function",
     "function_declaration",
@@ -7593,7 +7621,7 @@ function promoteIdentifierMatches(query, combined, semanticCandidates, keywordCa
   const remainder = combined.filter((candidate) => !promotedIds.has(candidate.id));
   return [...promoted, ...remainder];
 }
-function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallbackCandidates, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
+function buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbolIds, limit, fallbackCandidates, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
   if (!prioritizeSourcePaths) {
     return [];
   }
@@ -7607,14 +7635,14 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
   const primaryHint = extractPrimaryIdentifierQueryHint(query);
   const upsertChunkCandidate = (chunk, identifier, normalizedIdentifier, baseScore) => {
     if (branchChunkIds && !branchChunkIds.has(chunk.chunkId)) {
-      return;
+      return false;
     }
     const chunkType = chunk.nodeType ?? "other";
     if (!isImplementationChunkType(chunkType)) {
-      return;
+      return false;
     }
     if (!isLikelyImplementationPath2(chunk.filePath)) {
-      return;
+      return false;
     }
     const nameLower = (chunk.name ?? "").toLowerCase();
     const exactName = nameLower === identifier || nameLower.replace(/_/g, "") === normalizedIdentifier;
@@ -7636,6 +7664,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
         }
       });
     }
+    return true;
   };
   const normalizedHints = identifierHints.flatMap((hint) => [
     hint,
@@ -7657,12 +7686,46 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
       dedupSymbols.set(symbol.id, symbol);
     }
     for (const symbol of dedupSymbols.values()) {
+      if (branchSymbolIds && !branchSymbolIds.has(symbol.id)) {
+        continue;
+      }
+      if (filePathHint && !pathMatchesHint(symbol.filePath, filePathHint)) {
+        continue;
+      }
       const chunks = database.getChunksByFile(symbol.filePath);
+      let foundCoveringChunk = false;
       for (const chunk of chunks) {
         if (chunk.startLine > symbol.startLine || chunk.endLine < symbol.endLine) {
           continue;
         }
-        upsertChunkCandidate(chunk, identifier, normalizedIdentifier);
+        const chunkName = (chunk.name ?? "").toLowerCase();
+        const symbolName2 = symbol.name.toLowerCase();
+        if (chunkName !== symbolName2 && chunkName.replace(/_/g, "") !== symbolName2.replace(/_/g, "")) {
+          continue;
+        }
+        foundCoveringChunk = upsertChunkCandidate(chunk, identifier, normalizedIdentifier) || foundCoveringChunk;
+      }
+      if (foundCoveringChunk || !isLikelyImplementationPath2(symbol.filePath)) {
+        continue;
+      }
+      const symbolName = symbol.name.toLowerCase();
+      const exactName = symbolName === identifier || symbolName.replace(/_/g, "") === normalizedIdentifier;
+      const score = exactName ? 0.99 : 0.88;
+      const existing = symbolCandidates.get(symbol.id);
+      if (!existing || score > existing.score) {
+        symbolCandidates.set(symbol.id, {
+          id: symbol.id,
+          score,
+          metadata: {
+            filePath: symbol.filePath,
+            startLine: symbol.startLine,
+            endLine: symbol.endLine,
+            chunkType: symbol.kind,
+            name: symbol.name,
+            language: symbol.language,
+            hash: symbol.id
+          }
+        });
       }
     }
     const dedupChunksByName = /* @__PURE__ */ new Map();
@@ -7670,6 +7733,9 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
       dedupChunksByName.set(chunk.chunkId, chunk);
     }
     for (const chunk of dedupChunksByName.values()) {
+      if (filePathHint && !pathMatchesHint(chunk.filePath, filePathHint)) {
+        continue;
+      }
       upsertChunkCandidate(chunk, identifier, normalizedIdentifier);
     }
   }
@@ -8211,6 +8277,10 @@ var Indexer = class _Indexer {
     const projectHash = hashContent(path13.resolve(this.projectRoot)).slice(0, 16);
     return `${key}.${projectHash}`;
   }
+  getSymbolExtractorVersionMetadataKey(catalogIdentity = this.getBranchCatalogIdentity()) {
+    const branchKey = this.getBranchCatalogKeyFor(catalogIdentity);
+    return `index.symbolExtractorVersion.${hashContent(branchKey).slice(0, 24)}`;
+  }
   hasProjectForceReembedPending() {
     return this.config.scope === "global" && this.database?.getMetadata(this.getProjectForceReembedMetadataKey()) === "true";
   }
@@ -9554,7 +9624,8 @@ var Indexer = class _Indexer {
       }
       const branchKey = this.getBranchCatalogKey();
       const alreadyIndexed = database.getBranchChunkIds(branchKey).length > 0 && database.getBranchSymbolIds(branchKey).length > 0;
-      if (alreadyIndexed && this.getStoredBranchCommit(database) === normalizedCommit) {
+      const symbolsCurrent = database.getMetadata(this.getSymbolExtractorVersionMetadataKey()) === SYMBOL_EXTRACTOR_VERSION;
+      if (alreadyIndexed && symbolsCurrent && this.getStoredBranchCommit(database) === normalizedCommit) {
         return { prepared: false };
       }
       const stats = await this.indexUnlocked(onProgress, [], true);
@@ -9613,6 +9684,8 @@ var Indexer = class _Indexer {
     const reparseCachedSwiftFiles = database.getMetadata(swiftParserMetadataKey) !== SWIFT_PARSER_VERSION;
     const metalParserMetadataKey = this.getMetalParserVersionMetadataKey();
     const reparseCachedMetalFiles = database.getMetadata(metalParserMetadataKey) !== METAL_PARSER_VERSION;
+    const symbolExtractorMetadataKey = this.getSymbolExtractorVersionMetadataKey();
+    const refreshCachedSymbols = database.getMetadata(symbolExtractorMetadataKey) !== SYMBOL_EXTRACTOR_VERSION;
     if (reparseCachedSwiftFiles && Array.from(this.fileHashCache.keys()).some(
       (filePath) => path13.extname(filePath).toLowerCase() === ".swift"
     )) {
@@ -9656,7 +9729,7 @@ var Indexer = class _Indexer {
       );
       const requiresSwiftParserUpgrade = reparseCachedSwiftFiles && path13.extname(canonicalPath).toLowerCase() === ".swift";
       const requiresMetalParserUpgrade = reparseCachedMetalFiles && path13.extname(canonicalPath).toLowerCase() === ".metal";
-      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade) {
+      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade && !refreshCachedSymbols) {
         unchangedFilePaths.add(canonicalPath);
         this.logger.recordCacheHit();
       } else {
@@ -9867,37 +9940,27 @@ var Indexer = class _Indexer {
       const parsed = parsedFiles[i];
       const changedFile = changedFiles[i];
       const fileSymbols = [];
-      for (const chunk of parsed.chunks) {
-        if (!chunk.name || !CALL_GRAPH_SYMBOL_CHUNK_TYPES.has(chunk.chunkType)) continue;
-        const existingMetalSymbol = chunk.language === "metal" ? fileSymbols.find(
-          (symbol2) => symbol2.name === chunk.name && symbol2.kind === chunk.chunkType && symbol2.startLine <= chunk.endLine && chunk.startLine <= symbol2.endLine
-        ) : void 0;
-        if (existingMetalSymbol) {
-          existingMetalSymbol.startLine = Math.min(existingMetalSymbol.startLine, chunk.startLine);
-          existingMetalSymbol.endLine = Math.max(existingMetalSymbol.endLine, chunk.endLine);
-          existingMetalSymbol.startCol = Math.min(existingMetalSymbol.startCol, chunk.startCol ?? 0);
-          existingMetalSymbol.endCol = Math.max(existingMetalSymbol.endCol, chunk.endCol ?? 0);
-          continue;
-        }
+      for (const parsedSymbol of parsed.symbols) {
+        if (!CALL_GRAPH_SYMBOL_CHUNK_TYPES.has(parsedSymbol.kind)) continue;
         const preparedNamespace = this.getPreparedBranchNamespace();
         const symbolId = `sym_${hashContent(
-          (preparedNamespace ? `${preparedNamespace}:` : "") + parsed.path + ":" + chunk.name + ":" + chunk.chunkType + ":" + chunk.startLine + ":" + (chunk.startCol ?? 0) + ":" + changedFile.hash
+          (preparedNamespace ? `${preparedNamespace}:` : "") + parsed.path + ":" + parsedSymbol.name + ":" + parsedSymbol.kind + ":" + parsedSymbol.startLine + ":" + parsedSymbol.startCol + ":" + changedFile.hash
         ).slice(0, 16)}`;
         const symbol = {
           id: symbolId,
           filePath: parsed.path,
-          name: chunk.name,
-          kind: chunk.chunkType,
-          startLine: chunk.startLine,
-          startCol: chunk.startCol ?? 0,
-          endLine: chunk.endLine,
-          endCol: chunk.endCol ?? 0,
-          language: chunk.language
+          name: parsedSymbol.name,
+          kind: parsedSymbol.kind,
+          startLine: parsedSymbol.startLine,
+          startCol: parsedSymbol.startCol,
+          endLine: parsedSymbol.endLine,
+          endCol: parsedSymbol.endCol,
+          language: parsedSymbol.language
         };
         fileSymbols.push(symbol);
         allSymbolIds.add(symbolId);
       }
-      const fileLanguage = parsed.chunks[0]?.language;
+      const fileLanguage = parsed.symbols[0]?.language ?? parsed.chunks[0]?.language;
       const isCaseInsensitiveLanguage = !!fileLanguage && CASE_INSENSITIVE_LANGUAGES.has(fileLanguage);
       const normalizeSymbolKey = (name) => isCaseInsensitiveLanguage ? name.toLowerCase() : name;
       const symbolsByName = /* @__PURE__ */ new Map();
@@ -10013,6 +10076,7 @@ var Indexer = class _Indexer {
       }
       database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
       database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
+      database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
       this.saveBranchCommit(database, indexedCommit);
       this.saveIndexMetadata(configuredProviderInfo);
       this.indexCompatibility = { compatible: true };
@@ -10049,6 +10113,7 @@ var Indexer = class _Indexer {
       }
       database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
       database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
+      database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
       this.saveBranchCommit(database, indexedCommit);
       this.saveIndexMetadata(configuredProviderInfo);
       this.indexCompatibility = { compatible: true };
@@ -10328,6 +10393,7 @@ var Indexer = class _Indexer {
     }
     database.setMetadata(swiftParserMetadataKey, SWIFT_PARSER_VERSION);
     database.setMetadata(metalParserMetadataKey, METAL_PARSER_VERSION);
+    database.setMetadata(symbolExtractorMetadataKey, SYMBOL_EXTRACTOR_VERSION);
     this.saveBranchCommit(database, indexedCommit);
     this.saveIndexMetadata(configuredProviderInfo);
     this.indexCompatibility = { compatible: true };
@@ -10466,10 +10532,11 @@ var Indexer = class _Indexer {
     const keywordResults = await this.keywordSearch(query, maxResults * 4, store, invertedIndex);
     const keywordMs = performance2.now() - keywordStartTime;
     let branchChunkIds = null;
+    let branchSymbolIds = null;
     if (filterByBranch && (this.config.scope === "global" || this.currentBranch !== "default")) {
-      branchChunkIds = new Set(
-        this.getBranchCatalogKeys().flatMap((branchKey) => database.getBranchChunkIds(branchKey))
-      );
+      const branchCatalogKeys = this.getBranchCatalogKeys();
+      branchChunkIds = new Set(branchCatalogKeys.flatMap((branchKey) => database.getBranchChunkIds(branchKey)));
+      branchSymbolIds = new Set(branchCatalogKeys.flatMap((branchKey) => database.getBranchSymbolIds(branchKey)));
     }
     const prefilterStartTime = performance2.now();
     const shouldPrefilterByBranch = branchChunkIds !== null && (this.config.scope === "global" || branchChunkIds.size > 0);
@@ -10541,6 +10608,7 @@ var Indexer = class _Indexer {
       query,
       database,
       branchChunkIds,
+      branchSymbolIds,
       maxResults,
       union,
       sourceIntent
@@ -10554,7 +10622,7 @@ var Indexer = class _Indexer {
       (r) => isLikelyImplementationPath2(r.metadata.filePath) && isImplementationChunkType(r.metadata.chunkType)
     );
     const filtered = (sourceIntent && hasCodeHints && implementationOnly.length > 0 ? implementationOnly : baseFiltered).slice(0, maxResults);
-    const identifierFallback = !options?.definitionIntent && filtered.length === 0 && identifierHints.length > 0 ? buildSymbolDefinitionLane(query, database, branchChunkIds, maxResults, union, true).filter((r) => matchesSearchFilters(r, options, this.config.search.minScore)).slice(0, maxResults) : [];
+    const identifierFallback = !options?.definitionIntent && filtered.length === 0 && identifierHints.length > 0 ? buildSymbolDefinitionLane(query, database, branchChunkIds, branchSymbolIds, maxResults, union, true).filter((r) => matchesSearchFilters(r, options, this.config.search.minScore)).slice(0, maxResults) : [];
     const finalResults = filtered.length > 0 ? filtered : identifierFallback;
     const totalSearchMs = performance2.now() - searchStartTime;
     this.logger.recordSearch(totalSearchMs, {
@@ -10711,7 +10779,7 @@ var Indexer = class _Indexer {
       const extension = path13.extname(filePath).toLowerCase();
       return extension === ".php" || extension === ".c" || extension === ".cc" || extension === ".cpp" || extension === ".cxx";
     });
-    if (hasSwiftFiles && database.getMetadata(this.getSwiftParserVersionMetadataKey()) !== SWIFT_PARSER_VERSION || hasMetalFiles && database.getMetadata(this.getMetalParserVersionMetadataKey()) !== METAL_PARSER_VERSION || hasCallGraphMigrationFiles && database.getMetadata(this.getCallGraphResolutionMetadataKey()) !== CALL_GRAPH_RESOLUTION_VERSION) {
+    if (hasSwiftFiles && database.getMetadata(this.getSwiftParserVersionMetadataKey()) !== SWIFT_PARSER_VERSION || hasMetalFiles && database.getMetadata(this.getMetalParserVersionMetadataKey()) !== METAL_PARSER_VERSION || database.getMetadata(this.getSymbolExtractorVersionMetadataKey()) !== SYMBOL_EXTRACTOR_VERSION || hasCallGraphMigrationFiles && database.getMetadata(this.getCallGraphResolutionMetadataKey()) !== CALL_GRAPH_RESOLUTION_VERSION) {
       return { readable: true, current: false, reason: "migration-required" };
     }
     if (isGitRepo(this.materializedProjectRoot)) {
@@ -11419,7 +11487,10 @@ var Indexer = class _Indexer {
     const requestedRef = opts.pr !== void 0 ? expectedCommit : headRefName ?? resolvedBranch;
     const storedCommit = this.getStoredBranchCommit(database, catalogIdentity);
     const catalogIdentityMatches = storedCommit === expectedCommit;
-    if (branchSymbols.length === 0 || !catalogIdentityMatches) {
+    const symbolsCurrent = database.getMetadata(
+      this.getSymbolExtractorVersionMetadataKey(catalogIdentity)
+    ) === SYMBOL_EXTRACTOR_VERSION;
+    if (branchSymbols.length === 0 || !catalogIdentityMatches || !symbolsCurrent) {
       if (!resolvedBranch || resolvedBranch === "default") {
         throw new Error("Run index_codebase first to build the call graph and symbol index for this project.");
       }
@@ -11735,8 +11806,17 @@ function fitTextToContextBudget(text, tokenBudget) {
 function normalizedLineRange(result) {
   return result.startLine <= result.endLine ? { start: result.startLine, end: result.endLine } : { start: result.endLine, end: result.startLine };
 }
-function rankContextCandidates(results) {
-  return results.map((result, originalIndex) => ({ result, originalIndex })).sort((left, right) => right.result.score - left.result.score || left.originalIndex - right.originalIndex);
+function rankContextCandidates(results, preferImplementationPaths) {
+  return results.map((result, originalIndex) => ({ result, originalIndex })).sort((left, right) => {
+    if (preferImplementationPaths) {
+      const leftIsImplementation = isLikelyImplementationPath(left.result.filePath);
+      const rightIsImplementation = isLikelyImplementationPath(right.result.filePath);
+      if (leftIsImplementation !== rightIsImplementation) {
+        return leftIsImplementation ? -1 : 1;
+      }
+    }
+    return right.result.score - left.result.score || left.originalIndex - right.originalIndex;
+  });
 }
 function deduplicateContextCandidates(candidates) {
   const acceptedByFile = /* @__PURE__ */ new Map();
@@ -11825,7 +11905,12 @@ function buildContextPack(results, options = {}) {
   const maxResults = Math.max(0, Math.floor(options.maxResults ?? results.length));
   const includeExactSearchHandoff = options.includeExactSearchHandoff ?? false;
   const candidateCount = results.length;
-  const deduplicated = deduplicateContextCandidates(rankContextCandidates(results));
+  const deduplicated = deduplicateContextCandidates(
+    rankContextCandidates(
+      results,
+      options.preferImplementationPaths ?? false
+    )
+  );
   const diversified = diversifyContextCandidates(deduplicated);
   const duplicateCount = candidateCount - deduplicated.length;
   const selectable = diversified.slice(0, maxResults);
@@ -12197,7 +12282,7 @@ ${truncateContent(r.content)}
 }
 
 // src/utils/effectiveness-metrics.ts
-var EFFECTIVENESS_METRICS_SCHEMA_VERSION = 2;
+var EFFECTIVENESS_METRICS_SCHEMA_VERSION = 3;
 var MAX_EFFECTIVENESS_COUNTER = 1e9;
 var EFFECTIVENESS_TOOL_ROUTES = [
   "context-conceptual",
@@ -12243,6 +12328,9 @@ var EFFECTIVENESS_SCOPE_RELAXATION_BUCKETS = ["none", "directory", "file-type",
 function emptyCounterMap(values) {
   return Object.fromEntries(values.map((value) => [value, 0]));
 }
+function emptyRouteCounterMap(routes, values) {
+  return Object.fromEntries(routes.map((route) => [route, emptyCounterMap(values)]));
+}
 function boundedNumber(value) {
   if (value === void 0 || !Number.isFinite(value)) return 0;
   return Math.max(0, Math.floor(value));
@@ -12291,6 +12379,11 @@ function allowedValue(value, allowed, fallback) {
 function cloneCounterMap(counters) {
   return { ...counters };
 }
+function cloneRouteCounterMap(counters) {
+  return Object.fromEntries(
+    EFFECTIVENESS_TOOL_ROUTES.map((route) => [route, cloneCounterMap(counters[route])])
+  );
+}
 var EffectivenessMetrics = class {
   constructor(counterCap = MAX_EFFECTIVENESS_COUNTER) {
     this.counterCap = counterCap;
@@ -12306,7 +12399,7 @@ var EffectivenessMetrics = class {
         lifetime: "process",
         reset: "index_metrics-reset-or-process-exit",
         maxCounterValue: this.counterCap,
-        dimensions: "bounded-host-and-category-only"
+        dimensions: "bounded-route-and-bucketed-performance-only"
       },
       totalCalls: 0,
       toolRoute: emptyCounterMap(EFFECTIVENESS_TOOL_ROUTES),
@@ -12318,7 +12411,14 @@ var EffectivenessMetrics = class {
       tokenBudget: emptyCounterMap(EFFECTIVENESS_TOKEN_BUDGET_BUCKETS),
       returnedTokenEstimate: emptyCounterMap(EFFECTIVENESS_RETURNED_TOKEN_BUCKETS),
       exactHandoffEmitted: emptyCounterMap(EFFECTIVENESS_BOOLEAN_BUCKETS),
-      scopeRelaxation: emptyCounterMap(EFFECTIVENESS_SCOPE_RELAXATION_BUCKETS)
+      scopeRelaxation: emptyCounterMap(EFFECTIVENESS_SCOPE_RELAXATION_BUCKETS),
+      routeOutcome: emptyRouteCounterMap(EFFECTIVENESS_TOOL_ROUTES, EFFECTIVENESS_OUTCOMES),
+      routeLatency: emptyRouteCounterMap(EFFECTIVENESS_TOOL_ROUTES, EFFECTIVENESS_LATENCY_BUCKETS),
+      routeResultCount: emptyRouteCounterMap(EFFECTIVENESS_TOOL_ROUTES, EFFECTIVENESS_RESULT_COUNT_BUCKETS),
+      routeReturnedTokenEstimate: emptyRouteCounterMap(
+        EFFECTIVENESS_TOOL_ROUTES,
+        EFFECTIVENESS_RETURNED_TOKEN_BUCKETS
+      )
     };
   }
   increment(counters, key) {
@@ -12340,12 +12440,19 @@ var EffectivenessMetrics = class {
     this.increment(this.snapshot.hostMode, host);
     this.increment(this.snapshot.outcome, outcome);
     this.increment(this.snapshot.recoveryUsed, recoveryUsed);
-    this.increment(this.snapshot.resultCount, resultCountBucket(event.resultCount));
-    this.increment(this.snapshot.latency, latencyBucket(event.latencyMs));
+    const resultCountBucketValue = resultCountBucket(event.resultCount);
+    const latencyBucketValue = latencyBucket(event.latencyMs);
+    const returnedTokenBucketValue = returnedTokenBucket(event.returnedTokenEstimate);
+    this.increment(this.snapshot.resultCount, resultCountBucketValue);
+    this.increment(this.snapshot.latency, latencyBucketValue);
     this.increment(this.snapshot.tokenBudget, tokenBudgetBucket(event.tokenBudget));
-    this.increment(this.snapshot.returnedTokenEstimate, returnedTokenBucket(event.returnedTokenEstimate));
+    this.increment(this.snapshot.returnedTokenEstimate, returnedTokenBucketValue);
     this.increment(this.snapshot.exactHandoffEmitted, exactHandoffEmitted);
     this.increment(this.snapshot.scopeRelaxation, scopeRelaxation);
+    this.increment(this.snapshot.routeOutcome[route], outcome);
+    this.increment(this.snapshot.routeLatency[route], latencyBucketValue);
+    this.increment(this.snapshot.routeResultCount[route], resultCountBucketValue);
+    this.increment(this.snapshot.routeReturnedTokenEstimate[route], returnedTokenBucketValue);
   }
   getSnapshot() {
     return {
@@ -12360,7 +12467,11 @@ var EffectivenessMetrics = class {
       tokenBudget: cloneCounterMap(this.snapshot.tokenBudget),
       returnedTokenEstimate: cloneCounterMap(this.snapshot.returnedTokenEstimate),
       exactHandoffEmitted: cloneCounterMap(this.snapshot.exactHandoffEmitted),
-      scopeRelaxation: cloneCounterMap(this.snapshot.scopeRelaxation)
+      scopeRelaxation: cloneCounterMap(this.snapshot.scopeRelaxation),
+      routeOutcome: cloneRouteCounterMap(this.snapshot.routeOutcome),
+      routeLatency: cloneRouteCounterMap(this.snapshot.routeLatency),
+      routeResultCount: cloneRouteCounterMap(this.snapshot.routeResultCount),
+      routeReturnedTokenEstimate: cloneRouteCounterMap(this.snapshot.routeReturnedTokenEstimate)
     };
   }
   reset() {
@@ -12379,6 +12490,7 @@ function resetProcessEffectivenessMetrics() {
 }
 function formatEffectivenessMetrics(snapshot) {
   const formatCounters = (counters) => Object.entries(counters).map(([bucket, count]) => `${bucket}=${count}`).join(", ");
+  const formatRouteCounters = (counters) => EFFECTIVENESS_TOOL_ROUTES.map((route) => `${route} => ${formatCounters(counters[route])}`).join("; ");
   const lines = [
     `Privacy-safe effectiveness (schema v${snapshot.schemaVersion}):`,
     `  Retention: ${snapshot.retention.storage}, ${snapshot.retention.lifetime}-lifetime; reset with index_metrics(reset=true) or process exit`,
@@ -12393,6 +12505,10 @@ function formatEffectivenessMetrics(snapshot) {
     `  Latency bucket: ${formatCounters(snapshot.latency)}`,
     `  Token-budget bucket: ${formatCounters(snapshot.tokenBudget)}`,
     `  Returned-token estimate: ${formatCounters(snapshot.returnedTokenEstimate)}`,
+    `  Route outcome buckets: ${formatRouteCounters(snapshot.routeOutcome)}`,
+    `  Route latency buckets: ${formatRouteCounters(snapshot.routeLatency)}`,
+    `  Route result-count buckets: ${formatRouteCounters(snapshot.routeResultCount)}`,
+    `  Route returned-token buckets: ${formatRouteCounters(snapshot.routeReturnedTokenEstimate)}`,
     `  Exact handoff emitted: ${formatCounters(snapshot.exactHandoffEmitted)}`,
     `  Scope relaxation: ${formatCounters(snapshot.scopeRelaxation)}`,
     "  Privacy: no queries, response text, source, symbols, paths, repository names, user identity, or stable identifiers are retained."
@@ -12404,6 +12520,103 @@ function formatEffectivenessMetrics(snapshot) {
 import { existsSync as existsSync8, realpathSync as realpathSync4 } from "fs";
 import * as os6 from "os";
 import * as path15 from "path";
+
+// src/utils/power-source.ts
+import * as childProcess from "child_process";
+var POWER_SOURCE_RECHECK_DELAY_MS = 6e4;
+var PMSET_TIMEOUT_MS = 5e3;
+function getErrorMessage4(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function runCommand(file, args, options) {
+  return new Promise((resolve17, reject) => {
+    childProcess.execFile(
+      file,
+      args,
+      { encoding: "utf8", timeout: options.timeoutMs },
+      (error, stdout) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve17(stdout);
+      }
+    );
+  });
+}
+function parseMacOsPowerSource(output) {
+  const match = output.match(/Now drawing from '([^']+)'/i);
+  if (!match) {
+    return "unknown";
+  }
+  const source = match[1].toLowerCase();
+  if (source === "battery power") {
+    return "battery";
+  }
+  if (source === "ac power") {
+    return "ac";
+  }
+  return "unknown";
+}
+async function readMacOsPowerSource(commandRunner = runCommand) {
+  const output = await commandRunner(
+    "/usr/bin/pmset",
+    ["-g", "batt"],
+    { timeoutMs: PMSET_TIMEOUT_MS }
+  );
+  return parseMacOsPowerSource(output);
+}
+var MacOsBackgroundIndexingPolicy = class {
+  constructor(readPowerSource, recheckDelayMs) {
+    this.readPowerSource = readPowerSource;
+    this.recheckDelayMs = recheckDelayMs;
+  }
+  readPowerSource;
+  recheckDelayMs;
+  lastPaused = null;
+  reportedFailure = false;
+  isPaused() {
+    return this.checkPowerSource();
+  }
+  async checkPowerSource() {
+    try {
+      const source = await this.readPowerSource();
+      if (source === "unknown") {
+        throw new Error("pmset returned an unrecognized power source");
+      }
+      this.reportedFailure = false;
+      const paused = source === "battery";
+      if (paused && this.lastPaused !== true) {
+        console.warn("[codebase-index] Background indexing paused while macOS is using battery power.");
+      } else if (!paused && this.lastPaused === true) {
+        console.warn("[codebase-index] AC power detected; resuming pending background indexing.");
+      }
+      this.lastPaused = paused;
+      return paused;
+    } catch (error) {
+      if (!this.reportedFailure) {
+        console.error(
+          `[codebase-index] Failed to determine the macOS power source; background indexing will continue: ${getErrorMessage4(error)}`
+        );
+        this.reportedFailure = true;
+      }
+      this.lastPaused = false;
+      return false;
+    }
+  }
+};
+function createBackgroundIndexingPolicy(pauseOnBattery, options = {}) {
+  const platform2 = options.platform ?? process.platform;
+  if (!pauseOnBattery || platform2 !== "darwin") {
+    return null;
+  }
+  return new MacOsBackgroundIndexingPolicy(
+    options.readPowerSource ?? readMacOsPowerSource,
+    options.recheckDelayMs ?? POWER_SOURCE_RECHECK_DELAY_MS
+  );
+}
+
+// src/utils/auto-index.ts
 var MAX_RETRY_DELAY_MS = 1e4;
 var SHUTDOWN_WAIT_MS = 2e3;
 var coordinators = /* @__PURE__ */ new Map();
@@ -12520,7 +12733,13 @@ var AutoIndexCoordinator = class {
   activation = Promise.resolve();
   inFlight = null;
   activeRequest = null;
+  batteryCheck = null;
+  batteryIndexJob = null;
+  batteryDeferredRequest = null;
+  batteryRetryTimer = null;
+  resolveBatteryRetry = null;
   pendingRequest = null;
+  pendingFollowUp = null;
   abortController = null;
   stopped = false;
   constructor(registration) {
@@ -12533,6 +12752,7 @@ var AutoIndexCoordinator = class {
     };
   }
   update(registration) {
+    const pauseOnBatteryChanged = registration.config.indexing.pauseBackgroundIndexingOnBattery !== this.registration.config.indexing.pauseBackgroundIndexingOnBattery;
     this.registration = registration;
     this.status.enabled = registration.config.indexing.autoIndex;
     this.status.blockedReason = registration.blockedReason;
@@ -12548,6 +12768,9 @@ var AutoIndexCoordinator = class {
         this.setState("idle", { source: void 0 });
       }
     }
+    if (pauseOnBatteryChanged) {
+      this.cancelBatteryRetry();
+    }
   }
   activateAfter(activation) {
     this.activation = activation;
@@ -12569,7 +12792,26 @@ var AutoIndexCoordinator = class {
     if (this.stopped) {
       return Promise.resolve({ outcome: "stopped" });
     }
-    return this.activation.then(() => this.enqueueRequest(request));
+    return this.activation.then(() => this.enqueueBatteryAwareRequest(request));
+  }
+  enqueueBatteryAwareRequest(request) {
+    if (!this.shouldDeferForBattery(request)) {
+      return this.enqueueRequest(request);
+    }
+    if (this.batteryCheck && this.batteryIndexJob !== null && this.batteryIndexJob === this.inFlight) {
+      return this.enqueueRequest(request);
+    }
+    this.batteryDeferredRequest = mergeRequests(this.batteryDeferredRequest, request);
+    if (this.batteryCheck) {
+      return this.batteryCheck;
+    }
+    const batteryCheck = this.waitForACPower();
+    this.batteryCheck = batteryCheck;
+    void batteryCheck.then(
+      () => this.finishBatteryCheck(batteryCheck),
+      () => this.finishBatteryCheck(batteryCheck)
+    );
+    return batteryCheck;
   }
   enqueueRequest(request) {
     if (this.stopped || !this.canRun(request)) {
@@ -12587,6 +12829,11 @@ var AutoIndexCoordinator = class {
       }
       if (request.source === "watcher") {
         this.pendingRequest = mergeRequests(this.pendingRequest, request);
+        const active = this.inFlight;
+        return active.then(() => {
+          if (this.stopped) return { outcome: "stopped" };
+          return this.pendingFollowUp ?? { outcome: "stopped" };
+        });
       }
       return this.inFlight;
     }
@@ -12603,6 +12850,8 @@ var AutoIndexCoordinator = class {
   }
   async stop(waitForCompletion = false) {
     this.stopped = true;
+    this.batteryDeferredRequest = null;
+    this.cancelBatteryRetry();
     this.pendingRequest = null;
     this.abortController?.abort();
     this.setState("stopped", {
@@ -12632,10 +12881,20 @@ var AutoIndexCoordinator = class {
       this.inFlight = null;
       this.activeRequest = null;
       this.abortController = null;
+      if (this.batteryIndexJob === job) {
+        this.batteryIndexJob = null;
+        this.batteryCheck = null;
+      }
       const pending = this.pendingRequest;
       this.pendingRequest = null;
       if (pending && !this.stopped) {
-        this.startRequest(pending);
+        const followUp = this.request(pending);
+        this.pendingFollowUp = followUp;
+        void followUp.then(() => {
+          if (this.pendingFollowUp === followUp) {
+            this.pendingFollowUp = null;
+          }
+        });
       }
     });
     return job;
@@ -12799,6 +13058,68 @@ var AutoIndexCoordinator = class {
     }
     return this.registration.safeToRun && this.registration.config.indexing.autoIndex;
   }
+  shouldDeferForBattery(request) {
+    return this.registration.backgroundIndexingPolicy !== null && (request.source === "startup" || request.source === "watcher");
+  }
+  async waitForACPower() {
+    while (!this.stopped) {
+      const policy = this.registration.backgroundIndexingPolicy;
+      if (!policy || !await this.isBatteryPauseActive(policy)) {
+        const request = this.batteryDeferredRequest;
+        this.batteryDeferredRequest = null;
+        if (!request) return { outcome: "stopped" };
+        const job = this.enqueueRequest(request);
+        if (this.inFlight === job) {
+          this.batteryIndexJob = job;
+        }
+        return job;
+      }
+      await this.waitForBatteryRetry(policy.recheckDelayMs);
+    }
+    return { outcome: "stopped" };
+  }
+  async isBatteryPauseActive(policy) {
+    try {
+      return await policy.isPaused();
+    } catch (error) {
+      console.error(
+        `[codebase-index] Failed to apply the background indexing power policy; background indexing will continue: ${safeFailureMessage(error)}`
+      );
+      return false;
+    }
+  }
+  waitForBatteryRetry(delayMs) {
+    return new Promise((resolve17) => {
+      const timer = setTimeout(() => {
+        if (this.batteryRetryTimer === timer) {
+          this.batteryRetryTimer = null;
+          this.resolveBatteryRetry = null;
+        }
+        resolve17();
+      }, delayMs);
+      timer.unref?.();
+      this.batteryRetryTimer = timer;
+      this.resolveBatteryRetry = resolve17;
+    });
+  }
+  cancelBatteryRetry() {
+    if (this.batteryRetryTimer) {
+      clearTimeout(this.batteryRetryTimer);
+      this.batteryRetryTimer = null;
+    }
+    const resolve17 = this.resolveBatteryRetry;
+    this.resolveBatteryRetry = null;
+    resolve17?.();
+  }
+  finishBatteryCheck(batteryCheck) {
+    if (this.batteryCheck !== batteryCheck) return;
+    this.batteryCheck = null;
+    const deferredRequest = this.batteryDeferredRequest;
+    this.batteryDeferredRequest = null;
+    if (deferredRequest && !this.stopped) {
+      void this.request(deferredRequest);
+    }
+  }
 };
 function getCoordinator(projectRoot, host) {
   const key = coordinatorKeysByProject.get(projectLookupKey(projectRoot, host));
@@ -12808,6 +13129,9 @@ function configureAutoIndex(projectRoot, host, config, getIndexer) {
   const projectKey = projectLookupKey(projectRoot, host);
   const safety = getProjectSafety(projectRoot, config);
   const registration = {
+    backgroundIndexingPolicy: createBackgroundIndexingPolicy(
+      config.indexing.pauseBackgroundIndexingOnBattery
+    ),
     config,
     getIndexer,
     projectRoot,
@@ -14031,6 +14355,7 @@ Explicit symbol lookup only; conceptual search was not attempted.`
     const results = await tryConceptualSearch(attempt.queryText, attempt.scope, attempt.relaxed);
     if (results.length > 0) {
       const heading = buildPackHeading("conceptual", decisions);
+      const intent = analyzeQueryIntent(attempt.queryText);
       return toResult(
         "conceptual",
         attempt.queryText,
@@ -14038,7 +14363,8 @@ Explicit symbol lookup only; conceptual search was not attempted.`
           tokenBudget,
           maxResults: limit,
           heading,
-          includeExactSearchHandoff: true
+          includeExactSearchHandoff: true,
+          preferImplementationPaths: intent.preferSourcePaths || intent.primary !== "docs" && intent.primary !== "test"
         })
       );
     }
@@ -14339,17 +14665,26 @@ function percentile(values, p) {
 function normalizePath2(input) {
   return normalizePathSeparators(input);
 }
-function uniqueResultsByPath(results) {
+function uniqueResultsByEvidence(results) {
   const seen = /* @__PURE__ */ new Set();
   const unique = [];
   for (const result of results) {
-    const normalized = normalizePath2(result.filePath);
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
+    const key = `${normalizePath2(result.filePath)}::${result.name ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
     unique.push(result);
   }
   return unique;
 }
+function uniqueResultsByPath(results) {
+  const seen = /* @__PURE__ */ new Set();
+  return results.filter((result) => {
+    const key = normalizePath2(result.filePath);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
 function distinctTopKRatio(results, k) {
   const top = results.slice(0, k);
   if (top.length === 0) return 0;
@@ -14360,60 +14695,169 @@ function pathMatchesExpected(actualPath, expectedPath) {
   const actual = normalizePath2(actualPath);
   const expected = normalizePath2(expectedPath);
   if (actual === expected) return true;
-  return actual.endsWith(`/${expected}`) || expected.endsWith(`/${actual}`);
+  return actual.endsWith(`/${expected}`);
+}
+function getRelevantEvidence(query) {
+  const legacyEvidence = [];
+  if (query.expected.filePath !== void 0) {
+    legacyEvidence.push({
+      path: query.expected.filePath,
+      ...query.expected.symbol !== void 0 ? { symbol: query.expected.symbol } : {},
+      relevance: 1
+    });
+  }
+  if (query.expected.acceptableFiles) {
+    for (const path29 of query.expected.acceptableFiles) {
+      legacyEvidence.push({
+        path: path29,
+        ...query.expected.symbol !== void 0 ? { symbol: query.expected.symbol } : {},
+        relevance: 1
+      });
+    }
+  }
+  const gradedEvidence = query.expected.gradedEvidence ?? [];
+  const allEvidence = [...legacyEvidence, ...gradedEvidence];
+  const dedupeKey = (entry) => {
+    return `${normalizePath2(entry.path)}::${entry.symbol ?? ""}`;
+  };
+  const unique = /* @__PURE__ */ new Map();
+  for (const entry of allEvidence) {
+    unique.set(dedupeKey(entry), entry);
+  }
+  return Array.from(unique.values());
+}
+function hasSymbolRequirement(query) {
+  return isSymbolIntended(query);
+}
+function isSymbolIntended(query) {
+  return query.expected.symbol !== void 0 || query.args?.symbol !== void 0 || query.expected.gradedEvidence?.some((entry) => entry.symbol !== void 0) === true;
+}
+function isExpectedFile(filePath, relevant) {
+  return relevant.some((entry) => pathMatchesExpected(filePath, entry.path));
+}
+function resultRelevance(filePath, symbol, relevant, isSymbolIntendedQuery) {
+  let relevance = 0;
+  for (const entry of relevant) {
+    if (!pathMatchesExpected(filePath, entry.path)) {
+      continue;
+    }
+    if (isSymbolIntendedQuery) {
+      if (symbol === void 0 || entry.symbol === void 0 || symbol !== entry.symbol) {
+        continue;
+      }
+    } else if (entry.symbol !== void 0 && symbol !== void 0 && symbol !== entry.symbol) {
+      continue;
+    }
+    if (entry.symbol === void 0) {
+      relevance = Math.max(relevance, entry.relevance);
+      continue;
+    }
+    if (isSymbolIntendedQuery && entry.symbol !== void 0 && symbol === entry.symbol) {
+      relevance = Math.max(relevance, entry.relevance);
+      continue;
+    }
+    if (!isSymbolIntendedQuery && symbol !== void 0 && symbol === entry.symbol) {
+      relevance = Math.max(relevance, entry.relevance);
+    }
+  }
+  return relevance;
 }
-function getRelevantPaths(query) {
-  const fromExact = query.expected.filePath ? [query.expected.filePath] : [];
-  const fromAcceptable = query.expected.acceptableFiles ?? [];
-  return Array.from(/* @__PURE__ */ new Set([...fromExact, ...fromAcceptable]));
+function isRelevantResult(filePath, symbol, relevant, isSymbolIntendedQuery) {
+  return resultRelevance(filePath, symbol, relevant, isSymbolIntendedQuery) > 0;
+}
+function evidenceMatchesResult(entry, filePath, symbol, isSymbolIntendedQuery) {
+  if (!pathMatchesExpected(filePath, entry.path)) {
+    return false;
+  }
+  if (isSymbolIntendedQuery) {
+    return entry.symbol !== void 0 && symbol === entry.symbol;
+  }
+  return entry.symbol === void 0 || symbol === entry.symbol;
 }
-function isRelevantResult(filePath, relevantPaths) {
-  return relevantPaths.some((expected) => pathMatchesExpected(filePath, expected));
+function hasGradeBasedEvidence(query) {
+  return (query.expected.gradedEvidence?.length ?? 0) > 0;
 }
-function reciprocalRankAtK(results, relevantPaths, k) {
-  const top = uniqueResultsByPath(results).slice(0, k);
+function dedupeRelevantEvidence(relevant) {
+  const deduped = /* @__PURE__ */ new Map();
+  for (const entry of relevant) {
+    const key = `${normalizePath2(entry.path)}::${entry.symbol ?? ""}`;
+    if (!deduped.has(key)) {
+      deduped.set(key, entry);
+    }
+  }
+  return [...deduped.values()];
+}
+function reciprocalRankAtK(results, relevant, isSymbolIntendedQuery, k) {
+  const top = uniqueResultsByEvidence(results).slice(0, k);
   for (let i = 0; i < top.length; i += 1) {
-    if (isRelevantResult(top[i].filePath, relevantPaths)) {
+    if (isRelevantResult(top[i].filePath, top[i].name, relevant, isSymbolIntendedQuery)) {
       return 1 / (i + 1);
     }
   }
   return 0;
 }
-function ndcgAtK(results, relevantPaths, k) {
-  const top = uniqueResultsByPath(results).slice(0, k);
+function ndcgAtK(query, results, relevant, isSymbolIntendedQuery, k) {
+  const top = uniqueResultsByEvidence(results).slice(0, k);
+  const availableEvidence = dedupeRelevantEvidence(relevant).filter(
+    (entry) => !isSymbolIntendedQuery || entry.symbol !== void 0
+  );
   const dcg = top.reduce((sum, result, i) => {
-    const rel = isRelevantResult(result.filePath, relevantPaths) ? 1 : 0;
-    return sum + rel / Math.log2(i + 2);
+    let bestEvidenceIndex = -1;
+    let rel = 0;
+    for (let evidenceIndex = 0; evidenceIndex < availableEvidence.length; evidenceIndex += 1) {
+      const entry = availableEvidence[evidenceIndex];
+      if (entry.relevance > rel && evidenceMatchesResult(entry, result.filePath, result.name, isSymbolIntendedQuery)) {
+        bestEvidenceIndex = evidenceIndex;
+        rel = entry.relevance;
+      }
+    }
+    if (bestEvidenceIndex < 0) {
+      return sum;
+    }
+    availableEvidence.splice(bestEvidenceIndex, 1);
+    return sum + (2 ** rel - 1) / Math.log2(i + 2);
   }, 0);
-  const idealLen = Math.min(k, relevantPaths.length);
-  const idcg = Array.from({ length: idealLen }, (_, i) => 1 / Math.log2(i + 2)).reduce(
-    (sum, value) => sum + value,
+  const dedupedRelevant = dedupeRelevantEvidence(relevant).filter(
+    (entry) => !isSymbolIntendedQuery || entry.symbol !== void 0
+  );
+  const idealRelevances = hasGradeBasedEvidence(query) ? dedupedRelevant.map((entry) => entry.relevance).sort((a, b) => b - a).slice(0, k) : relevant.length > 0 ? [1] : [];
+  const idcg = idealRelevances.reduce(
+    (sum, rel, index) => sum + (2 ** rel - 1) / Math.log2(index + 2),
     0
   );
-  return idcg === 0 ? 0 : dcg / idcg;
+  if (idcg === 0) {
+    return 0;
+  }
+  const ndcg = dcg / idcg;
+  if (ndcg <= 0) {
+    return 0;
+  }
+  return ndcg > 1 ? 1 : ndcg;
 }
 function isDocsOrTestsPath(filePath) {
   const lowered = normalizePath2(filePath).toLowerCase();
   return lowered.includes("/docs/") || lowered.includes("/test/") || lowered.includes("/tests/") || lowered.includes("readme") || lowered.includes("/benchmarks/");
 }
 function classifyFailureBucket(query, results, k) {
-  const relevantPaths = getRelevantPaths(query);
-  const top = uniqueResultsByPath(results).slice(0, k);
-  const hasRelevantTopK = top.some((result) => isRelevantResult(result.filePath, relevantPaths));
+  const relevant = getRelevantEvidence(query);
+  const isSymbolIntendedQuery = isSymbolIntended(query);
+  if (query.expected.expectedOutcome === "no-results") return void 0;
+  const top = uniqueResultsByEvidence(results).slice(0, k);
+  const hasRelevantTopK = top.some(
+    (result) => isRelevantResult(result.filePath, result.name, relevant, isSymbolIntendedQuery)
+  );
   if (!hasRelevantTopK) {
+    const hasExpectedFileTopK = top.some((result) => isExpectedFile(result.filePath, relevant));
+    if (hasExpectedFileTopK && hasSymbolRequirement(query)) {
+      return "wrong-symbol";
+    }
     return "no-relevant-hit-top-k";
   }
-  if (query.expected.symbol) {
-    const hasSymbol = top.some(
-      (result) => isRelevantResult(result.filePath, relevantPaths) && result.name === query.expected.symbol
-    );
-    if (!hasSymbol) return "wrong-symbol";
-  }
   const top1 = top[0];
-  if (top1 && !isRelevantResult(top1.filePath, relevantPaths) && isDocsOrTestsPath(top1.filePath)) {
+  if (top1 && !isExpectedFile(top1.filePath, relevant) && isDocsOrTestsPath(top1.filePath)) {
     return "docs-tests-outranking-source";
   }
-  if (top1 && !isRelevantResult(top1.filePath, relevantPaths)) {
+  if (top1 && !isExpectedFile(top1.filePath, relevant)) {
     return "wrong-file";
   }
   return void 0;
@@ -14422,9 +14866,12 @@ function buildPerQueryResult(query, results, latencyMs, k, route = {
   resolvedRoute: "search",
   routedQuery: query.query
 }, context) {
-  const relevantPaths = getRelevantPaths(query);
-  const deduped = uniqueResultsByPath(results);
-  const hitAt = (cutoff) => deduped.slice(0, cutoff).some((result) => isRelevantResult(result.filePath, relevantPaths));
+  const relevant = getRelevantEvidence(query);
+  const isSymbolIntendedQuery = isSymbolIntended(query);
+  const deduped = uniqueResultsByEvidence(results);
+  const hitAt = (cutoff) => deduped.slice(0, cutoff).some(
+    (result) => isRelevantResult(result.filePath, result.name, relevant, isSymbolIntendedQuery)
+  );
   const perQuery = {
     id: query.id,
     query: query.query,
@@ -14432,13 +14879,19 @@ function buildPerQueryResult(query, results, latencyMs, k, route = {
     retrievalMode: query.retrievalMode ?? "search",
     resolvedRoute: route.resolvedRoute,
     routedQuery: route.routedQuery,
+    routeMatched: query.expected.expectedRoute ? query.expected.expectedRoute === route.resolvedRoute : void 0,
+    outcomeMatched: query.expected.expectedOutcome === void 0 ? void 0 : query.expected.expectedOutcome === "results" ? deduped.length > 0 : deduped.length === 0,
+    recoveryMatched: query.expected.recoveryExpectation === void 0 ? void 0 : query.expected.recoveryExpectation === "filter-relaxed" ? context?.recoveryRelaxed === true : context?.recoveryUsed !== true,
+    language: query.language,
+    difficulty: query.difficulty,
+    tags: query.tags,
     latencyMs,
     hitAt1: hitAt(1),
     hitAt3: hitAt(3),
     hitAt5: hitAt(5),
     hitAt10: hitAt(10),
-    reciprocalRankAt10: reciprocalRankAtK(deduped, relevantPaths, 10),
-    ndcgAt10: ndcgAtK(deduped, relevantPaths, 10),
+    reciprocalRankAt10: reciprocalRankAtK(deduped, relevant, isSymbolIntendedQuery, 10),
+    ndcgAt10: ndcgAtK(query, deduped, relevant, isSymbolIntendedQuery, 10),
     failureBucket: classifyFailureBucket(query, results, k),
     rawTop3DistinctRatio: distinctTopKRatio(results, 3),
     tokenBudget: context?.tokenBudget,
@@ -14456,6 +14909,11 @@ function buildPerQueryResult(query, results, latencyMs, k, route = {
 function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingTokensUsed, costPer1MTokensUsd) {
   const count = perQuery.length;
   const safeDiv = (value) => count === 0 ? 0 : value / count;
+  const positiveQueryIds = new Set(
+    queries.filter((query) => query.expected.expectedOutcome !== "no-results").map((query) => query.id)
+  );
+  const positiveCount = perQuery.filter((query) => positiveQueryIds.has(query.id)).length;
+  const safePositiveDiv = (value) => positiveCount === 0 ? 0 : value / positiveCount;
   const sum = {
     hitAt1: 0,
     hitAt3: 0,
@@ -14477,27 +14935,52 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
   const contextResponseTokens = contextQueries.map((item) => item.responseTokens);
   const totalContextResponseTokens = contextResponseTokens.reduce((sum2, value) => sum2 + value, 0);
   const contextTokenUnits = totalContextResponseTokens / 1e3;
+  let routeMatchedCount = 0;
+  let routeExpectedCount = 0;
+  let outcomeMatchedCount = 0;
+  let outcomeExpectedCount = 0;
+  let recoveryMatchedCount = 0;
+  let recoveryExpectedCount = 0;
   for (const query of perQuery) {
-    if (query.hitAt1) sum.hitAt1 += 1;
-    if (query.hitAt3) sum.hitAt3 += 1;
-    if (query.hitAt5) sum.hitAt5 += 1;
-    if (query.hitAt10) sum.hitAt10 += 1;
-    sum.mrrAt10 += query.reciprocalRankAt10;
-    sum.ndcgAt10 += query.ndcgAt10;
-    sum.distinctTop3Ratio += distinctTopKRatio(query.results, 3);
+    if (positiveQueryIds.has(query.id)) {
+      if (query.hitAt1) sum.hitAt1 += 1;
+      if (query.hitAt3) sum.hitAt3 += 1;
+      if (query.hitAt5) sum.hitAt5 += 1;
+      if (query.hitAt10) sum.hitAt10 += 1;
+      sum.mrrAt10 += query.reciprocalRankAt10;
+      sum.ndcgAt10 += query.ndcgAt10;
+    }
+    sum.distinctTop3Ratio += distinctTopKRatio(uniqueResultsByPath(query.results), 3);
     sum.rawDistinctTop3Ratio += query.rawTop3DistinctRatio;
     if (query.failureBucket) {
       failureBuckets[query.failureBucket] += 1;
     }
+    if (query.routeMatched !== void 0) {
+      routeExpectedCount += 1;
+      if (query.routeMatched) {
+        routeMatchedCount += 1;
+      }
+    }
+    if (query.outcomeMatched !== void 0) {
+      outcomeExpectedCount += 1;
+      if (query.outcomeMatched) outcomeMatchedCount += 1;
+    }
+    if (query.recoveryMatched !== void 0) {
+      recoveryExpectedCount += 1;
+      if (query.recoveryMatched) recoveryMatchedCount += 1;
+    }
   }
   const queryTokens = queries.reduce((acc, q) => acc + estimateTokens(q.query), 0);
   return {
-    hitAt1: safeDiv(sum.hitAt1),
-    hitAt3: safeDiv(sum.hitAt3),
-    hitAt5: safeDiv(sum.hitAt5),
-    hitAt10: safeDiv(sum.hitAt10),
-    mrrAt10: safeDiv(sum.mrrAt10),
-    ndcgAt10: safeDiv(sum.ndcgAt10),
+    hitAt1: safePositiveDiv(sum.hitAt1),
+    hitAt3: safePositiveDiv(sum.hitAt3),
+    hitAt5: safePositiveDiv(sum.hitAt5),
+    hitAt10: safePositiveDiv(sum.hitAt10),
+    mrrAt10: safePositiveDiv(sum.mrrAt10),
+    ndcgAt10: safePositiveDiv(sum.ndcgAt10),
+    routeAccuracy: routeExpectedCount === 0 ? 0 : routeMatchedCount / routeExpectedCount,
+    outcomeAccuracy: outcomeExpectedCount === 0 ? 0 : outcomeMatchedCount / outcomeExpectedCount,
+    recoveryAccuracy: recoveryExpectedCount === 0 ? 0 : recoveryMatchedCount / recoveryExpectedCount,
     distinctTop3Ratio: safeDiv(sum.distinctTop3Ratio),
     rawDistinctTop3Ratio: safeDiv(sum.rawDistinctTop3Ratio),
     latencyMs: {
@@ -14704,6 +15187,9 @@ function isRecord3(value) {
 function isStringArray4(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
 function asPositiveNumber(value, path29) {
   if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
     throw new Error(`${path29} must be a non-negative number`);
@@ -14718,11 +15204,109 @@ function parseQueryType(value, path29) {
     `${path29} must be one of: definition, implementation-intent, similarity, keyword-heavy, conceptual`
   );
 }
+function parseExpectedRoute(value, path29) {
+  if (value === void 0) return void 0;
+  if (value === "search" || value === "definition") return value;
+  throw new Error(`${path29} must be one of: search, definition`);
+}
+function parseExpectedOutcome(value, path29) {
+  if (value === void 0) return void 0;
+  if (value === "results" || value === "no-results") {
+    return value;
+  }
+  throw new Error(`${path29} must be one of: results, no-results`);
+}
+function parseRecoveryExpectation(value, path29) {
+  if (value === void 0) return void 0;
+  if (value === "none" || value === "filter-relaxed") {
+    return value;
+  }
+  throw new Error(`${path29} must be one of: none, filter-relaxed`);
+}
+function parseQueryDifficulty(value, path29) {
+  if (value === void 0) return void 0;
+  if (value === "easy" || value === "medium" || value === "hard") {
+    return value;
+  }
+  throw new Error(`${path29} must be one of: easy, medium, hard`);
+}
+function parseQueryTags(value, path29) {
+  if (value === void 0) return void 0;
+  if (!isStringArray4(value) || value.some((tag) => tag.trim().length === 0)) {
+    throw new Error(`${path29} must be an array of non-empty strings`);
+  }
+  if (value.length > 16) {
+    throw new Error(`${path29} must contain at most 16 tags`);
+  }
+  return value;
+}
+function parseQueryArgs(value, path29) {
+  if (value === void 0) return void 0;
+  if (!isRecord3(value)) {
+    throw new Error(`${path29} must be an object`);
+  }
+  const symbol = parseStringOrUndefined(value.symbol, `${path29}.symbol`);
+  const fileType = parseStringOrUndefined(value.fileType, `${path29}.fileType`);
+  const directory = parseStringOrUndefined(value.directory, `${path29}.directory`);
+  return {
+    ...symbol !== void 0 ? { symbol } : {},
+    ...fileType !== void 0 ? { fileType } : {},
+    ...directory !== void 0 ? { directory } : {}
+  };
+}
+var SEMVER_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function parseSemanticVersion(value, path29) {
+  if (!isNonEmptyString(value)) {
+    throw new Error(`${path29} must be a non-empty string`);
+  }
+  if (!SEMVER_VERSION_PATTERN.test(value)) {
+    throw new Error(`${path29} must be a valid semantic version (MAJOR.MINOR.PATCH)`);
+  }
+  return value;
+}
 function parseRetrievalMode(value, path29) {
   if (value === void 0 || value === "search") return "search";
   if (value === "context") return value;
   throw new Error(`${path29} must be one of: search, context`);
 }
+function parseStringOrUndefined(value, path29) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isNonEmptyString(value)) {
+    throw new Error(`${path29} must be a non-empty string`);
+  }
+  return value;
+}
+function parseGradedEvidence(value, path29) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${path29} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (!isRecord3(entry)) {
+      throw new Error(`${path29}[${index}] must be an object`);
+    }
+    const evidencePath = parseStringOrUndefined(entry.path, `${path29}[${index}].path`);
+    if (evidencePath === void 0) {
+      throw new Error(`${path29}[${index}].path is required`);
+    }
+    const symbol = parseStringOrUndefined(entry.symbol, `${path29}[${index}].symbol`);
+    const relevance = parseEvidenceRelevance(entry.relevance, `${path29}[${index}].relevance`);
+    return {
+      path: evidencePath,
+      ...symbol !== void 0 ? { symbol } : {},
+      relevance
+    };
+  });
+}
+function parseEvidenceRelevance(value, path29) {
+  if (value === void 0) {
+    throw new Error(`${path29} is required`);
+  }
+  if (value !== 1 && value !== 2 && value !== 3) {
+    throw new Error(`${path29} must be 1, 2, or 3`);
+  }
+  return value;
+}
 function parseExpected(input, path29) {
   if (!isRecord3(input)) {
     throw new Error(`${path29} must be an object`);
@@ -14731,10 +15315,18 @@ function parseExpected(input, path29) {
   const acceptableFilesRaw = input.acceptableFiles;
   const symbolRaw = input.symbol;
   const branchRaw = input.branch;
-  const filePath = typeof filePathRaw === "string" ? filePathRaw : void 0;
+  const expectedRouteRaw = input.expectedRoute;
+  const expectedOutcomeRaw = input.expectedOutcome;
+  const recoveryExpectationRaw = input.recoveryExpectation;
+  const gradedEvidenceRaw = input.gradedEvidence;
+  const filePath = parseStringOrUndefined(filePathRaw, `${path29}.filePath`);
   const acceptableFiles = isStringArray4(acceptableFilesRaw) ? acceptableFilesRaw : void 0;
-  if (!filePath && (!acceptableFiles || acceptableFiles.length === 0)) {
-    throw new Error(`${path29} must include either expected.filePath or expected.acceptableFiles`);
+  const gradedEvidence = parseGradedEvidence(gradedEvidenceRaw, `${path29}.gradedEvidence`);
+  const expectedOutcome = parseExpectedOutcome(expectedOutcomeRaw, `${path29}.expectedOutcome`);
+  if (expectedOutcome !== "no-results" && !filePath && (!acceptableFiles || acceptableFiles.length === 0) && gradedEvidence.length === 0) {
+    throw new Error(
+      `${path29} must include expected.filePath, expected.acceptableFiles, or expected.gradedEvidence`
+    );
   }
   if (acceptableFilesRaw !== void 0 && !isStringArray4(acceptableFilesRaw)) {
     throw new Error(`${path29}.acceptableFiles must be an array of strings`);
@@ -14745,13 +15337,25 @@ function parseExpected(input, path29) {
   if (branchRaw !== void 0 && typeof branchRaw !== "string") {
     throw new Error(`${path29}.branch must be a string when provided`);
   }
+  const expectedRoute = parseExpectedRoute(expectedRouteRaw, `${path29}.expectedRoute`);
+  const recoveryExpectation = parseRecoveryExpectation(
+    recoveryExpectationRaw,
+    `${path29}.recoveryExpectation`
+  );
   return {
     filePath,
     acceptableFiles,
     symbol: typeof symbolRaw === "string" ? symbolRaw : void 0,
-    branch: typeof branchRaw === "string" ? branchRaw : void 0
+    branch: typeof branchRaw === "string" ? branchRaw : void 0,
+    expectedRoute,
+    expectedOutcome,
+    recoveryExpectation,
+    ...gradedEvidence.length > 0 ? { gradedEvidence } : {}
   };
 }
+function parseQueryLanguage(value, path29) {
+  return parseStringOrUndefined(value, path29);
+}
 function parseQuery(input, index) {
   const path29 = `queries[${index}]`;
   if (!isRecord3(input)) {
@@ -14762,6 +15366,10 @@ function parseQuery(input, index) {
   const queryType = input.queryType;
   const retrievalMode = input.retrievalMode;
   const expected = input.expected;
+  const language = input.language;
+  const difficulty = input.difficulty;
+  const tags = input.tags;
+  const args = input.args;
   if (typeof id !== "string" || id.trim().length === 0) {
     throw new Error(`${path29}.id must be a non-empty string`);
   }
@@ -14773,6 +15381,10 @@ function parseQuery(input, index) {
     query,
     queryType: parseQueryType(queryType, `${path29}.queryType`),
     retrievalMode: parseRetrievalMode(retrievalMode, `${path29}.retrievalMode`),
+    language: parseQueryLanguage(language, `${path29}.language`),
+    difficulty: parseQueryDifficulty(difficulty, `${path29}.difficulty`),
+    args: parseQueryArgs(args, `${path29}.args`),
+    tags: parseQueryTags(tags, `${path29}.tags`),
     expected: parseExpected(expected, `${path29}.expected`)
   };
 }
@@ -14784,9 +15396,7 @@ function parseGoldenDataset(raw, sourceLabel) {
   const name = raw.name;
   const description = raw.description;
   const queriesRaw = raw.queries;
-  if (typeof version !== "string" || version.trim().length === 0) {
-    throw new Error(`${sourceLabel}.version must be a non-empty string`);
-  }
+  const validatedVersion = parseSemanticVersion(version, `${sourceLabel}.version`);
   if (typeof name !== "string" || name.trim().length === 0) {
     throw new Error(`${sourceLabel}.name must be a non-empty string`);
   }
@@ -14808,7 +15418,7 @@ function parseGoldenDataset(raw, sourceLabel) {
     idSet.add(query.id);
   }
   return {
-    version,
+    version: validatedVersion,
     name,
     description: typeof description === "string" ? description : void 0,
     queries
@@ -14868,16 +15478,8 @@ function parseBudget(raw, sourceLabel) {
         "p95LatencyMaxAbsoluteMs",
         sourceLabel
       ),
-      minHitAt5: parseThresholdValue(
-        thresholds.minHitAt5,
-        "minHitAt5",
-        sourceLabel
-      ),
-      minMrrAt10: parseThresholdValue(
-        thresholds.minMrrAt10,
-        "minMrrAt10",
-        sourceLabel
-      ),
+      minHitAt5: parseThresholdValue(thresholds.minHitAt5, "minHitAt5", sourceLabel),
+      minMrrAt10: parseThresholdValue(thresholds.minMrrAt10, "minMrrAt10", sourceLabel),
       minRawDistinctTop3Ratio: parseThresholdValue(
         thresholds.minRawDistinctTop3Ratio,
         "minRawDistinctTop3Ratio",
@@ -14927,6 +15529,26 @@ function loadBudget(budgetPath) {
 }
 
 // src/eval/runner.ts
+function normalizeForFingerprint(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeForFingerprint(entry));
+  }
+  if (value && typeof value === "object") {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const normalizedValue = normalizeForFingerprint(value[key]);
+      if (normalizedValue !== void 0) {
+        normalized[key] = normalizedValue;
+      }
+    }
+    return normalized;
+  }
+  return value;
+}
+function buildDatasetFingerprint(dataset) {
+  const canonical = JSON.stringify(normalizeForFingerprint(dataset));
+  return crypto.createHash("sha256").update(canonical).digest("hex");
+}
 async function runEvaluation(options) {
   const datasetPath = toAbsolute(options.projectRoot, options.datasetPath);
   const againstPath = options.againstPath ? toAbsolute(options.projectRoot, options.againstPath) : void 0;
@@ -14951,27 +15573,40 @@ async function runEvaluation(options) {
       const start = performance3.now();
       const contextResult = query.retrievalMode === "context" ? await resolveSearchContext({
         query: query.query,
+        symbol: query.args?.symbol,
+        fileType: query.args?.fileType,
+        directory: query.args?.directory,
         limit: 10,
         tokenBudget: DEFAULT_CONTEXT_PACK_TOKEN_BUDGET
       }, {
-        lookup: (symbol, limit, _scope) => indexer.search(symbol, limit, {
+        lookup: (symbol, limit, scope) => indexer.search(symbol, limit, {
           metadataOnly: true,
           filterByBranch: !!query.expected.branch,
-          definitionIntent: true
+          definitionIntent: true,
+          fileType: scope.fileType,
+          directory: scope.directory
         }),
-        search: (searchQuery, limit, _scope) => indexer.search(searchQuery, limit, {
+        search: (searchQuery, limit, scope) => indexer.search(searchQuery, limit, {
           metadataOnly: true,
           filterByBranch: !!query.expected.branch,
-          definitionIntent: false
+          definitionIntent: false,
+          fileType: scope.fileType,
+          directory: scope.directory
         })
       }) : void 0;
       const result = contextResult?.details?.results ?? await indexer.search(query.query, 10, {
         metadataOnly: true,
-        filterByBranch: !!query.expected.branch
+        filterByBranch: !!query.expected.branch,
+        fileType: query.args?.fileType,
+        directory: query.args?.directory
       });
       const elapsed = performance3.now() - start;
       const resolvedRoute = contextResult?.details?.route === "definition" ? "definition" : "search";
       const routedQuery = contextResult?.details?.routedQuery ?? query.query;
+      const successfulRecoveryAttempt = contextResult?.details?.recovery?.successfulAttemptIndex;
+      const recoveryAttempts = contextResult?.details?.recovery?.attempts ?? [];
+      const recoveryRelaxed = successfulRecoveryAttempt === void 0 ? false : (recoveryAttempts[successfulRecoveryAttempt]?.relaxedFields.length ?? 0) > 0;
+      const recoveryUsed = recoveryAttempts.length > 1 || recoveryAttempts.some((attempt) => attempt.relaxedFields.length > 0);
       const materialized = result.map((item) => ({
         filePath: item.filePath,
         startLine: item.startLine,
@@ -14988,7 +15623,9 @@ async function runEvaluation(options) {
         responseTokens: contextResult.details.tokenEstimate,
         candidateCount: contextResult.details.candidateCount ?? 0,
         deduplicatedCount: contextResult.details.deduplicatedCount ?? 0,
-        omittedCount: contextResult.details.omittedCount ?? 0
+        omittedCount: contextResult.details.omittedCount ?? 0,
+        recoveryUsed,
+        recoveryRelaxed
       } : void 0));
     }
     const logger = indexer.getLogger();
@@ -15000,6 +15637,7 @@ async function runEvaluation(options) {
       datasetPath,
       datasetName: dataset.name,
       datasetVersion: dataset.version,
+      datasetFingerprint: buildDatasetFingerprint(dataset),
       queryCount: dataset.queries.length,
       topK: 10,
       searchConfig: {
@@ -17916,7 +18554,10 @@ function createWatcherWithIndexer(getIndexer, projectRoot, config, host = "openc
   if (isGitRepo(projectRoot)) {
     gitWatcher = new GitHeadWatcher(projectRoot);
     gitWatcher.start(async (oldBranch, newBranch) => {
-      console.log(`Branch changed: ${oldBranch ?? "(none)"} -> ${newBranch}`);
+      getIndexer().getLogger().branch("info", "Branch changed", {
+        oldBranch,
+        newBranch
+      });
       requestReindex();
     });
   }