fix(search): query-aware bestExample, golden file threshold, ONNX thread limits

- Lower golden file threshold from >=3 to >=2 for React/generic codebase coverage
- Persist patterns field in IntelligenceGoldenFile for downstream category filtering
- get_team_patterns now returns filtered goldenFiles for di/state/testing categories
- search_codebase getBestExample uses directory overlap against top-5 results (no keyword maps)
- discovery-harness falls back to parsed.bestExample when preflight.bestExample absent
- ONNX Runtime limited to half cores by default (CODEBASE_CONTEXT_ONNX_THREADS override)
- setImmediate yields added in embedBatch inner loop and indexer outer batch loop

Author: PatrickSys

src/core/indexer.ts

@@ -694,7 +694,7 @@ export class CodebaseIndexer {
               : [];
             const uniqueCategories = new Set(detectedPatterns.map((p) => p.category));
             const patternScore = uniqueCategories.size;
-            if (patternScore >= 3) {
+            if (patternScore >= 2) {
               const patternFlags: Record<string, boolean> = {};
               for (const p of detectedPatterns) {
                 patternFlags[`${p.category}:${p.name}`] = true;
@@ -797,6 +797,10 @@ export class CodebaseIndexer {
             });
           }
 
+          // Yield to event loop between outer embedding batches — keeps system responsive
+          // and allows SIGINT/SIGTERM signal handlers to fire during long indexing runs.
+          await new Promise<void>((resolve) => setImmediate(resolve));
+
           // Update progress
           const embeddingProgress = 50 + Math.round((i / chunksToEmbed.length) * 25);
           this.updateProgress('embedding', embeddingProgress);

src/core/reranker.ts

@@ -9,6 +9,7 @@
  */
 
 import type { SearchResult } from '../types/index.js';
+import os from 'os';
 
 const DEFAULT_RERANKER_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
 
@@ -47,7 +48,12 @@ async function ensureModelLoaded(): Promise<void> {
 
     cachedTokenizer = await AutoTokenizer.from_pretrained(DEFAULT_RERANKER_MODEL);
     cachedModel = await AutoModelForSequenceClassification.from_pretrained(DEFAULT_RERANKER_MODEL, {
-      dtype: 'q8'
+      dtype: 'q8',
+      // Limit ONNX Runtime to half cores by default — prevents system freeze during indexing.
+      session_options: {
+        intraOpNumThreads: Math.max(1, Math.floor(os.cpus().length / 2)),
+        interOpNumThreads: 1
+      }
     });
 
     console.error('[reranker] Cross-encoder loaded successfully');

src/embeddings/transformers.ts

@@ -1,5 +1,20 @@
 import { EmbeddingProvider, DEFAULT_MODEL } from './types.js';
 import type { FeatureExtractionPipelineType } from '@huggingface/transformers';
+import os from 'os';
+
+/**
+ * Returns the number of ONNX intra-op threads to use.
+ * Defaults to half of available CPU cores to prevent system freeze during indexing.
+ * Override via CODEBASE_CONTEXT_ONNX_THREADS env var.
+ */
+function getOnnxThreadCount(): number {
+  const envVal = process.env.CODEBASE_CONTEXT_ONNX_THREADS;
+  if (envVal) {
+    const parsed = parseInt(envVal, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return Math.max(1, Math.floor(os.cpus().length / 2));
+}
 
 interface ModelConfig {
   dimensions: number;
@@ -62,7 +77,14 @@ export class TransformersEmbeddingProvider implements EmbeddingProvider {
         opts: Record<string, unknown>
       ) => Promise<FeatureExtractionPipelineType>;
       this.pipeline = await (pipeline as PipelineFn)('feature-extraction', this.modelName, {
-        dtype: 'q8'
+        dtype: 'q8',
+        // Limit ONNX Runtime to half cores by default — prevents system freeze during indexing.
+        // interOpNumThreads: 1 — no benefit for single-model pipelines.
+        // Override via CODEBASE_CONTEXT_ONNX_THREADS env var.
+        session_options: {
+          intraOpNumThreads: getOnnxThreadCount(),
+          interOpNumThreads: 1
+        }
       });
 
       this.ready = true;
@@ -114,6 +136,10 @@ export class TransformersEmbeddingProvider implements EmbeddingProvider {
       });
       embeddings.push(...(output.tolist() as number[][]));
 
+      // Yield to event loop — allows signal handlers (SIGINT/SIGTERM) to fire during
+      // tight embedding loops, keeping the system responsive during indexing.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+
       if (texts.length > 100 && (i + batchSize) % 100 === 0) {
         console.error(`Embedded ${Math.min(i + batchSize, texts.length)}/${texts.length} chunks`);
       }

src/eval/discovery-harness.ts

@@ -63,7 +63,9 @@ async function runSearchCodebase(
   const bestExample =
     preflight && typeof preflight === 'object' && preflight !== null && 'bestExample' in preflight
       ? ((preflight.bestExample as string | undefined) ?? null)
-      : null;
+      : typeof parsed.bestExample === 'string'
+        ? parsed.bestExample
+        : null;
 
   return {
     payload,
@@ -145,7 +147,12 @@ export function matchSignals(
   payload: string,
   expectedSignals: string[],
   forbiddenSignals: string[] | undefined
-): { matchedSignals: string[]; missingSignals: string[]; forbiddenHits: string[]; usefulnessScore: number } {
+): {
+  matchedSignals: string[];
+  missingSignals: string[];
+  forbiddenHits: string[];
+  usefulnessScore: number;
+} {
   const normalizedPayload = normalizeText(payload);
   const matchedSignals = expectedSignals.filter((signal) =>
     normalizedPayload.includes(normalizeText(signal))

src/tools/get-team-patterns.ts

@@ -6,7 +6,24 @@ import {
   isComplementaryPatternConflict,
   shouldSkipLegacyTestingFrameworkCategory
 } from '../patterns/semantics.js';
-import type { IntelligenceData, PatternsData } from '../types/index.js';
+import type { IntelligenceData, IntelligenceGoldenFile, PatternsData } from '../types/index.js';
+
+/**
+ * Filter golden files by category prefix keys in their patterns map.
+ * Returns files whose patterns include at least one key matching a given prefix.
+ * Returns empty array when no golden files match — never fabricates.
+ */
+function filterGoldenFilesByCategory(
+  goldenFiles: IntelligenceGoldenFile[] | undefined,
+  categoryPrefixes: string[]
+): IntelligenceGoldenFile[] {
+  if (!goldenFiles?.length) return [];
+  return goldenFiles.filter(
+    (gf) =>
+      gf.patterns &&
+      categoryPrefixes.some((prefix) => Object.keys(gf.patterns!).some((k) => k.startsWith(prefix)))
+  );
+}
 
 export const definition: Tool = {
   name: 'get_team_patterns',
@@ -59,11 +76,13 @@ export async function handle(
       if (intel.patterns?.dependencyInjection)
         (result.patterns as Record<string, unknown>).dependencyInjection =
           intel.patterns.dependencyInjection;
+      result.goldenFiles = filterGoldenFilesByCategory(intel.goldenFiles, ['dependencyInjection:']);
     } else if (category === 'state') {
       result.patterns = {};
       if (intel.patterns?.stateManagement)
         (result.patterns as Record<string, unknown>).stateManagement =
           intel.patterns.stateManagement;
+      result.goldenFiles = filterGoldenFilesByCategory(intel.goldenFiles, ['stateManagement:']);
     } else if (category === 'testing') {
       result.patterns = {};
       for (const k of [
@@ -75,6 +94,11 @@ export async function handle(
         if (intel.patterns?.[k])
           (result.patterns as Record<string, unknown>)[k] = intel.patterns[k];
       }
+      result.goldenFiles = filterGoldenFilesByCategory(intel.goldenFiles, [
+        'unitTestFramework:',
+        'e2eFramework:',
+        'testingFramework:'
+      ]);
     } else if (category === 'libraries') {
       result.topUsed = intel.importGraph?.topUsed || [];
       if (intel.tsconfigPaths) {

src/tools/search-codebase.ts

@@ -587,9 +587,45 @@ export async function handle(
     return entries.length > 0 ? entries.join(', ') : undefined;
   }
 
-  // Return the top golden file path from intelligence.json (compact mode bestExample)
-  function getBestExample(): string | undefined {
-    return intelligence?.goldenFiles?.[0]?.file;
+  // Return the golden file path most relevant to the given search results, using directory
+  // overlap as a query-aware proximity signal. Falls back to goldenFiles[0] when no overlap.
+  // Track B: use cross-encoder reranker to score golden files against the query for stronger
+  // relevance — deferred to avoid reranker latency on compact mode in v2.
+  function getBestExample(topResults: Array<{ filePath: string }>): string | undefined {
+    const goldenFiles = intelligence?.goldenFiles;
+    if (!goldenFiles?.length) return undefined;
+    if (!topResults?.length) return goldenFiles[0].file;
+
+    // Extract directory paths from top-5 results
+    const resultDirs = topResults.slice(0, 5).map((r) => path.dirname(r.filePath));
+
+    let bestFile = goldenFiles[0];
+    let bestScore = -1;
+
+    for (const gf of goldenFiles) {
+      const gfParts = path.dirname(gf.file).split(path.sep).filter(Boolean);
+      let maxShared = 0;
+
+      for (const resDir of resultDirs) {
+        const resParts = resDir.split(path.sep).filter(Boolean);
+        let shared = 0;
+        const minLen = Math.min(gfParts.length, resParts.length);
+        for (let i = 0; i < minLen; i++) {
+          if (gfParts[i] === resParts[i]) shared++;
+          else break;
+        }
+        if (shared > maxShared) maxShared = shared;
+      }
+
+      // Use golden file score as tie-breaker
+      const score = maxShared * 1000 + (gf.score ?? 0);
+      if (score > bestScore) {
+        bestScore = score;
+        bestFile = gf;
+      }
+    }
+
+    return bestFile.file;
   }
 
   // Build up to 2 dynamic next-hop suggestions (compact mode)
@@ -887,9 +923,10 @@ export async function handle(
           };
         }
 
-        // Add bestExample (top 1 golden file)
-        if (goldenFiles.length > 0) {
-          decisionCard.bestExample = `${goldenFiles[0].file}`;
+        // Add bestExample — query-aware via directory overlap against top search results
+        const preflightBestExample = getBestExample(results.slice(0, 5));
+        if (preflightBestExample) {
+          decisionCard.bestExample = preflightBestExample;
         }
 
         // Add impact (coverage + top 3 files)
@@ -1011,7 +1048,7 @@ export async function handle(
     const compactResults = results.slice(0, 6);
     const strongMemories = filterStrongMemories(relatedMemories, queryStr);
     const patternSummary = buildPatternSummary();
-    const bestExample = getBestExample();
+    const bestExample = getBestExample(compactResults);
     const nextHops = buildNextHops(compactResults, searchQuality);
 
     return {

src/types/index.ts

@@ -639,6 +639,8 @@ export type PatternsData = Record<string, PatternEntry>;
 export interface IntelligenceGoldenFile {
   file: string;
   score: number;
+  /** Pattern flags persisted from runtime GoldenFile — e.g. "dependencyInjection:inject() function": true */
+  patterns?: Record<string, boolean>;
 }
 
 // ============================================================================