opencode-codebase-index 0.19.1 → 0.20.0

package/dist/index.cjs

@@ -787,6 +787,7 @@ function getDefaultIndexingConfig() {
     autoIndexMaxRetries: 5,
     autoIndexRetryDelayMs: 100,
     watchFiles: true,
+    pauseBackgroundIndexingOnBattery: false,
     maxFileSize: 1048576,
     maxChunksPerFile: 100,
     semanticOnly: false,
@@ -918,6 +919,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,
@@ -4188,9 +4190,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,
@@ -6707,6 +6721,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) {
@@ -7008,7 +7023,7 @@ function classifyQueryIntentRaw(query) {
   return "neutral";
 }
 function isImplementationChunkType(chunkType) {
-  return [
+  return CALL_GRAPH_SYMBOL_CHUNK_TYPES.has(chunkType) || [
     "export_statement",
     "function",
     "function_declaration",
@@ -7453,7 +7468,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 [];
   }
@@ -7467,14 +7482,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;
@@ -7496,6 +7511,7 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
         }
       });
     }
+    return true;
   };
   const normalizedHints = identifierHints.flatMap((hint) => [
     hint,
@@ -7517,12 +7533,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();
@@ -7530,6 +7580,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);
     }
   }
@@ -8071,6 +8124,10 @@ var Indexer = class _Indexer {
     const projectHash = hashContent(path14.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";
   }
@@ -9414,7 +9471,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);
@@ -9473,6 +9531,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) => path14.extname(filePath).toLowerCase() === ".swift"
     )) {
@@ -9516,7 +9576,7 @@ var Indexer = class _Indexer {
       );
       const requiresSwiftParserUpgrade = reparseCachedSwiftFiles && path14.extname(canonicalPath).toLowerCase() === ".swift";
       const requiresMetalParserUpgrade = reparseCachedMetalFiles && path14.extname(canonicalPath).toLowerCase() === ".metal";
-      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade) {
+      if (cachedHashMatches && !needsCallGraphRefresh && !requiresSwiftParserUpgrade && !requiresMetalParserUpgrade && !refreshCachedSymbols) {
         unchangedFilePaths.add(canonicalPath);
         this.logger.recordCacheHit();
       } else {
@@ -9727,37 +9787,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();
@@ -9873,6 +9923,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 };
@@ -9909,6 +9960,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 };
@@ -10188,6 +10240,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 };
@@ -10326,10 +10379,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);
@@ -10401,6 +10455,7 @@ var Indexer = class _Indexer {
       query,
       database,
       branchChunkIds,
+      branchSymbolIds,
       maxResults,
       union,
       sourceIntent
@@ -10414,7 +10469,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, {
@@ -10571,7 +10626,7 @@ var Indexer = class _Indexer {
       const extension = path14.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)) {
@@ -11279,7 +11334,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.");
       }
@@ -11621,8 +11679,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();
@@ -11711,7 +11778,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);
@@ -12083,7 +12155,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",
@@ -12129,6 +12201,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));
@@ -12177,6 +12252,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;
@@ -12192,7 +12272,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),
@@ -12204,7 +12284,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) {
@@ -12226,12 +12313,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 {
@@ -12246,7 +12340,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() {
@@ -12265,6 +12363,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`,
@@ -12279,6 +12378,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."
@@ -12290,6 +12393,103 @@ function formatEffectivenessMetrics(snapshot) {
 var import_fs11 = require("fs");
 var os6 = __toESM(require("os"), 1);
 var path16 = __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((resolve14, reject) => {
+    childProcess.execFile(
+      file,
+      args,
+      { encoding: "utf8", timeout: options.timeoutMs },
+      (error, stdout) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve14(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();
@@ -12406,7 +12606,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) {
@@ -12419,6 +12625,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;
@@ -12434,6 +12641,9 @@ var AutoIndexCoordinator = class {
         this.setState("idle", { source: void 0 });
       }
     }
+    if (pauseOnBatteryChanged) {
+      this.cancelBatteryRetry();
+    }
   }
   activateAfter(activation) {
     this.activation = activation;
@@ -12455,7 +12665,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)) {
@@ -12473,6 +12702,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;
     }
@@ -12489,6 +12723,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", {
@@ -12518,10 +12754,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;
@@ -12685,6 +12931,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((resolve14) => {
+      const timer = setTimeout(() => {
+        if (this.batteryRetryTimer === timer) {
+          this.batteryRetryTimer = null;
+          this.resolveBatteryRetry = null;
+        }
+        resolve14();
+      }, delayMs);
+      timer.unref?.();
+      this.batteryRetryTimer = timer;
+      this.resolveBatteryRetry = resolve14;
+    });
+  }
+  cancelBatteryRetry() {
+    if (this.batteryRetryTimer) {
+      clearTimeout(this.batteryRetryTimer);
+      this.batteryRetryTimer = null;
+    }
+    const resolve14 = this.resolveBatteryRetry;
+    this.resolveBatteryRetry = null;
+    resolve14?.();
+  }
+  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));
@@ -12694,6 +13002,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,
@@ -15445,7 +15756,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();
     });
   }
@@ -15997,6 +16311,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,
@@ -16004,7 +16319,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"
         })
       );
     }
@@ -17294,6 +17610,21 @@ var CONCEPTUAL_DISCOVERY_HINTS = [
   "pattern",
   "code that"
 ];
+var BROAD_LOCAL_TASK_HINTS = [
+  "fix the bug",
+  "fix this",
+  "fix issue",
+  "implement ",
+  "add support",
+  "investigate ",
+  "debug ",
+  "refactor ",
+  "review this",
+  "review codebase",
+  "review the codebase",
+  "audit this",
+  "audit the codebase"
+];
 var DEFINITION_HINTS = [
   "defined",
   "definition",
@@ -17340,6 +17671,9 @@ function isExternalLookup(text) {
 function hasConceptualDiscoveryHint(text) {
   return includesHint(text, CONCEPTUAL_DISCOVERY_HINTS);
 }
+function hasBroadLocalTaskHint(text) {
+  return includesHint(text, BROAD_LOCAL_TASK_HINTS);
+}
 function hasDefinitionHint(text) {
   return includesHint(text, DEFINITION_HINTS);
 }
@@ -17397,10 +17731,11 @@ function assessRoutingIntent(text) {
   const matchedDefinitionHint = hasDefinitionHint(lowered);
   const matchedExactMatchHint = hasExactMatchHint(lowered);
   const matchedNonDiscoveryHint = hasNonDiscoveryHint(lowered);
+  const matchedBroadLocalTask = hasBroadLocalTaskHint(lowered);
   const hasIdentifier = hasIdentifierShape(normalizedText);
   const hasQuotedIdentifier = containsQuotedIdentifier(normalizedText);
   const shortQuery = countWords(lowered) <= 10;
-  if (matchedNonDiscoveryHint && !matchedConceptualHint) {
+  if (matchedNonDiscoveryHint && !matchedConceptualHint && !matchedBroadLocalTask) {
     return {
       intent: "other",
       text: normalizedText,
@@ -17421,6 +17756,13 @@ function assessRoutingIntent(text) {
       reason: "definition_lookup_request"
     };
   }
+  if (matchedBroadLocalTask) {
+    return {
+      intent: "local_broad_task",
+      text: normalizedText,
+      reason: "broad_local_code_task"
+    };
+  }
   if ((matchedExactMatchHint || hasQuotedIdentifier || hasIdentifier) && !matchedConceptualHint && shortQuery) {
     return {
       intent: "exact_identifier",
@@ -17448,15 +17790,15 @@ function buildRoutingHint(assessment, status, includeGraphHandoff = false) {
     }
     return "For this turn, prefer `implementation_lookup` to find the authoritative definition site. Use `codebase_search` only if no definition is found, and use `grep` for exhaustive literal matches.";
   }
-  if (assessment.intent !== "local_conceptual") {
+  if (assessment.intent !== "local_conceptual" && assessment.intent !== "local_broad_task") {
     return null;
   }
   if (!status || !status.indexed || status.compatibility?.compatible === false) {
     const graphHandoff2 = includeGraphHandoff ? " Use graph tools after semantic discovery identifies relevant symbols." : "";
-    return `For this turn, if local code discovery by behavior is needed, check \`index_status\` first and run \`index_codebase\` if the index is missing or incompatible.${graphHandoff2} Use \`grep\` for exact identifiers or exhaustive matches.`;
+    return `For this turn, if local code discovery by behavior is needed, check \`index_status\` first and run \`index_codebase\` if the index is missing or incompatible.${graphHandoff2} Then use \`codebase_context\` as the first local repository lookup. Use \`grep\` for exact identifiers or exhaustive matches.`;
   }
   const graphHandoff = includeGraphHandoff ? " before graph tools such as `call_graph`, `call_graph_path`, `pr_impact`, or OMO CodeGraph" : "";
-  return `For this turn, prefer \`codebase_peek\` for local code discovery by behavior or likely location${graphHandoff}. Then use \`codebase_search\` when you need implementation content. Use \`grep\` for exact identifiers or exhaustive matches.`;
+  return `For this turn, prefer \`codebase_context\` for local code discovery, then use \`codebase_peek\` for metadata and \`codebase_search\` when you need implementation content${graphHandoff}. Use \`grep\` for exact identifiers or exhaustive matches.`;
 }
 var RoutingHintController = class {
   constructor(getStatus, maxSessions = 200, includeGraphHandoff = false) {
@@ -17473,7 +17815,7 @@ var RoutingHintController = class {
     this.compactSessions();
     this.sessionState.set(sessionID, {
       assessment,
-      pendingHint: assessment.intent === "local_conceptual" || assessment.intent === "definition_lookup",
+      pendingHint: assessment.intent === "local_conceptual" || assessment.intent === "local_broad_task" || assessment.intent === "definition_lookup",
       updatedAt: Date.now()
     });
     return assessment;
@@ -17488,6 +17830,9 @@ var RoutingHintController = class {
     }
     const status = await this.safeGetStatus();
     const hint = buildRoutingHint(state.assessment, status, this.includeGraphHandoff);
+    state.pendingHint = false;
+    state.updatedAt = Date.now();
+    this.sessionState.set(sessionID, state);
     return hint ? [hint] : [];
   }
   markToolUsed(sessionID, toolName) {
@@ -17495,7 +17840,7 @@ var RoutingHintController = class {
     if (!state || !state.pendingHint) {
       return;
     }
-    if (toolName === "codebase_peek" || toolName === "codebase_search" || toolName === "implementation_lookup" || toolName === "index_status" || toolName === "index_codebase") {
+    if (toolName === "codebase_context" || toolName === "codebase_peek" || toolName === "codebase_search" || toolName === "implementation_lookup" || toolName === "index_status" || toolName === "index_codebase") {
       state.pendingHint = false;
       state.updatedAt = Date.now();
       this.sessionState.set(sessionID, state);