claude-code-workflow 6.3.53 → 7.0.0

package/codex-lens/src/codexlens/search/chain_search.py

@@ -13,6 +13,7 @@ from typing import List, Optional, Dict, Any, Literal, Tuple, TYPE_CHECKING
 import json
 import logging
 import os
+import threading
 import time
 
 from codexlens.entities import SearchResult, Symbol
@@ -32,7 +33,7 @@ from codexlens.storage.global_index import GlobalSymbolIndex
 from codexlens.storage.path_mapper import PathMapper
 from codexlens.storage.sqlite_store import SQLiteStore
 from codexlens.storage.vector_meta_store import VectorMetadataStore
-from codexlens.config import VECTORS_META_DB_NAME
+from codexlens.config import BINARY_VECTORS_MMAP_NAME, VECTORS_META_DB_NAME
 from codexlens.search.hybrid_search import HybridSearchEngine
 
 
@@ -55,7 +56,6 @@ class SearchOptions:
         enable_fuzzy: Enable fuzzy FTS in hybrid mode (default True)
         enable_vector: Enable vector semantic search (default False)
         pure_vector: If True, only use vector search without FTS fallback (default False)
-        enable_splade: Enable SPLADE sparse neural search (default False)
         enable_cascade: Enable cascade (binary+dense) two-stage retrieval (default False)
         hybrid_weights: Custom RRF weights for hybrid search (optional)
         group_results: Enable grouping of similar results (default False)
@@ -75,7 +75,6 @@ class SearchOptions:
     enable_fuzzy: bool = True
     enable_vector: bool = False
     pure_vector: bool = False
-    enable_splade: bool = False
     enable_cascade: bool = False
     hybrid_weights: Optional[Dict[str, float]] = None
     group_results: bool = False
@@ -167,6 +166,12 @@ class ChainSearchEngine:
         self._max_workers = max_workers
         self._executor: Optional[ThreadPoolExecutor] = None
         self._config = config
