sweet-search 2.5.2 → 2.5.3

package/core/search/search-cli.js

@@ -1,8 +1,9 @@
 /**
  * Search CLI Module
  *
- * Extracted from sweet-search.js (SOLID refactor).
- * Contains all CLI/terminal code: styling, pixel art, argument parsing, runCli.
+ * Extracted from sweet-search.js (SOLID refactor). Argument parsing + runCli.
+ * Decoration rendering lives in cli-decoration.js; the where-to-emit decision
+ * lives in output-policy.js.
  *
  * IMPORTANT: Uses dynamic import() for sweet-search.js and search-server.js
  * references to avoid circular dependencies.
@@ -17,177 +18,8 @@ import {
   formatSummaryFirst,
   formatMiddleRes,
 } from './search-format.js';
-
-// =============================================================================
-// CLI STYLING (ANSI truecolor w/ fallback)
-// =============================================================================
-
-export const STYLE = (() => {
-  // 5 shades of dark blue (edge -> center)
-  const colors = {
-    darkest:       { r: 6,   g: 10,  b: 31  },
-    darker:        { r: 10,  g: 17,  b: 52  },
-    dark:          { r: 14,  g: 24,  b: 73  },
-    lightDark:     { r: 18,  g: 32,  b: 95  },
-    lightestDark:  { r: 22,  g: 40,  b: 116 },
-    border:        { r: 90,  g: 115, b: 220 },
-    white:         { r: 255, g: 255, b: 255 },
-  };
-
-  const reset = '\x1b[0m';
-  const bold = '\x1b[1m';
-
-  const lerp = (c1, c2, t) => ({
-    r: Math.round(c1.r + (c2.r - c1.r) * t),
-    g: Math.round(c1.g + (c2.g - c1.g) * t),
-    b: Math.round(c1.b + (c2.b - c1.b) * t),
-  });
-
-  // Convert RGB to xterm-256 color code (fallback for terminals without truecolor)
-  const rgbToAnsi256 = (r, g, b) => {
-    // Grayscale range
-    if (r === g && g === b) {
-      if (r < 8) return 16;
-      if (r > 248) return 231;
-      return Math.round(((r - 8) / 247) * 24) + 232;
-    }
-
-    const to6 = (v) => Math.round((v / 255) * 5);
-    const rr = to6(r);
-    const gg = to6(g);
-    const bb = to6(b);
-    return 16 + (36 * rr) + (6 * gg) + bb;
-  };
-
-  const fg24 = (c) => `\x1b[38;2;${c.r};${c.g};${c.b}m`;
-  const bg24 = (c) => `\x1b[48;2;${c.r};${c.g};${c.b}m`;
-
-  const fg256 = (c) => `\x1b[38;5;${rgbToAnsi256(c.r, c.g, c.b)}m`;
-  const bg256 = (c) => `\x1b[48;5;${rgbToAnsi256(c.r, c.g, c.b)}m`;
-
-  const detectColorMode = () => {
-    const forced = (process.env.SWEET_SEARCH_COLOR_MODE || process.env.SMART_SEARCH_COLOR_MODE || '').trim().toLowerCase();
-    if (forced === 'none' || forced === '0' || forced === 'off') return 'none';
-    if (forced === '256' || forced === 'ansi256' || forced === 'xterm256') return 'ansi256';
-    if (forced === 'truecolor' || forced === '24bit' || forced === 'rgb') return 'truecolor';
-
-    if (process.env.NO_COLOR) return 'none';
-
-    const colorterm = process.env.COLORTERM || '';
-    if (/truecolor|24bit/i.test(colorterm)) return 'truecolor';
-
-    // Windows Terminal + VS Code terminals are typically truecolor-capable.
-    if (process.env.WT_SESSION || process.env.TERM_PROGRAM === 'vscode') return 'truecolor';
-
-    const term = process.env.TERM || '';
-    if (/256color/i.test(term)) return 'ansi256';
-
-    return 'none';
-  };
-
-  const colorMode = detectColorMode(); // 'truecolor' | 'ansi256' | 'none'
-  const fg = colorMode === 'truecolor' ? fg24 : colorMode === 'ansi256' ? fg256 : () => '';
-  const bg = colorMode === 'truecolor' ? bg24 : colorMode === 'ansi256' ? bg256 : () => '';
-
-  const headerStyleEnv = (process.env.SWEET_SEARCH_HEADER_STYLE || process.env.SMART_SEARCH_HEADER_STYLE || '').trim().toLowerCase();
-  const headerStyle =
-    headerStyleEnv === 'zones' || headerStyleEnv === 'gradient'
-      ? headerStyleEnv
-      : (colorMode === 'truecolor' ? 'gradient' : 'zones');
-
-  return {
-    colors,
-    fg,
-    bg,
-    reset: colorMode === 'none' ? '' : reset,
-    bold: colorMode === 'none' ? '' : bold,
-    lerp,
-    colorMode,
-    headerStyle,
-  };
-})();
-
-// 2-line pixel art using half-blocks - SWEET SEARCH
-const SWEET_SEARCH_L1 = '█▀▀ █ █ █ █▀▀ █▀▀ ▀█▀  █▀▀ █▀▀ ▄▀▄ █▀▄ █▀▀ █▄█';
-const SWEET_SEARCH_L2 = '▄▄█ ▀▄█▄▀ ██▄ ██▄  █   ▄▄█ ██▄ █▀█ ██▄ █▄▄ █▀█';
-
-/**
- * Print styled header - 2-line pixel art with query on right = 2 content lines.
- */
-export function printStyledHeader(query) {
-  const width = Math.min(process.stdout.columns || 80, 80);
-  const { colors, fg, bg, reset, bold } = STYLE;
-
-  const artLen = SWEET_SEARCH_L2.length;
-  const maxQueryLen = width - artLen - 8;
-  const displayQuery = query.length > maxQueryLen
-    ? query.slice(0, maxQueryLen - 3) + '...'
-    : query;
-
-  const palette = [
-    colors.darkest,
-    colors.darker,
-    colors.dark,
-    colors.lightDark,
-    colors.lightestDark,
-  ];
-
-  const getBgColor = (i, w) => {
-    const pos = i / Math.max(1, w - 1);
-    const t = 1 - Math.abs(0.5 - pos) * 2;
-    const zone = Math.min(Math.floor(t * palette.length), palette.length - 1);
-    return palette[zone];
-  };
-
-  const buildLine = (leftContent, rightContent = null, isArt = false) => {
-    let result = '';
-    const leftPad = 2;
-    const rightPad = 2;
-    const rightStart = rightContent ? width - rightPad - rightContent.length : width;
-
-    for (let i = 0; i < width; i++) {
-      const bgColor = getBgColor(i, width);
-      const leftCharIdx = i - leftPad;
-      const rightCharIdx = i - rightStart;
-
-      if (rightContent && rightCharIdx >= 0 && rightCharIdx < rightContent.length) {
-        result += bold + fg(colors.white) + bg(bgColor) + rightContent[rightCharIdx];
-      } else if (leftCharIdx >= 0 && leftCharIdx < leftContent.length) {
-        const fgColor = isArt ? colors.border : colors.white;
-        result += bold + fg(fgColor) + bg(bgColor) + leftContent[leftCharIdx];
-      } else {
-        result += bg(bgColor) + ' ';
-      }
-    }
-    return result + reset;
-  };
-
-  const queryStr = `"${displayQuery}"`;
-
-  console.log('');
-  console.log(buildLine(SWEET_SEARCH_L1, null, true));
-  console.log(buildLine(SWEET_SEARCH_L2, queryStr, true));
-}
-
-/**
- * Print styled stats line
- */
-export function printStyledStats(stats, isWarm = false) {
-  const { colors, fg, reset } = STYLE;
-  const mode = stats.routing?.mode || stats.mode || 'auto';
-  const pathType = stats.path || 'hybrid';
-  const timeMs = stats.server_ms || stats.total_ms || 0;
-
-  const modeIcon = { lexical: '⚡', semantic: '🧠', hybrid: '⚗️', structural: '🔗', auto: '✨' }[mode] || '◆';
-  const warmIcon = isWarm ? `${fg(colors.border)}●${reset}` : `${fg(colors.darker)}○${reset}`;
-
-  console.log(
-    `  ${modeIcon} ${fg(colors.white)}${mode}${reset} ` +
-    `${fg(colors.dark)}│${reset} ${fg(colors.border)}${pathType}${reset} ` +
-    `${fg(colors.dark)}│${reset} ${fg(colors.white)}${timeMs}ms${reset} ${warmIcon}`
-  );
-  console.log('');
-}
+import { detectOutputPolicy } from './output-policy.js';
+import { emitDecoration } from './cli-decoration.js';
 
 // =============================================================================
 // CLI entry point
