opencode-codebase-index 0.19.1 → 0.20.0

package/dist/pi-extension.cjs

@@ -786,6 +786,7 @@ function getDefaultIndexingConfig() {
     autoIndexMaxRetries: 5,
     autoIndexRetryDelayMs: 100,
     watchFiles: true,
+    pauseBackgroundIndexingOnBattery: false,
     maxFileSize: 1048576,
     maxChunksPerFile: 100,
     semanticOnly: false,
@@ -917,6 +918,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,
@@ -3996,9 +3998,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,
@@ -6515,6 +6529,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) {
@@ -6816,7 +6831,7 @@ function classifyQueryIntentRaw(query) {
   return "neutral";
 }
 function isImplementationChunkType(chunkType) {
-  return [
+  return CALL_GRAPH_SYMBOL_CHUNK_TYPES.has(chunkType) || [
     "export_statement",
     "function",
     "function_declaration",
@@ -7261,7 +7276,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 [];
   }
@@ -7275,14 +7290,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;
@@ -7304,6 +7319,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
         }
       });
     }
+    return true;
   };
   const normalizedHints = identifierHints.flatMap((hint) => [
     hint,
@@ -7325,12 +7341,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();
@@ -7338,6 +7388,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);
     }
   }
@@ -7879,6 +7932,10 @@ var Indexer = class _Indexer {
     const projectHash = hashContent(path12.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";
   }
@@ -9222,7 +9279,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);
@@ -9281,6 +9339,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) => path12.extname(filePath).toLowerCase() === ".swift"
     )) {
@@ -9324,7 +9384,7 @@ var Indexer = class _Indexer {
       );
       const requiresSwiftParserUpgrade = reparseCachedSwiftFiles && path12.extname(canonicalPath).toLowerCase() === ".swift";
       const requiresMetalParserUpgrade = reparseCachedMetalFiles && path12.extname(canonicalPath).toLowerCase() === ".metal";
-      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade) {
+      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade && !refreshCachedSymbols) {
         unchangedFilePaths.add(canonicalPath);
         this.logger.recordCacheHit();
       } else {
@@ -9535,37 +9595,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();
@@ -9681,6 +9731,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 };
@@ -9717,6 +9768,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 };
@@ -9996,6 +10048,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 };
@@ -10134,10 +10187,11 @@ var Indexer = class _Indexer {
     const keywordResults = await this.keywordSearch(query, maxResults * 4, store, invertedIndex);
     const keywordMs = import_perf_hooks.performance.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 = import_perf_hooks.performance.now();
     const shouldPrefilterByBranch = branchChunkIds !== null && (this.config.scope === "global" || branchChunkIds.size > 0);
@@ -10209,6 +10263,7 @@ var Indexer = class _Indexer {
       query,
       database,
       branchChunkIds,
+      branchSymbolIds,
       maxResults,
       union,
       sourceIntent
@@ -10222,7 +10277,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 = import_perf_hooks.performance.now() - searchStartTime;
     this.logger.recordSearch(totalSearchMs, {
@@ -10379,7 +10434,7 @@ var Indexer = class _Indexer {
       const extension = path12.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)) {
@@ -11087,7 +11142,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.");
       }
@@ -11429,8 +11487,17 @@ function fitTextToContextBudget(text3, 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();
@@ -11519,7 +11586,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);
@@ -11891,7 +11963,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",
@@ -11937,6 +12009,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));
@@ -11985,6 +12060,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;
@@ -12000,7 +12080,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),
@@ -12012,7 +12092,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) {
@@ -12034,12 +12121,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 {
@@ -12054,7 +12148,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() {
@@ -12073,6 +12171,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`,
@@ -12087,6 +12186,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."
@@ -12098,6 +12201,103 @@ function formatEffectivenessMetrics(snapshot) {
 var import_fs10 = require("fs");
 var os6 = __toESM(require("os"), 1);
 var path14 = __toESM(require("path"), 1);
+
+// src/utils/power-source.ts
+var childProcess = __toESM(require("child_process"), 1);
+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((resolve12, reject) => {
+    childProcess.execFile(
+      file,
+      args,
+      { encoding: "utf8", timeout: options.timeoutMs },
+      (error, stdout) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve12(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();
@@ -12214,7 +12414,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) {
@@ -12227,6 +12433,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;
@@ -12242,6 +12449,9 @@ var AutoIndexCoordinator = class {
         this.setState("idle", { source: void 0 });
       }
     }
+    if (pauseOnBatteryChanged) {
+      this.cancelBatteryRetry();
+    }
   }
   activateAfter(activation) {
     this.activation = activation;
@@ -12263,7 +12473,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)) {
@@ -12281,6 +12510,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;
     }
@@ -12297,6 +12531,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", {
@@ -12326,10 +12562,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;
@@ -12493,6 +12739,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((resolve12) => {
+      const timer = setTimeout(() => {
+        if (this.batteryRetryTimer === timer) {
+          this.batteryRetryTimer = null;
+          this.resolveBatteryRetry = null;
+        }
+        resolve12();
+      }, delayMs);
+      timer.unref?.();
+      this.batteryRetryTimer = timer;
+      this.resolveBatteryRetry = resolve12;
+    });
+  }
+  cancelBatteryRetry() {
+    if (this.batteryRetryTimer) {
+      clearTimeout(this.batteryRetryTimer);
+      this.batteryRetryTimer = null;
+    }
+    const resolve12 = this.resolveBatteryRetry;
+    this.resolveBatteryRetry = null;
+    resolve12?.();
+  }
+  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(projectRoot3, host) {
   const key = coordinatorKeysByProject.get(projectLookupKey(projectRoot3, host));
@@ -12502,6 +12810,9 @@ function configureAutoIndex(projectRoot3, host, config, getIndexer) {
   const projectKey = projectLookupKey(projectRoot3, host);
   const safety = getProjectSafety(projectRoot3, config);
   const registration = {
+    backgroundIndexingPolicy: createBackgroundIndexingPolicy(
+      config.indexing.pauseBackgroundIndexingOnBattery
+    ),
     config,
     getIndexer,
     projectRoot: projectRoot3,
@@ -13849,6 +14160,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,
@@ -13856,7 +14168,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"
         })
       );
     }