+        self._realtime_lsp_keepalive_lock = threading.RLock()
+        self._realtime_lsp_keepalive = None
+        self._realtime_lsp_keepalive_key = None
+        # Track which (workspace_root, config_file) pairs have already been warmed up.
+        # This avoids paying the warmup sleep on every query when using keep-alive LSP servers.
+        self._realtime_lsp_warmed_ids: set[tuple[str, str | None]] = set()
 
     def _get_executor(self, max_workers: Optional[int] = None) -> ThreadPoolExecutor:
         """Get or create the shared thread pool executor.
@@ -189,6 +194,15 @@ class ChainSearchEngine:
         if self._executor is not None:
             self._executor.shutdown(wait=True)
             self._executor = None
+        with self._realtime_lsp_keepalive_lock:
+            keepalive = self._realtime_lsp_keepalive
+            self._realtime_lsp_keepalive = None
+            self._realtime_lsp_keepalive_key = None
+        if keepalive is not None:
+            try:
+                keepalive.stop()
+            except Exception:
+                pass
 
     def __enter__(self) -> "ChainSearchEngine":
         """Context manager entry."""
@@ -306,154 +320,6 @@ class ChainSearchEngine:
             related_results=related_results,
         )
 
-    def hybrid_cascade_search(
-        self,
-        query: str,
-        source_path: Path,
-        k: int = 10,
-        coarse_k: int = 100,
-        options: Optional[SearchOptions] = None,
-    ) -> ChainSearchResult:
-        """Execute two-stage cascade search with hybrid coarse retrieval and cross-encoder reranking.
-
-        Hybrid cascade search process:
-        1. Stage 1 (Coarse): Fast retrieval using RRF fusion of FTS + SPLADE + Vector
-           to get coarse_k candidates
-        2. Stage 2 (Fine): CrossEncoder reranking of candidates to get final k results
-
-        This approach balances recall (from broad coarse search) with precision
-        (from expensive but accurate cross-encoder scoring).
-
-        Note: This method is the original hybrid approach. For binary vector cascade,
-        use binary_cascade_search() instead.
-
-        Args:
-            query: Natural language or keyword query string
-            source_path: Starting directory path
-            k: Number of final results to return (default 10)
-            coarse_k: Number of coarse candidates from first stage (default 100)
-            options: Search configuration (uses defaults if None)
-
-        Returns:
-            ChainSearchResult with reranked results and statistics
-
-        Examples:
-            >>> engine = ChainSearchEngine(registry, mapper, config=config)
-            >>> result = engine.hybrid_cascade_search(
-            ...     "how to authenticate users",
-            ...     Path("D:/project/src"),
-            ...     k=10,
-            ...     coarse_k=100
-            ... )
-            >>> for r in result.results:
-            ...     print(f"{r.path}: {r.score:.3f}")
-        """
-        options = options or SearchOptions()
-        start_time = time.time()
-        stats = SearchStats()
-
-        # Use config defaults if available
-        if self._config is not None:
-            if hasattr(self._config, "cascade_coarse_k"):
-                coarse_k = coarse_k or self._config.cascade_coarse_k
-            if hasattr(self._config, "cascade_fine_k"):
-                k = k or self._config.cascade_fine_k
-
-        # Step 1: Find starting index
-        start_index = self._find_start_index(source_path)
-        if not start_index:
-            self.logger.warning(f"No index found for {source_path}")
-            stats.time_ms = (time.time() - start_time) * 1000
-            return ChainSearchResult(
-                query=query,
-                results=[],
-                symbols=[],
-                stats=stats
-            )
-
-        # Step 2: Collect all index paths
-        index_paths = self._collect_index_paths(start_index, options.depth)
-        stats.dirs_searched = len(index_paths)
-
-        if not index_paths:
-            self.logger.warning(f"No indexes collected from {start_index}")
-            stats.time_ms = (time.time() - start_time) * 1000
-            return ChainSearchResult(
-                query=query,
-                results=[],
-                symbols=[],
-                stats=stats
-            )
-
-        # Stage 1: Coarse retrieval with hybrid search (FTS + SPLADE + Vector)
-        # Use hybrid mode for multi-signal retrieval
-        coarse_options = SearchOptions(
-            depth=options.depth,
-            max_workers=1,  # Single thread for GPU safety
-            limit_per_dir=max(coarse_k // len(index_paths), 20),
-            total_limit=coarse_k,
-            hybrid_mode=True,
-            enable_fuzzy=options.enable_fuzzy,
-            enable_vector=True,  # Enable vector for semantic matching
-            pure_vector=False,
-            hybrid_weights=options.hybrid_weights,
-        )
-
-        self.logger.debug(
-            "Cascade Stage 1: Coarse retrieval for %d candidates", coarse_k
-        )
-        coarse_results, search_stats = self._search_parallel(
-            index_paths, query, coarse_options
-        )
-        stats.errors = search_stats.errors
-
-        # Merge and deduplicate coarse results
-        coarse_merged = self._merge_and_rank(coarse_results, coarse_k)
-        self.logger.debug(
-            "Cascade Stage 1 complete: %d candidates retrieved", len(coarse_merged)
-        )
-
-        if not coarse_merged:
-            stats.time_ms = (time.time() - start_time) * 1000
-            return ChainSearchResult(
-                query=query,
-                results=[],
-                symbols=[],
-                stats=stats
-            )
-
-        # Stage 2: Cross-encoder reranking
-        self.logger.debug(
-            "Cascade Stage 2: Cross-encoder reranking %d candidates to top-%d",
-            len(coarse_merged),
-            k,
-        )
-
-        final_results = self._cross_encoder_rerank(query, coarse_merged, k)
-
-        # Optional: grouping of similar results
-        if options.group_results:
-            from codexlens.search.ranking import group_similar_results
-            final_results = group_similar_results(
-                final_results, score_threshold_abs=options.grouping_threshold
-            )
-
-        stats.files_matched = len(final_results)
-        stats.time_ms = (time.time() - start_time) * 1000
-
-        self.logger.debug(
-            "Cascade search complete: %d results in %.2fms",
-            len(final_results),
-            stats.time_ms,
-        )
-
-        return ChainSearchResult(
-            query=query,
-            results=final_results,
-            symbols=[],
-            stats=stats,
-        )
-
     def binary_cascade_search(
         self,
         query: str,
@@ -501,9 +367,9 @@ class ChainSearchEngine:
         """
         if not NUMPY_AVAILABLE:
             self.logger.warning(
-                "NumPy not available, falling back to hybrid cascade search"
+                "NumPy not available, falling back to standard search"
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         options = options or SearchOptions()
         start_time = time.time()
@@ -552,10 +418,10 @@ class ChainSearchEngine:
         except ImportError as exc:
             self.logger.warning(
                 "Binary cascade dependencies not available: %s. "
-                "Falling back to hybrid cascade search.",
+                "Falling back to standard search.",
                 exc
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         # Stage 1: Binary vector coarse retrieval
         self.logger.debug(
@@ -573,10 +439,10 @@ class ChainSearchEngine:
         except Exception as exc:
             self.logger.warning(
                 "Failed to generate binary query embedding: %s. "
-                "Falling back to hybrid cascade search.",
+                "Falling back to standard search.",
                 exc
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         # Try centralized BinarySearcher first (preferred for mmap indexes)
         # The index root is the parent of the first index path
@@ -629,8 +495,8 @@ class ChainSearchEngine:
                     stats.errors.append(f"Binary search failed for {index_path}: {exc}")
 
         if not all_candidates:
-            self.logger.debug("No binary candidates found, falling back to hybrid")
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            self.logger.debug("No binary candidates found, falling back to standard search")
+            return self.search(query, source_path, options=options)
 
         # Sort by Hamming distance and take top coarse_k
         all_candidates.sort(key=lambda x: x[1])
@@ -828,14 +694,14 @@ class ChainSearchEngine:
         k: int = 10,
         coarse_k: int = 100,
         options: Optional[SearchOptions] = None,
-        strategy: Optional[Literal["binary", "hybrid", "binary_rerank", "dense_rerank", "staged"]] = None,
+        strategy: Optional[Literal["binary", "binary_rerank", "dense_rerank", "staged", "hybrid"]] = None,
     ) -> ChainSearchResult:
         """Unified cascade search entry point with strategy selection.
 
         Provides a single interface for cascade search with configurable strategy:
         - "binary": Uses binary vector coarse ranking + dense fine ranking (fastest)
-        - "hybrid": Uses FTS+SPLADE+Vector coarse ranking + cross-encoder reranking (original)
         - "binary_rerank": Uses binary vector coarse ranking + cross-encoder reranking (best balance)
+        - "hybrid": Alias for "binary_rerank" (backward compat)
         - "dense_rerank": Uses dense vector coarse ranking + cross-encoder reranking
         - "staged": 4-stage pipeline: binary -> LSP expand -> clustering -> optional rerank
 
@@ -850,7 +716,7 @@ class ChainSearchEngine:
             k: Number of final results to return (default 10)
             coarse_k: Number of coarse candidates from first stage (default 100)
             options: Search configuration (uses defaults if None)
-            strategy: Cascade strategy - "binary", "hybrid", "binary_rerank", "dense_rerank", or "staged".
+            strategy: Cascade strategy - "binary", "binary_rerank", "dense_rerank", or "staged".
 
         Returns:
             ChainSearchResult with reranked results and statistics
@@ -859,8 +725,6 @@ class ChainSearchEngine:
             >>> engine = ChainSearchEngine(registry, mapper, config=config)
             >>> # Use binary cascade (default, fastest)
             >>> result = engine.cascade_search("auth", Path("D:/project"))
-            >>> # Use hybrid cascade (original behavior)
-            >>> result = engine.cascade_search("auth", Path("D:/project"), strategy="hybrid")
             >>> # Use binary + cross-encoder (best balance of speed and quality)
             >>> result = engine.cascade_search("auth", Path("D:/project"), strategy="binary_rerank")
             >>> # Use 4-stage pipeline (binary + LSP expand + clustering + optional rerank)
@@ -868,7 +732,7 @@ class ChainSearchEngine:
         """
         # Strategy priority: parameter > config > default
         effective_strategy = strategy
-        valid_strategies = ("binary", "hybrid", "binary_rerank", "dense_rerank", "staged")
+        valid_strategies = ("binary", "binary_rerank", "dense_rerank", "staged", "hybrid")
         if effective_strategy is None:
             # Not passed via parameter, check config
             if self._config is not None:
@@ -880,6 +744,10 @@ class ChainSearchEngine:
         if effective_strategy not in valid_strategies:
             effective_strategy = "binary"
 
+        # Normalize backward-compat alias
+        if effective_strategy == "hybrid":
+            effective_strategy = "binary_rerank"
+
         if effective_strategy == "binary":
             return self.binary_cascade_search(query, source_path, k, coarse_k, options)
         elif effective_strategy == "binary_rerank":
@@ -889,7 +757,7 @@ class ChainSearchEngine:
         elif effective_strategy == "staged":
             return self.staged_cascade_search(query, source_path, k, coarse_k, options)
         else:
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.binary_cascade_search(query, source_path, k, coarse_k, options)
 
     def staged_cascade_search(
         self,
@@ -943,9 +811,9 @@ class ChainSearchEngine:
         """
         if not NUMPY_AVAILABLE:
             self.logger.warning(
-                "NumPy not available, falling back to hybrid cascade search"
+                "NumPy not available, falling back to standard search"
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         options = options or SearchOptions()
         start_time = time.time()
@@ -991,7 +859,11 @@ class ChainSearchEngine:
         # ========== Stage 1: Binary Coarse Search ==========
         stage1_start = time.time()
         coarse_results, index_root = self._stage1_binary_search(
-            query, index_paths, coarse_k, stats
+            query,
+            index_paths,
+            coarse_k,
+            stats,
+            index_root=start_index.parent,
         )
         stage_times["stage1_binary_ms"] = (time.time() - stage1_start) * 1000
         stage_counts["stage1_candidates"] = len(coarse_results)
@@ -1002,14 +874,47 @@ class ChainSearchEngine:
         )
 
         if not coarse_results:
-            self.logger.debug("No binary candidates found, falling back to hybrid cascade")
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            # Keep the staged pipeline running even when Stage 1 yields no candidates.
+            # This makes "realtime LSP graph → clustering → rerank" comparable across queries.
+            self.logger.debug(
+                "No Stage 1 candidates found; seeding staged pipeline with FTS results"
+            )
+            stage1_fallback_start = time.time()
+            try:
+                seed_opts = SearchOptions(
+                    depth=options.depth,
+                    max_workers=options.max_workers,
+                    limit_per_dir=max(10, int(coarse_k)),
+                    total_limit=int(coarse_k),
+                    include_symbols=True,
+                    enable_vector=False,
+                    hybrid_mode=False,
+                    enable_cascade=False,
+                )
+                seed = self.search(query, source_path, options=seed_opts)
+                coarse_results = list(seed.results or [])[: int(coarse_k)]
+                stage_counts["stage1_fallback_used"] = 1
+            except Exception as exc:
+                self.logger.debug("Stage 1 fallback seeding failed: %r", exc)
+                coarse_results = []
+
+            stage_times["stage1_fallback_search_ms"] = (time.time() - stage1_fallback_start) * 1000
+            stage_counts["stage1_candidates"] = len(coarse_results)
+
+        if not coarse_results:
+            return ChainSearchResult(query=query, results=[], symbols=[], stats=stats)
 
         # ========== Stage 2: LSP Graph Expansion ==========
         stage2_start = time.time()
-        expanded_results = self._stage2_lsp_expand(coarse_results, index_root)
+        expanded_results = self._stage2_lsp_expand(coarse_results, index_root, query=query)
         stage_times["stage2_expand_ms"] = (time.time() - stage2_start) * 1000
         stage_counts["stage2_expanded"] = len(expanded_results)
+        try:
+            stage2_unique_paths = len({(r.path or "").lower() for r in expanded_results if getattr(r, "path", None)})
+        except Exception:
+            stage2_unique_paths = 0
+        stage_counts["stage2_unique_paths"] = stage2_unique_paths
+        stage_counts["stage2_duplicate_paths"] = max(0, len(expanded_results) - stage2_unique_paths)
 
         self.logger.debug(
             "Staged Stage 2: LSP expansion %d -> %d results in %.2fms",
@@ -1021,6 +926,11 @@ class ChainSearchEngine:
         clustered_results = self._stage3_cluster_prune(expanded_results, k * 2)
         stage_times["stage3_cluster_ms"] = (time.time() - stage3_start) * 1000
         stage_counts["stage3_clustered"] = len(clustered_results)
+        if self._config is not None:
+            try:
+                stage_counts["stage3_strategy"] = str(getattr(self._config, "staged_clustering_strategy", "auto") or "auto")
+            except Exception:
+                pass
 
         self.logger.debug(
             "Staged Stage 3: Clustering %d -> %d representatives in %.2fms",
@@ -1097,6 +1007,8 @@ class ChainSearchEngine:
         index_paths: List[Path],
         coarse_k: int,
         stats: SearchStats,
+        *,
+        index_root: Optional[Path] = None,
     ) -> Tuple[List[SearchResult], Optional[Path]]:
         """Stage 1: Binary vector coarse search using Hamming distance.
 
@@ -1120,18 +1032,40 @@ class ChainSearchEngine:
             )
             return [], None
 
-        # Try centralized BinarySearcher first (preferred for mmap indexes)
-        index_root = index_paths[0].parent if index_paths else None
-        coarse_candidates: List[Tuple[int, int, Path]] = []  # (chunk_id, distance, index_path)
+        # Try centralized BinarySearcher first (preferred for mmap indexes).
+        # Centralized binary vectors live at a project index root (where `index binary-mmap`
+        # was run), which may be an ancestor of the nearest `_index.db` directory.
+        index_root = Path(index_root).resolve() if index_root is not None else (index_paths[0].parent if index_paths else None)
+        if index_root is not None:
+            index_root = self._find_nearest_binary_mmap_root(index_root)
+        coarse_candidates: List[Tuple[int, float, Path]] = []  # (chunk_id, distance, index_path)
         used_centralized = False
+        using_dense_fallback = False
 
         if index_root:
             binary_searcher = self._get_centralized_binary_searcher(index_root)
             if binary_searcher is not None:
                 try:
-                    from codexlens.semantic.embedder import Embedder
-                    embedder = Embedder()
-                    query_dense = embedder.embed_to_numpy([query])[0]
+                    use_gpu = True
+                    if self._config is not None:
+                        use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+                    query_dense = None
+                    backend = getattr(binary_searcher, "backend", None)
+                    model = getattr(binary_searcher, "model", None)
+                    profile = getattr(binary_searcher, "model_profile", None) or "code"
+
+                    if backend == "litellm":
+                        try:
+                            from codexlens.semantic.factory import get_embedder as get_factory_embedder
+                            embedder = get_factory_embedder(backend="litellm", model=model or "code")
+                            query_dense = embedder.embed_to_numpy([query])[0]
+                        except Exception:
+                            query_dense = None
+                    if query_dense is None:
+                        from codexlens.semantic.embedder import get_embedder
+                        embedder = get_embedder(profile=str(profile), use_gpu=use_gpu)
+                        query_dense = embedder.embed_to_numpy([query])[0]
 
                     results = binary_searcher.search(query_dense, top_k=coarse_k)
                     for chunk_id, distance in results:
@@ -1145,30 +1079,78 @@ class ChainSearchEngine:
                     self.logger.debug(f"Centralized binary search failed: {exc}")
 
         if not used_centralized:
-            # Fallback to per-directory binary indexes
-            use_gpu = True
-            if self._config is not None:
-                use_gpu = getattr(self._config, "embedding_use_gpu", True)
+            # Fallback to per-directory binary indexes (legacy BinaryANNIndex).
+            #
+            # Generating the query binary embedding can be expensive (depending on embedding backend).
+            # If no legacy binary vector files exist, skip this path and fall back to dense ANN search.
+            has_legacy_binary_vectors = any(
+                (p.parent / f"{p.stem}_binary_vectors.bin").exists() for p in index_paths
+            )
+            if not has_legacy_binary_vectors:
+                self.logger.debug(
+                    "No legacy binary vector files found; skipping legacy binary search fallback"
+                )
+            else:
+                use_gpu = True
+                if self._config is not None:
+                    use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+                query_binary = None
+                try:
+                    binary_backend = BinaryEmbeddingBackend(use_gpu=use_gpu)
+                    query_binary = binary_backend.embed_packed([query])[0]
+                except Exception as exc:
+                    self.logger.warning(f"Failed to generate binary query embedding: {exc}")
+                    query_binary = None
+
+                if query_binary is not None:
+                    for index_path in index_paths:
+                        try:
+                            binary_index = self._get_or_create_binary_index(index_path)
+                            if binary_index is None or binary_index.count() == 0:
+                                continue
+                            ids, distances = binary_index.search(query_binary, coarse_k)
+                            for chunk_id, dist in zip(ids, distances):
+                                coarse_candidates.append((chunk_id, float(dist), index_path))
+                        except Exception as exc:
+                            self.logger.debug(
+                                "Binary search failed for %s: %s", index_path, exc
+                            )
 
+        if not coarse_candidates:
+            # Final fallback: dense ANN coarse search (HNSW) over existing dense vector indexes.
+            #
+            # This allows the staged pipeline (LSP expansion + clustering) to run even when
+            # binary vectors are not generated for the current project.
+            dense_candidates: List[Tuple[int, float, Path]] = []
             try:
-                binary_backend = BinaryEmbeddingBackend(use_gpu=use_gpu)
-                query_binary = binary_backend.embed_packed([query])[0]
+                from codexlens.semantic.ann_index import ANNIndex
+                from codexlens.semantic.embedder import Embedder
+
+                embedder = Embedder()
+                query_dense = embedder.embed_to_numpy([query])[0]
+                dim = int(getattr(query_dense, "shape", (len(query_dense),))[0])
+
+                for index_path in index_paths:
+                    try:
+                        ann_index = ANNIndex(index_path, dim=dim)
+                        if not ann_index.load() or ann_index.count() == 0:
+                            continue
+                        ids, distances = ann_index.search(query_dense, top_k=coarse_k)
+                        for chunk_id, dist in zip(ids, distances):
+                            dense_candidates.append((chunk_id, float(dist), index_path))
+                    except Exception as exc:
+                        self.logger.debug(
+                            "Dense coarse search failed for %s: %s", index_path, exc
+                        )
             except Exception as exc:
-                self.logger.warning(f"Failed to generate binary query embedding: {exc}")
-                return [], index_root
+                self.logger.debug("Dense coarse search fallback unavailable: %s", exc)
+                dense_candidates = []
 
-            for index_path in index_paths:
-                try:
-                    binary_index = self._get_or_create_binary_index(index_path)
-                    if binary_index is None or binary_index.count() == 0:
-                        continue
-                    ids, distances = binary_index.search(query_binary, coarse_k)
-                    for chunk_id, dist in zip(ids, distances):
-                        coarse_candidates.append((chunk_id, dist, index_path))
-                except Exception as exc:
-                    self.logger.debug(
-                        "Binary search failed for %s: %s", index_path, exc
-                    )
+            if dense_candidates:
+                dense_candidates.sort(key=lambda x: x[1])
+                coarse_candidates = dense_candidates[:coarse_k]
+                using_dense_fallback = True
 
         if not coarse_candidates:
             return [], index_root
@@ -1239,7 +1221,11 @@ class ChainSearchEngine:
                         (d for cid, d, _ in coarse_candidates if cid == chunk_id),
                         256
                     )
-                    score = 1.0 - (distance / 256.0)
+                    if using_dense_fallback:
+                        # Cosine distance in [0, 2] -> clamp to [0, 1] score
+                        score = max(0.0, 1.0 - float(distance))
+                    else:
+                        score = 1.0 - (int(distance) / 256.0)
 
                     content = chunk.get("content", "")
 
@@ -1247,15 +1233,15 @@ class ChainSearchEngine:
                     metadata = chunk.get("metadata")
                     symbol_name = None
                     symbol_kind = None
-                    start_line = None
-                    end_line = None
+                    start_line = chunk.get("start_line")
+                    end_line = chunk.get("end_line")
                     if metadata:
                         try:
                             meta_dict = json.loads(metadata) if isinstance(metadata, str) else metadata
                             symbol_name = meta_dict.get("symbol_name")
                             symbol_kind = meta_dict.get("symbol_kind")
-                            start_line = meta_dict.get("start_line")
-                            end_line = meta_dict.get("end_line")
+                            start_line = meta_dict.get("start_line", start_line)
+                            end_line = meta_dict.get("end_line", end_line)
                         except Exception:
                             pass
 
@@ -1282,11 +1268,13 @@ class ChainSearchEngine:
         self,
         coarse_results: List[SearchResult],
         index_root: Optional[Path],
+        query: Optional[str] = None,
     ) -> List[SearchResult]:
-        """Stage 2: LSP-based graph expansion using GraphExpander.
+        """Stage 2: LSP/graph expansion for staged cascade.
 
-        Expands coarse results with related symbols (definitions, references,
-        callers, callees) using precomputed graph neighbors.
+        Supports two modes via Config.staged_stage2_mode:
+        - "precomputed" (default): GraphExpander over per-dir `graph_neighbors` table
+        - "realtime": on-demand graph expansion via live LSP servers (LspBridge + LspGraphBuilder)
 
         Args:
             coarse_results: Results from Stage 1 binary search
@@ -1299,52 +1287,566 @@ class ChainSearchEngine:
             return coarse_results
 
         try:
-            from codexlens.search.graph_expander import GraphExpander
+            mode = "precomputed"
+            if self._config is not None:
+                mode = (getattr(self._config, "staged_stage2_mode", "precomputed") or "precomputed").strip().lower()
+
+            if mode in {"realtime", "live"}:
+                return self._stage2_realtime_lsp_expand(
+                    coarse_results,
+                    index_root=index_root,
+                    query=query,
+                )
 
-            # Get expansion depth from config
+            if mode == "static_global_graph":
+                return self._stage2_static_global_graph_expand(coarse_results, index_root=index_root)
+
+            return self._stage2_precomputed_graph_expand(coarse_results, index_root=index_root)
+
+        except ImportError as exc:
+            self.logger.debug("GraphExpander not available: %s", exc)
+            return coarse_results
+        except Exception as exc:
+            self.logger.debug("Stage 2 LSP expansion failed: %s", exc)
+            return coarse_results
+
+    def _stage2_precomputed_graph_expand(
+        self,
+        coarse_results: List[SearchResult],
+        *,
+        index_root: Path,
+    ) -> List[SearchResult]:
+        """Stage 2 (precomputed): expand using GraphExpander over `graph_neighbors`."""
+        from codexlens.search.graph_expander import GraphExpander
+
+        depth = 2
+        if self._config is not None:
+            depth = getattr(
+                self._config,
+                "staged_lsp_depth",
+                getattr(self._config, "graph_expansion_depth", 2),
+            )
+        try:
+            depth = int(depth)
+        except Exception:
             depth = 2
-            if self._config is not None:
-                depth = getattr(self._config, "graph_expansion_depth", 2)
 
-            expander = GraphExpander(self.mapper, config=self._config)
+        expander = GraphExpander(self.mapper, config=self._config)
+
+        max_expand = min(10, len(coarse_results))
+        max_related = 50
+
+        related_results = expander.expand(
+            coarse_results,
+            depth=depth,
+            max_expand=max_expand,
+            max_related=max_related,
+        )
+
+        if related_results:
+            self.logger.debug(
+                "Stage 2 (precomputed) expanded %d base results to %d related symbols",
+                len(coarse_results), len(related_results)
+            )
+
+        return self._combine_stage2_results(coarse_results, related_results)
 
-            # Expand top results (limit expansion to avoid explosion)
-            max_expand = min(10, len(coarse_results))
-            max_related = 50
+    def _stage2_static_global_graph_expand(
+        self,
+        coarse_results: List[SearchResult],
+        *,
+        index_root: Path,
+    ) -> List[SearchResult]:
+        """Stage 2 (static_global_graph): expand using GlobalGraphExpander over global_relationships."""
+        from codexlens.search.global_graph_expander import GlobalGraphExpander
+
+        global_db_path = index_root / GlobalSymbolIndex.DEFAULT_DB_NAME
+        if not global_db_path.exists():
+            self.logger.debug("Global symbol DB not found at %s, skipping static graph expansion", global_db_path)
+            return coarse_results
+
+        project_id = 1
+        try:
+            for p in self.registry.list_projects():
+                if p.index_root.resolve() == index_root.resolve():
+                    project_id = p.id
+                    break
+        except Exception:
+            pass
 
+        global_index = GlobalSymbolIndex(global_db_path, project_id=project_id)
+        global_index.initialize()
+
+        try:
+            expander = GlobalGraphExpander(global_index, config=self._config)
             related_results = expander.expand(
                 coarse_results,
-                depth=depth,
-                max_expand=max_expand,
-                max_related=max_related,
+                top_n=min(10, len(coarse_results)),
+                max_related=50,
             )
 
             if related_results:
                 self.logger.debug(
-                    "Stage 2 expanded %d base results to %d related symbols",
-                    len(coarse_results), len(related_results)
+                    "Stage 2 (static_global_graph) expanded %d base results to %d related symbols",
+                    len(coarse_results), len(related_results),
                 )
 
-            # Combine: original results + related results
-            # Keep original results first (higher relevance)
-            combined = list(coarse_results)
-            seen_keys = {(r.path, r.symbol_name, r.start_line) for r in coarse_results}
+            return self._combine_stage2_results(coarse_results, related_results)
+        finally:
+            global_index.close()
 
-            for related in related_results:
-                key = (related.path, related.symbol_name, related.start_line)
-                if key not in seen_keys:
-                    seen_keys.add(key)
-                    combined.append(related)
+    def _stage2_realtime_lsp_expand(
+        self,
+        coarse_results: List[SearchResult],
+        *,
+        index_root: Path,
+        query: Optional[str] = None,
+    ) -> List[SearchResult]:
+        """Stage 2 (realtime): compute expansion graph via live LSP servers."""
+        import asyncio
+        from concurrent.futures import ThreadPoolExecutor
+
+        from codexlens.hybrid_search.data_structures import CodeSymbolNode, Range
+        from codexlens.lsp import LspBridge, LspGraphBuilder
+
+        max_depth = 1
+        timeout_s = 30.0
+        max_nodes = 50
+        max_seeds = 1
+        max_concurrent = 2
+        warmup_s = 3.0
+        resolve_symbols = False
+        if self._config is not None:
+            max_depth = int(
+                getattr(
+                    self._config,
+                    "staged_realtime_lsp_depth",
+                    getattr(self._config, "staged_lsp_depth", 1),
+                )
+                or 1
+            )
+            timeout_s = float(getattr(self._config, "staged_realtime_lsp_timeout_s", 30.0) or 30.0)
+            max_nodes = int(getattr(self._config, "staged_realtime_lsp_max_nodes", 50) or 50)
+            warmup_s = float(getattr(self._config, "staged_realtime_lsp_warmup_s", 3.0) or 0.0)
+            max_seeds = int(getattr(self._config, "staged_realtime_lsp_max_seeds", 1) or 1)
+            max_concurrent = int(getattr(self._config, "staged_realtime_lsp_max_concurrent", 2) or 2)
+            resolve_symbols = bool(getattr(self._config, "staged_realtime_lsp_resolve_symbols", False))
 
-            return combined
+        try:
+            source_root = self.mapper.index_to_source(index_root)
+        except Exception:
+            source_root = Path(coarse_results[0].path).resolve().parent
+
+        lsp_config_file = self._find_lsp_config_file(source_root)
+        workspace_root = Path(source_root).resolve()
+
+        max_expand = min(max(1, max_seeds), len(coarse_results))
+        seed_nodes: List[CodeSymbolNode] = []
+        seed_ids: set[str] = set()
+
+        selected_results = list(coarse_results)
+        if query:
+            import re
+
+            terms = {
+                t.lower()
+                for t in re.findall(r"[A-Za-z_][A-Za-z0-9_]*", query)
+                if t
+            }
+
+            def _priority(result: SearchResult) -> float:
+                sym = (result.symbol_name or "").strip().lower()
+                stem = Path(result.path).stem.lower() if result.path else ""
+                score = 0.0
+                if sym and sym in terms:
+                    score += 5.0
+                if sym:
+                    score += 2.0
+                if stem and stem in terms:
+                    score += 1.0
+                if result.symbol_kind:
+                    score += 0.5
+                if result.start_line:
+                    score += 0.2
+                return score
+
+            indexed = list(enumerate(selected_results))
+            indexed.sort(
+                key=lambda pair: (
+                    _priority(pair[1]),
+                    float(pair[1].score),
+                    -pair[0],
+                ),
+                reverse=True,
+            )
+            selected_results = [r for _, r in indexed]
+        else:
+            indexed = list(enumerate(selected_results))
+            indexed.sort(
+                key=lambda pair: (
+                    1.0 if pair[1].symbol_name else 0.0,
+                    float(pair[1].score),
+                    -pair[0],
+                ),
+                reverse=True,
+            )
+            selected_results = [r for _, r in indexed]
+
+        # Prefer symbol-definition seeds when possible (improves LSP reference/call-hierarchy results).
+        #
+        # NOTE: We avoid relying purely on the stored symbol index here because its ranges may be
+        # imprecise in some projects. Instead, we attempt a lightweight definition-line detection
+        # for query identifiers within the top coarse candidate files.
+        if query:
+            try:
+                import re
+
+                terms_raw = [
+                    t for t in re.findall(r"[A-Za-z_][A-Za-z0-9_]*", query) if t
+                ]
+                stopwords = {
+                    "class", "def", "function", "method", "import", "from", "return",
+                    "async", "await", "public", "private", "protected", "static",
+                    "const", "let", "var", "new",
+                }
+                candidate_terms = [
+                    t for t in terms_raw
+                    if t.lower() not in stopwords and len(t) >= 3
+                ]
+
+                candidate_terms.sort(key=len, reverse=True)
+
+                # Candidate files (best-first): de-dupe while preserving ordering.
+                candidate_files: List[str] = []
+                seen_files: set[str] = set()
+                for r in selected_results:
+                    if r.path and r.path not in seen_files:
+                        seen_files.add(r.path)
+                        candidate_files.append(r.path)
+                    if len(candidate_files) >= 50:
+                        break
+
+                # Also consider files whose *names* match query identifiers (helps when coarse retrieval
+                # misses the defining file for a symbol like `Config`).
+                try:
+                    if source_root and candidate_terms:
+                        allow_suffix = {".py", ".ts", ".tsx", ".js", ".jsx"}
+                        name_terms = [t.lower() for t in candidate_terms[:3]]
+                        for dirpath, _, filenames in os.walk(source_root):
+                            for filename in filenames:
+                                suffix = Path(filename).suffix.lower()
+                                if suffix not in allow_suffix:
+                                    continue
+                                lowered = filename.lower()
+                                if any(t in lowered for t in name_terms):
+                                    fp = str(Path(dirpath) / filename)
+                                    if fp not in seen_files:
+                                        seen_files.add(fp)
+                                        candidate_files.append(fp)
+                            if len(candidate_files) >= 120:
+                                break
+                except Exception:
+                    pass
+
+                for term in candidate_terms[:5]:
+                    if len(seed_nodes) >= max_expand:
+                        break
+
+                    escaped = re.escape(term)
+                    py_class = re.compile(rf"^\s*class\s+{escaped}\b")
+                    py_def = re.compile(rf"^\s*(?:async\s+)?def\s+{escaped}\b")
+                    ts_class = re.compile(rf"^\s*(?:export\s+)?class\s+{escaped}\b")
+                    ts_func = re.compile(rf"^\s*(?:export\s+)?(?:async\s+)?function\s+{escaped}\b")
+
+                    for file_path in candidate_files:
+                        if len(seed_nodes) >= max_expand:
+                            break
+                        suffix = Path(file_path).suffix.lower()
+                        if suffix not in {".py", ".ts", ".tsx", ".js", ".jsx"}:
+                            continue
 
-        except ImportError as exc:
-            self.logger.debug("GraphExpander not available: %s", exc)
+                        try:
+                            lines = Path(file_path).read_text(encoding="utf-8", errors="ignore").splitlines()
+                        except Exception:
+                            continue
+
+                        for i, line in enumerate(lines):
+                            kind = None
+                            if suffix == ".py":
+                                if py_class.search(line):
+                                    kind = "class"
+                                elif py_def.search(line):
+                                    kind = "function"
+                            else:
+                                if ts_class.search(line):
+                                    kind = "class"
+                                elif ts_func.search(line):
+                                    kind = "function"
+
+                            if not kind:
+                                continue
+
+                            start_line = i + 1
+                            idx = line.find(term)
+                            if idx >= 0:
+                                start_character = idx + 1
+                            else:
+                                stripped = line.lstrip()
+                                start_character = (len(line) - len(stripped)) + 1 if stripped else 1
+
+                            node_id = f"{file_path}:{term}:{start_line}"
+                            if node_id in seed_ids:
+                                break
+
+                            seed_ids.add(node_id)
+                            seed_nodes.append(
+                                CodeSymbolNode(
+                                    id=node_id,
+                                    name=term,
+                                    kind=kind,
+                                    file_path=file_path,
+                                    range=Range(
+                                        start_line=start_line,
+                                        start_character=start_character,
+                                        end_line=start_line,
+                                        end_character=start_character,
+                                    ),
+                                )
+                            )
+                            break
+            except Exception:
+                pass
+
+        for seed in selected_results:
+            if len(seed_nodes) >= max_expand:
+                break
+            if not seed.path:
+                continue
+            name = seed.symbol_name or Path(seed.path).stem
+            kind = seed.symbol_kind or "unknown"
+            start_line = int(seed.start_line or 1)
+            end_line = int(seed.end_line or start_line)
+            start_character = 1
+            try:
+                if start_line >= 1:
+                    line_text = Path(seed.path).read_text(encoding="utf-8", errors="ignore").splitlines()[start_line - 1]
+                    if seed.symbol_name:
+                        idx = line_text.find(seed.symbol_name)
+                        if idx >= 0:
+                            start_character = idx + 1  # 1-based for StandaloneLspManager
+                    else:
+                        stripped = line_text.lstrip()
+                        if stripped:
+                            start_character = (len(line_text) - len(stripped)) + 1
+            except Exception:
+                start_character = 1
+            node_id = f"{seed.path}:{name}:{start_line}"
+            if node_id in seed_ids:
+                continue
+            seed_ids.add(node_id)
+            seed_nodes.append(
+                CodeSymbolNode(
+                    id=node_id,
+                    name=name,
+                    kind=kind,
+                    file_path=seed.path,
+                    range=Range(
+                        start_line=start_line,
+                        start_character=start_character,
+                        end_line=end_line,
+                        end_character=start_character if end_line == start_line else 1,
+                    ),
+                    raw_code=seed.content or "",
+                    docstring=seed.excerpt or "",
+                )
+            )
+
+        if not seed_nodes:
             return coarse_results
+
+        effective_warmup_s = warmup_s
+
+        async def expand_graph(bridge: LspBridge):
+            # Warm up analysis: open seed docs and wait a bit so references/call hierarchy are populated.
+            if effective_warmup_s > 0:
+                for seed in seed_nodes[:3]:
+                    try:
+                        await bridge.get_document_symbols(seed.file_path)
+                    except Exception:
+                        continue
+                try:
+                    warmup_budget = min(effective_warmup_s, max(0.0, timeout_s * 0.1))
+                    await asyncio.sleep(min(warmup_budget, max(0.0, timeout_s - 0.5)))
+                except Exception:
+                    pass
+            builder = LspGraphBuilder(
+                max_depth=max_depth,
+                max_nodes=max_nodes,
+                max_concurrent=max(1, max_concurrent),
+                resolve_symbols=resolve_symbols,
+            )
+            return await builder.build_from_seeds(seed_nodes, bridge)
+
+        try:
+            try:
+                asyncio.get_running_loop()
+                has_running_loop = True
+            except RuntimeError:
+                has_running_loop = False
+
+            if has_running_loop:
+                with ThreadPoolExecutor(max_workers=1) as executor:
+                    async def _expand_once():
+                        async with LspBridge(
+                            workspace_root=str(workspace_root),
+                            config_file=str(lsp_config_file) if lsp_config_file else None,
+                            timeout=timeout_s,
+                        ) as bridge:
+                            return await expand_graph(bridge)
+
+                    def _run():
+                        return asyncio.run(asyncio.wait_for(_expand_once(), timeout=timeout_s))
+
+                    graph = executor.submit(_run).result(timeout=timeout_s + 1.0)
+            else:
+                from codexlens.lsp.keepalive_bridge import KeepAliveKey, KeepAliveLspBridge
+
+                key = KeepAliveKey(
+                    workspace_root=str(workspace_root),
+                    config_file=str(lsp_config_file) if lsp_config_file else None,
+                    timeout=float(timeout_s),
+                )
+                warm_id = (key.workspace_root, key.config_file)
+                with self._realtime_lsp_keepalive_lock:
+                    if warm_id in self._realtime_lsp_warmed_ids:
+                        effective_warmup_s = 0.0
+                    keepalive = self._realtime_lsp_keepalive
+                    if keepalive is None or self._realtime_lsp_keepalive_key != key:
+                        if keepalive is not None:
+                            try:
+                                keepalive.stop()
+                            except Exception:
+                                pass
+                        keepalive = KeepAliveLspBridge(
+                            workspace_root=key.workspace_root,
+                            config_file=key.config_file,
+                            timeout=key.timeout,
+                        )
+                        self._realtime_lsp_keepalive = keepalive
+                        self._realtime_lsp_keepalive_key = key
+
+                graph = keepalive.run(expand_graph, timeout=timeout_s)
+                with self._realtime_lsp_keepalive_lock:
+                    self._realtime_lsp_warmed_ids.add(warm_id)
         except Exception as exc:
-            self.logger.debug("Stage 2 LSP expansion failed: %s", exc)
+            self.logger.debug("Stage 2 (realtime) expansion failed: %r", exc)
             return coarse_results
 
+        try:
+            node_count = len(getattr(graph, "nodes", {}) or {})
+            edge_count = len(getattr(graph, "edges", []) or [])
+        except Exception:
+            node_count, edge_count = 0, 0
+        self.logger.debug(
+            "Stage 2 (realtime) graph built: seeds=%d nodes=%d edges=%d",
+            len(seed_nodes),
+            node_count,
+            edge_count,
+        )
+
+        related_results: List[SearchResult] = []
+        for node_id, node in getattr(graph, "nodes", {}).items():
+            if node_id in seed_ids or getattr(node, "id", "") in seed_ids:
+                continue
+
+            try:
+                start_line = int(getattr(node.range, "start_line", 1) or 1)
+                end_line = int(getattr(node.range, "end_line", start_line) or start_line)
+            except Exception:
+                start_line, end_line = 1, 1
+
+            related_results.append(
+                SearchResult(
+                    path=node.file_path,
+                    score=0.5,
+                    excerpt=None,
+                    content=getattr(node, "raw_code", "") or None,
+                    symbol_name=node.name,
+                    symbol_kind=node.kind,
+                    start_line=start_line,
+                    end_line=end_line,
+                    metadata={"stage2_mode": "realtime", "lsp_node_id": node_id},
+                )
+            )
+
+        if related_results:
+            self.logger.debug(
+                "Stage 2 (realtime) expanded %d base results to %d related symbols",
+                len(coarse_results), len(related_results)
+            )
+
+        return self._combine_stage2_results(coarse_results, related_results)
+
+    def _combine_stage2_results(
+        self,
+        coarse_results: List[SearchResult],
+        related_results: List[SearchResult],
+    ) -> List[SearchResult]:
+        combined = list(coarse_results)
+        seen_keys = {(r.path, r.symbol_name, r.start_line) for r in coarse_results}
+
+        for related in related_results:
+            key = (related.path, related.symbol_name, related.start_line)
+            if key not in seen_keys:
+                seen_keys.add(key)
+                combined.append(related)
+
+        return combined
+
+    def _find_lsp_workspace_root(self, start_path: Path) -> Path:
+        """Best-effort workspace root selection for LSP initialization.
+
+        Many language servers (e.g. Pyright) use workspace-relative include/exclude
+        patterns, so using a deep subdir (like "src") as root can break reference
+        and call-hierarchy queries.
+        """
+        start = Path(start_path).resolve()
+        if start.is_file():
+            start = start.parent
+
+        # Prefer an explicit LSP config file in the workspace.
+        for current in [start, *list(start.parents)]:
+            try:
+                if (current / "lsp-servers.json").is_file():
+                    return current
+            except OSError:
+                continue
+
+        # Fallback heuristics for project root markers.
+        for current in [start, *list(start.parents)]:
+            try:
+                if (current / ".git").exists() or (current / "pyproject.toml").is_file():
+                    return current
+            except OSError:
+                continue
+
+        return start
+
+    def _find_lsp_config_file(self, start_path: Path) -> Optional[Path]:
+        """Find a lsp-servers.json by walking up from start_path."""
+        start = Path(start_path).resolve()
+        if start.is_file():
+            start = start.parent
+
+        for current in [start, *list(start.parents)]:
+            try:
+                candidate = current / "lsp-servers.json"
+                if candidate.is_file():
+                    return candidate
+            except OSError:
+                continue
+        return None
+
     def _stage3_cluster_prune(
         self,
         expanded_results: List[SearchResult],
@@ -1369,6 +1871,57 @@ class ChainSearchEngine:
         if len(expanded_results) <= target_count:
             return expanded_results
 
+        strategy_name = "auto"
+        if self._config is not None:
+            strategy_name = getattr(self._config, "staged_clustering_strategy", "auto") or "auto"
+        strategy_name = str(strategy_name).strip().lower()
+
+        if strategy_name in {"noop", "none", "off"}:
+            return sorted(expanded_results, key=lambda r: r.score, reverse=True)[:target_count]
+
+        if strategy_name in {"score", "top", "rank"}:
+            return sorted(expanded_results, key=lambda r: r.score, reverse=True)[:target_count]
+
+        if strategy_name in {"path", "file"}:
+            best_by_path: Dict[str, SearchResult] = {}
+            for r in expanded_results:
+                if not r.path:
+                    continue
+                key = str(r.path).lower()
+                if key not in best_by_path or r.score > best_by_path[key].score:
+                    best_by_path[key] = r
+            candidates = list(best_by_path.values()) or expanded_results
+            candidates.sort(key=lambda r: r.score, reverse=True)
+            return candidates[:target_count]
+
+        if strategy_name in {"dir_rr", "rr_dir", "round_robin_dir"}:
+            results_sorted = sorted(expanded_results, key=lambda r: r.score, reverse=True)
+            buckets: Dict[str, List[SearchResult]] = {}
+            dir_order: List[str] = []
+            for r in results_sorted:
+                try:
+                    d = str(Path(r.path).parent).lower()
+                except Exception:
+                    d = ""
+                if d not in buckets:
+                    buckets[d] = []
+                    dir_order.append(d)
+                buckets[d].append(r)
+
+            out: List[SearchResult] = []
+            while len(out) < target_count:
+                progressed = False
+                for d in dir_order:
+                    if not buckets.get(d):
+                        continue
+                    out.append(buckets[d].pop(0))
+                    progressed = True
+                    if len(out) >= target_count:
+                        break
+                if not progressed:
+                    break
+            return out
+
         try:
             from codexlens.search.clustering import (
                 ClusteringConfig,
@@ -1534,7 +2087,7 @@ class ChainSearchEngine:
         2. Stage 2 (Fine): Cross-encoder reranking for precise semantic ranking
            of candidates using query-document attention
 
-        This approach is typically faster than hybrid_cascade_search while
+        This approach is typically faster than binary_cascade_search while
         achieving similar or better quality through cross-encoder reranking.
 
         Performance characteristics:
@@ -1565,9 +2118,9 @@ class ChainSearchEngine:
         """
         if not NUMPY_AVAILABLE:
             self.logger.warning(
-                "NumPy not available, falling back to hybrid cascade search"
+                "NumPy not available, falling back to standard search"
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         options = options or SearchOptions()
         start_time = time.time()
@@ -1611,10 +2164,10 @@ class ChainSearchEngine:
             from codexlens.indexing.embedding import BinaryEmbeddingBackend
         except ImportError as exc:
             self.logger.warning(
-                "BinaryEmbeddingBackend not available: %s, falling back to hybrid cascade",
+                "BinaryEmbeddingBackend not available: %s, falling back to standard search",
                 exc
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         # Step 4: Binary coarse search (same as binary_cascade_search)
         binary_coarse_time = time.time()
@@ -1658,7 +2211,7 @@ class ChainSearchEngine:
                 query_binary = binary_backend.embed_packed([query])[0]
             except Exception as exc:
                 self.logger.warning(f"Failed to generate binary query embedding: {exc}")
-                return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+                return self.search(query, source_path, options=options)
 
             # Fallback to per-directory binary indexes
             for index_path in index_paths:
@@ -1676,9 +2229,9 @@ class ChainSearchEngine:
                     )
 
         if not coarse_candidates:
-            self.logger.info("No binary candidates found, falling back to hybrid cascade for reranking")
-            # Fall back to hybrid_cascade_search which uses FTS+Vector coarse + cross-encoder rerank
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            self.logger.info("No binary candidates found, falling back to standard search for reranking")
+            # Fall back to standard search which uses FTS+Vector
+            return self.search(query, source_path, options=options)
 
         # Sort by Hamming distance and take top coarse_k
         coarse_candidates.sort(key=lambda x: x[1])
@@ -1785,7 +2338,7 @@ class ChainSearchEngine:
             "Retrieved %d chunks for cross-encoder reranking", len(coarse_results)
         )
 
-        # Step 6: Cross-encoder reranking (same as hybrid_cascade_search)
+        # Step 6: Cross-encoder reranking
         rerank_time = time.time()
         reranked_results = self._cross_encoder_rerank(query, coarse_results, top_k=k)
 
@@ -1848,9 +2401,9 @@ class ChainSearchEngine:
         """
         if not NUMPY_AVAILABLE:
             self.logger.warning(
-                "NumPy not available, falling back to hybrid cascade search"
+                "NumPy not available, falling back to standard search"
             )
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         options = options or SearchOptions()
         start_time = time.time()
@@ -1955,7 +2508,7 @@ class ChainSearchEngine:
             self.logger.debug(f"Dense query embedding: {query_dense.shape[0]}-dim via {embedding_backend}/{embedding_model}")
         except Exception as exc:
             self.logger.warning(f"Failed to generate dense query embedding: {exc}")
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            return self.search(query, source_path, options=options)
 
         # Step 5: Dense coarse search using centralized HNSW index
         coarse_candidates: List[Tuple[int, float, Path]] = []  # (chunk_id, distance, index_path)
@@ -2006,8 +2559,8 @@ class ChainSearchEngine:
                     )
 
         if not coarse_candidates:
-            self.logger.info("No dense candidates found, falling back to hybrid cascade")
-            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+            self.logger.info("No dense candidates found, falling back to standard search")
+            return self.search(query, source_path, options=options)
 
         # Sort by distance (ascending for cosine distance) and take top coarse_k
         coarse_candidates.sort(key=lambda x: x[1])
@@ -2214,6 +2767,31 @@ class ChainSearchEngine:
             self.logger.debug("Failed to load centralized binary searcher: %s", exc)
             return None
 
+    def _find_nearest_binary_mmap_root(self, index_root: Path, *, max_levels: int = 10) -> Path:
+        """Walk up index_root parents to find the nearest centralized binary mmap.
+
+        Centralized staged-binary artifacts are stored at a project index root
+        (e.g. `.../project/src/_binary_vectors.mmap`), but staged search often starts
+        from the nearest ancestor `_index.db` path, which can be nested deeper.
+
+        This helper makes Stage 1 robust by locating the nearest ancestor directory
+        that contains the centralized `_binary_vectors.mmap`.
+        """
+        current_dir = Path(index_root).resolve()
+        for _ in range(max(0, int(max_levels)) + 1):
+            try:
+                if (current_dir / BINARY_VECTORS_MMAP_NAME).exists():
+                    return current_dir
+            except Exception:
+                return Path(index_root).resolve()
+
+            parent = current_dir.parent
+            if parent == current_dir:
+                break
+            current_dir = parent
+
+        return Path(index_root).resolve()
+
     def _compute_cosine_similarity(
         self,
         query_vec: "np.ndarray",
@@ -2972,7 +3550,6 @@ class ChainSearchEngine:
                 options.enable_fuzzy,
                 options.enable_vector,
                 options.pure_vector,
-                options.enable_splade,
                 options.hybrid_weights
             ): idx_path
             for idx_path in index_paths
@@ -3001,7 +3578,6 @@ class ChainSearchEngine:
                               enable_fuzzy: bool = True,
                               enable_vector: bool = False,
                               pure_vector: bool = False,
-                              enable_splade: bool = False,
                               hybrid_weights: Optional[Dict[str, float]] = None) -> List[SearchResult]:
         """Search a single index database.
 
@@ -3017,7 +3593,6 @@ class ChainSearchEngine:
             enable_fuzzy: Enable fuzzy FTS in hybrid mode
             enable_vector: Enable vector semantic search
             pure_vector: If True, only use vector search without FTS fallback
-            enable_splade: If True, force SPLADE sparse neural search
             hybrid_weights: Custom RRF weights for hybrid search
 
         Returns:
@@ -3034,7 +3609,6 @@ class ChainSearchEngine:
                     enable_fuzzy=enable_fuzzy,
                     enable_vector=enable_vector,
                     pure_vector=pure_vector,
-                    enable_splade=enable_splade,
                 )
             else:
                 # Single-FTS search (exact or fuzzy mode)