@@ -196,9 +28,9 @@ export function printStyledStats(stats, isWarm = false) {
 export async function runCli(args) {
   // Dynamic imports to avoid circular dependencies
   const { default: SweetSearch } = await import('./sweet-search.js');
-  const { startServer, queryServer, isServerRunning, autoSpawnServer,
-          SEARCH_SERVER_SOCKET, SEARCH_SERVER_SOCKET_LEGACY, SEARCH_SERVER_PORT
+  const { startServer, queryServer, isServerRunning, autoSpawnServer
         } = await import('./search-server.js');
+  const { projectSocketPath } = await import('./server-identity.js');
 
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     console.log(`
@@ -220,13 +52,25 @@ Options:
   --fusion <type>   Legacy: cc or rrf (ignored for hybrid - always uses robust CC fusion)
   --late-interaction Enable late interaction reranking (if index available)
   --late-interaction-model=ID Use specific model (lateon-code or lateon-code-edge)
-  --agent           Agent mode: return self-contained code blocks (ColGrep context packaging)
-  --agent-full      Agent mode with full expansion for top-3 results (budget: 8000)
-  --budget <n>      Agent mode token budget (default: 4000 preview, 8000 full)
+  --agent           Agent mode: self-contained code blocks. Auto-picks 4k/8k/12k
+                    tier from score-distribution signals (top-1 dominance,
+                    entropy, candidate-pool breadth) — no need to choose a tier.
+  --agent-preview   Force the 4k preview tier (rarely needed; --agent auto-picks)
+  --agent-full      Force the 8k full tier (rarely needed; --agent auto-picks)
+  --agent-full-xl   Force the 12k XL tier; gated on top-1 dominance ≥ 2× top-2
+  --budget <n>      Explicit total token budget (overrides auto-tier; --agent
+                    keeps it as the format)
   --summary         HCGS summary-first output (10x token reduction)
   --mid             Middle-res view: signature + docstring (5x token reduction)
   --json            Output as JSON
+  --format <fmt>    Output format: plain (no banner/color), json
+  --no-banner       Suppress the decorative banner (keep text results)
   --verbose, -v     Enable verbose logging
+
+Decoration is auto by default (shown only where it is token-free). Override with
+SWEET_SEARCH_DECORATION=never (always plain) or =always (force the banner onto
+stdout even when captured — you accept the added token cost). NO_COLOR disables
+ANSI color.
   --cold            Force cold start (skip auto-start server)
   --serve           Manually start server (usually not needed)
 
@@ -271,28 +115,15 @@ Examples:
         req.end();
       });
 
-      // F-06: Stop via Unix socket first so CLI behavior matches server policy.
+      // Stop this project's server via its per-project Unix socket (C3). No
+      // legacy/global fallback — that would risk stopping another project's
+      // server.
+      const socketPath = projectSocketPath();
       let stopResponse = null;
-      if (existsSync(SEARCH_SERVER_SOCKET)) {
-        stopResponse = await requestStop({
-          socketPath: SEARCH_SERVER_SOCKET,
-          path: '/stop',
-          method: 'GET',
-        });
-      } else if (existsSync(SEARCH_SERVER_SOCKET_LEGACY)) {
-        stopResponse = await requestStop({
-          socketPath: SEARCH_SERVER_SOCKET_LEGACY,
-          path: '/stop',
-          method: 'GET',
-        });
+      if (existsSync(socketPath)) {
+        stopResponse = await requestStop({ socketPath, path: '/stop', method: 'GET' });
       } else {
-        // Backward-compatible fallback for older servers without Unix socket.
-        stopResponse = await requestStop({
-          hostname: 'localhost',
-          port: SEARCH_SERVER_PORT,
-          path: '/stop',
-          method: 'GET',
-        });
+        stopResponse = { statusCode: 0, body: 'no server running for this project' };
       }
 
       if (stopResponse.statusCode === 200) {
@@ -324,6 +155,8 @@ Examples:
     let fusion = 'cc';
     let useLateInteraction = LATE_INTERACTION_CONFIG.enabled;
     let json = false;
+    let outputFormat = null;    // e.g. 'plain' — disables decoration but keeps text results
+    let noBanner = false;
     let verbose = false;
     let summaryFirst = false;
     let middleRes = false;
@@ -373,6 +206,14 @@ Examples:
         LATE_INTERACTION_CONFIG.model = arg.split('=')[1];
       } else if (arg === '--json') {
         json = true;
+      } else if (arg === '--no-banner') {
+        noBanner = true;
+      } else if (arg === '--format' && args[i + 1]) {
+        outputFormat = args[++i];
+        if (outputFormat === 'json') json = true;
+      } else if (arg.startsWith('--format=')) {
+        outputFormat = arg.slice('--format='.length);
+        if (outputFormat === 'json') json = true;
       } else if (arg === '--summary') {
         summaryFirst = true;
       } else if (arg === '--mid') {
@@ -382,14 +223,22 @@ Examples:
       } else if (arg === '--cold') {
         forceCold = true;
       } else if (arg === '--agent') {
-        agentFormat = agentFormat || 'agent_preview';
+        // 'agent' triggers auto-tier selection (preview/full/xl picked from
+        // top-1 dominance, entropy, and candidate-pool breadth). Power users
+        // can still force a specific tier with --agent-preview / --agent-full
+        // / --agent-full-xl.
+        agentFormat = agentFormat || 'agent';
+      } else if (arg === '--agent-preview') {
+        agentFormat = 'agent_preview';
       } else if (arg === '--agent-full') {
         agentFormat = 'agent_full';
       } else if (arg === '--agent-full-xl') {
         agentFormat = 'agent_full_xl';
       } else if (arg === '--budget' && args[i + 1]) {
         agentBudget = parseInt(args[++i], 10);
-        agentFormat = agentFormat || 'agent_preview';
+        // Pair an explicit numeric budget with auto-tier so the response's
+        // budgetReason reflects 'explicit_budget' rather than a tier override.
+        agentFormat = agentFormat || 'agent';
       } else if (!arg.startsWith('--')) {
         query = arg;
       }
@@ -407,6 +256,16 @@ Examples:
       process.exit(1);
     }
 
+    // Decide where decoration may go (token-free channels only). Computed once;
+    // both the warm and cold paths consult it.
+    const outputPolicy = detectOutputPolicy({
+      json,
+      format: outputFormat,
+      noBanner,
+      env: process.env,
+      stream: process.stdout,
+    });
+
     // Check if warm server is running (unless --cold)
     let serverRunning = !forceCold && await isServerRunning();
 
@@ -452,8 +311,7 @@ Examples:
           if (json) {
             console.log(JSON.stringify({ results, stats }, null, 2));
           } else {
-            printStyledHeader(query);
-            printStyledStats(stats, true);
+            emitDecoration(outputPolicy, query, stats, true);
 
             // Use pure formatting helpers (no full SweetSearch instantiation needed).
             // Contract note: formatResults currently only depends on `this` for
@@ -521,8 +379,7 @@ Examples:
         if (json) {
           console.log(JSON.stringify({ results, stats }, null, 2));
         } else {
-          printStyledHeader(query);
-          printStyledStats(stats, false);
+          emitDecoration(outputPolicy, query, stats, false);
 
           if (stats.path === 'structural') {
             console.log(searcher.formatStructuralResults(results, stats));

package/core/search/search-hybrid.js

@@ -10,6 +10,83 @@
 
 import { routeQuery } from '../query/query-router.js';
 import { applyMMR, shouldApplyMMR, getLambdaForIntent } from '../ranking/mmr.js';
+import { applyFileKindRanking, applyResultDemotions, classifyFileKindIntent, detectFileKind } from '../ranking/file-kind-ranking.js';
+import { injectAnchorCandidates } from './search-anchor.js';
+import { runRRFFallback } from './search-rrf.js';
+
+const QUERY_SCAFFOLD_RE = /^(?:where|when|how)\s+(?:does|do|did|is|are|was|were|can|could|should)?\s*/i;
+const IMPLEMENTATION_VERB_RE = /^(?:abort|bind|build|call|compute|create|decode|decide|detect|encode|handle|load|parse|parsed|redirect|register|run|search|skip|transform|validate|write)s?\b/i;
+const QUERY_STOPWORDS = new Set([
+  'a', 'an', 'are', 'can', 'could', 'did', 'do', 'does', 'for', 'from',
+  'how', 'in', 'into', 'is', 'of', 'on', 'should', 'the', 'to', 'was',
+  'were', 'when', 'where', 'with',
+]);
+
+function hasAblation(ablations, name) {
+  return ablations instanceof Set
+    ? ablations.has(name)
+    : Array.isArray(ablations) && ablations.includes(name);
+}
+
+// Per-stage profiling hooks. No-op unless `globalThis.__stageTimings` is set
+// by scripts/profile-search-stages.mjs. See search-postprocess.js for the
+// matching helpers — same convention for consistency.
+function __ptStart() {
+  return globalThis.__stageTimings ? performance.now() : null;
+}
+function __ptEnd(stage, t0) {
+  if (t0 == null || !globalThis.__stageTimings) return;
+  const ms = performance.now() - t0;
+  const buf = globalThis.__stageTimings;
+  (buf[stage] = buf[stage] || []).push(ms);
+}
+
+function envFloat(name, fallback, min = 0, max = 1) {
+  const raw = process.env[name];
+  if (raw == null || raw === '') return fallback;
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) && parsed >= min && parsed <= max ? parsed : fallback;
+}
+
+export function rewriteImplementationQuery(query) {
+  if (classifyFileKindIntent(query) !== 'implementation') return null;
+  const stripped = String(query || '').trim().replace(QUERY_SCAFFOLD_RE, '').trim();
+  if (!stripped) return null;
+
+  const words = stripped.split(/\s+/).filter(Boolean);
+  if (words.length >= 3 && /^[A-Z][A-Za-z0-9_.-]*$/.test(words[0]) && IMPLEMENTATION_VERB_RE.test(words[1])) {
+    words.shift();
+  }
+
+  const compact = words.filter(word => {
+    const normalized = word.toLowerCase().replace(/^[^\w]+|[^\w/.-]+$/g, '');
+    return normalized && !QUERY_STOPWORDS.has(normalized);
+  }).join(' ');
+
+  return compact && compact !== query ? compact : null;
+}
+
+function resultFileKind(result) {
+  return detectFileKind(
+    result?.file
+    || result?.file_path
+    || result?.path
+    || result?.metadata?.file
+    || result?.metadata?.file_path
+    || result?.metadata?.path
+    || ''
+  );
+}
+
+function implementationRetryReason(query, results) {
+  if (classifyFileKindIntent(query) !== 'implementation') return null;
+  if (!Array.isArray(results) || results.length === 0) return 'empty_results';
+
+  const window = results.slice(0, Math.min(5, results.length));
+  const hasImplementation = window.some(result => resultFileKind(result) === 'implementation');
+  const hasDemotable = window.some(result => resultFileKind(result) !== 'implementation');
+  return !hasImplementation && hasDemotable ? 'no_implementation_in_top_results' : null;
+}
 
 // =============================================================================
 // Hybrid Search V2
@@ -35,7 +112,13 @@ export async function hybridSearchV2(query, options = {}) {
   // without synthetic graph-expansion scores polluting the distribution.
   const [lexicalSearchResult, semanticSearchResult] = await Promise.all([
     this.graphSearch.bm25SearchRaw(query, 50),
-    this.semanticSearch(query, { k: 50, rerank: false, useLateInteraction }),
+    this.semanticSearch(query, {
+      k: 50,
+      rerank: false,
+      useLateInteraction,
+      format: options.format,
+      ablations: options.ablations,
+    }),
   ]);
 
   const lexicalResults = lexicalSearchResult.results.map(r => ({
@@ -48,26 +131,97 @@ export async function hybridSearchV2(query, options = {}) {
   const lexicalLatencyMs = lexicalSearchResult.latency ?? null;
 
   // Step 2: Robust CC fusion with RRF fallback for edge cases
+  const fusionAlpha = options.fusionAlpha ?? (
+    routing.rawMode === 'semantic'
+      ? envFloat('SWEET_SEARCH_COLLAPSED_SEMANTIC_ALPHA', undefined)
+      : undefined
+  );
   const { results: fused, method, fallbackReason } = this.robustCCFusion(
     lexicalResults,
     semanticResults,
-    routeType
+    routeType,
+    fusionAlpha == null ? undefined : { alpha: fusionAlpha }
+  );
+
+  // Step 2.5: Identifier-Anchored Retrieval (IAR).
+  // Couples dense fusion with an exact-name symbol lookup so abstract
+  // natural-language queries that mention a real entity name can land on
+  // that entity even when the encoder ranked something tangentially-similar
+  // higher. Mirrors the Aider repo-map / Cody+SCIP / Cursor recipe.
+  // Purely additive: only surfaces entities that exist in the index, deduped
+  // against the fused set. Disable via ablations 'no-anchor-injection' or
+  // env SWEET_SEARCH_DISABLE_IAR=1 (kill switch — overrides the format-based
+  // default for ablation experiments).
+  const iarKilled = process.env.SWEET_SEARCH_DISABLE_IAR === '1'
+    || hasAblation(options.ablations, 'no-anchor-injection');
+  const shouldInjectAnchors = !iarKilled && (
+    options.anchorInjection === true
+    || options.format === 'agent'
+    || process.env.SWEET_SEARCH_ANCHOR_INJECTION === '1'
   );
+  const __t_iar = __ptStart();
+  const { results: anchored, stats: anchorStats } = shouldInjectAnchors
+    ? injectAnchorCandidates(fused, query, {
+        codeGraphRepo: this.codeGraphRepo,
+        lateInteractionIndex: this.lateInteractionIndex,
+        ablations: options.ablations,
+        allowPlainTitlecase: options.format === 'agent',
+      })
+    : { results: fused, stats: { skipped: true, reason: 'disabled_for_non_agent_search' } };
+  __ptEnd('hybrid:injectAnchorCandidates', __t_iar);
 
   // Step 3: Apply post-fusion boosts uniformly (both paths benefit equally)
-  const boosted = this.applyPostFusionBoosts(fused, query, routing.mode, routing.confidence);
+  const boosted = this.applyPostFusionBoosts(anchored, query, routing.mode, routing.confidence, {
+    format: options.format,
+  });
+
+  // Step 3.5: Apply source-vs-doc/test/config preference before the top-k cut.
+  // The post-retrieval pass has the same guard, but hybrid used to slice first,
+  // so docs/tests/tiny YAML could occupy top-1 and hide implementation chunks.
+  const fileKindIntent = classifyFileKindIntent(query);
+  const __t_fk = __ptStart();
+  const rankedByFileKind = applyFileKindRanking(boosted, {
+    intent: fileKindIntent,
+    window: options.fileKindWindow ?? 100,
+    docFactor: options.hybridDocFactor ?? 0.35,
+    testFactor: options.hybridTestFactor ?? 0.35,
+    typeFactor: options.hybridTypeFactor ?? 0.70,
+    ancillaryFactor: options.hybridAncillaryFactor ?? 0.15,
+    tinyAncillaryFactor: options.hybridTinyAncillaryFactor ?? 0.05,
+    _fileKindCache: options._fileKindCache,
+  });
+  __ptEnd('hybrid:applyFileKindRanking', __t_fk);
+  const __t_dem = __ptStart();
+  const demoted = applyResultDemotions(rankedByFileKind, {
+    query,
+    window: options.resultDemotionWindow ?? 100,
+    ablations: options.ablations,
+    format: options.format,
+    projectRoot: this.projectRoot,
+    codeGraphRepo: this.codeGraphRepo,
+    _entityKindCache: options._entityKindCache,
+    _entityNameCache: options._entityNameCache,
+    _resultTextCache: options._resultTextCache,
+    _fullFileTextCache: options._fullFileTextCache,
+    _isTestSupportCache: options._isTestSupportCache,
+    _isTestChunkCache: options._isTestChunkCache,
+    _fileKindCache: options._fileKindCache,
+  });
+  __ptEnd('hybrid:applyResultDemotions', __t_dem);
 
   // Step 4: MMR Diversification (replaces flood control)
-  let diversified = boosted;
+  let diversified = demoted;
   let mmrStats = null;
 
-  const useMMR = options.useMMR ?? true; // Enable by default
-  if (useMMR && shouldApplyMMR(boosted)) {
+  const useMMR = (options.useMMR ?? true) && !hasAblation(options.ablations, 'no-mmr');
+  if (useMMR && shouldApplyMMR(demoted)) {
     const lambda = getLambdaForIntent(routing.mode, routing.confidence);
-    const mmrResult = applyMMR(boosted, {
-      k: Math.min(k * 2, boosted.length), // Get more candidates for diversity
+    const __t_mmr = __ptStart();
+    const mmrResult = applyMMR(demoted, {
+      k: Math.min(k * 2, demoted.length), // Get more candidates for diversity
       lambda,
     });
+    __ptEnd('hybrid:applyMMR', __t_mmr);
     diversified = mmrResult.results;
     mmrStats = mmrResult.stats;
 
@@ -83,10 +237,91 @@ export async function hybridSearchV2(query, options = {}) {
     fusionMethod: method,
   }));
 
-  this.log(`Hybrid V2 (${method}, alpha=${results[0]?.alpha?.toFixed(2) || '?'}): ${lexicalResults.length} lex + ${semanticResults.length} sem -> ${results.length} final`);
+  const retryReason = implementationRetryReason(query, results);
+  if (retryReason && options.allowQueryRewrite !== false && !hasAblation(options.ablations, 'no-query-rewrite')) {
+    const rewrittenQuery = rewriteImplementationQuery(query);
+    if (rewrittenQuery && rewrittenQuery !== query) {
+      this.log(`Hybrid rewrite retry: "${query}" -> "${rewrittenQuery}"`);
+      const retry = await hybridSearchV2.call(this, rewrittenQuery, {
+        ...options,
+        allowQueryRewrite: false,
+      });
+      retry.fusionStats = {
+        ...(retry.fusionStats || {}),
+        queryRewrite: {
+          from: query,
+          to: rewrittenQuery,
+          reason: retryReason,
+        },
+      };
+      return retry;
+    }
+  }
+
+  // Step 6: Multi-query BM25F + RRF tail fallback.
+  // Last-resort safety net: when hybrid + IAR + rewrite-retry STILL leaves
+  // top-1 below the confidence floor, the candidate list empty, or no
+  // source file in top-3, fire one BM25F query per content keyword
+  // and fuse with reciprocal-rank-fusion. RRF (Cormack 2009) is the
+  // SOTA pattern used by SWE-grep, Polarity Omnigrep, and Cody Deep
+  // Search; corpus-agnostic (no stopword denylist) and naturally
+  // demotes single-keyword noise hits via rank-position weighting.
+  // Disable via ablations 'no-rrf-fallback'.
+  let finalResults = results;
+  let fallbackStats = null;
+  if (options.allowKeywordFallback !== false) {
+    const __t_rrf = __ptStart();
+    const fb = await runRRFFallback(results, query, {
+      searcher: this,
+      ablations: options.ablations,
+      confidenceFloor: options.confidenceFloor,
+    });
+    __ptEnd('hybrid:runRRFFallback', __t_rrf);
+    fallbackStats = fb.stats;
+    if (fb.results !== results) {
+      // Re-run BOTH file-kind ranking AND content demotions on the merged
+      // set so doc/test/example demotion AND tiny/test-name/entity-kind
+      // rules apply to the RRF-injected chunks. Without the file-kind
+      // re-pass, a test-file chunk that RRF-fused on a couple of keywords
+      // would slip past the primary doc/test demotion.
+      const reRanked = applyFileKindRanking(fb.results, {
+        intent: fileKindIntent,
+        window: options.fileKindWindow ?? 100,
+        docFactor: options.hybridDocFactor ?? 0.35,
+        testFactor: options.hybridTestFactor ?? 0.35,
+        typeFactor: options.hybridTypeFactor ?? 0.70,
+        ancillaryFactor: options.hybridAncillaryFactor ?? 0.15,
+        tinyAncillaryFactor: options.hybridTinyAncillaryFactor ?? 0.05,
+      });
+      const remerged = applyResultDemotions(reRanked, {
+        query,
+        window: options.resultDemotionWindow ?? 100,
+        ablations: options.ablations,
+        format: options.format,
+        projectRoot: this.projectRoot,
+        codeGraphRepo: this.codeGraphRepo,
+        _entityKindCache: options._entityKindCache,
+        _entityNameCache: options._entityNameCache,
+        _resultTextCache: options._resultTextCache,
+        _fullFileTextCache: options._fullFileTextCache,
+        _isTestSupportCache: options._isTestSupportCache,
+        _isTestChunkCache: options._isTestChunkCache,
+        _fileKindCache: options._fileKindCache,
+      });
+      finalResults = remerged.slice(0, k).map(r => ({
+        ...r,
+        searchPath: r.searchPath || 'hybrid',
+        hybridScore: r.score,
+        fusionMethod: method,
+      }));
+      this.log(`Hybrid RRF fallback (${fb.stats.reason}, ${fb.stats.keywords.length}kw, ${fb.stats.fusedCount} fused): +${fb.stats.injected} new, +${fb.stats.boosted} boosted`);
+    }
+  }
+
+  this.log(`Hybrid V2 (${method}, alpha=${finalResults[0]?.alpha?.toFixed(2) || '?'}): ${lexicalResults.length} lex + ${semanticResults.length} sem -> ${finalResults.length} final`);
 
   return {
-    results,
+    results: finalResults,
     semanticStats,
     fusionStats: {
       method,
@@ -95,6 +330,11 @@ export async function hybridSearchV2(query, options = {}) {
       routerMode: routing.mode,
       routerConfidence: routing.confidence,
       lexicalLatencyMs,
+      fileKindIntent,
+      fileKindRankingApplied: rankedByFileKind !== boosted,
+      resultDemotionsApplied: demoted !== rankedByFileKind,
+      anchorInjection: anchorStats,
+      keywordFallback: fallbackStats,
     },
   };
 }