@comfanion/usethis_search 4.4.0 → 4.5.1

package/tools/search.ts

@@ -13,7 +13,7 @@ import { tool } from "@opencode-ai/plugin"
 import path from "path"
 import fs from "fs/promises"
 
-import { CodebaseIndexer, getSearchConfig, getDecomposerConfig, getIndexer, releaseIndexer } from "../vectorizer/index.ts"
+import { CodebaseIndexer, getSearchConfig, getWorkspaceConfig, getDecomposerConfig, getIndexer, releaseIndexer } from "../vectorizer/index.ts"
 import { workspaceCache } from "../cache/manager.ts"
 import { buildWorkspaceOutput } from "./workspace-state.ts"
 import { decomposeQuery } from "../vectorizer/query-decomposer.ts"
@@ -91,7 +91,8 @@ async function expandChunkContext(
       if (alreadyAttached.has(chunkId)) continue
       
       // Skip the main chunk itself
-      if (chunkId === mainChunk.chunkId) continue
+      const mainChunkId = mainChunk.chunk_id || `${mainChunk.file}:chunk-${mainChunk.chunk_index ?? 0}`
+      if (chunkId === mainChunkId) continue
       
       // Add other sections from same document
       expanded.push({
@@ -188,11 +189,14 @@ Available indexes:
 - "config" - Configuration files (*.yaml, *.json, etc.)
 - searchAll: true - Search across all indexes
 
-Auto-detects query type:
+Auto-detects query type (per item in queries array):
 - Semantic: "authentication logic" → vector search for relevant code
 - File path: "docs/architecture.md" → attaches entire file to workspace
 - Chunk ID: "src/auth.ts:chunk-5" → attaches specific chunk
 
+Multi-query: pass multiple queries to search/attach in one call.
+Each query is processed independently — semantic searches are merged, files/chunks are attached.
+
 How workspace works:
 - Top results are AUTO-ATTACHED to workspace with expanded context (class methods, imports, related code via graph)
 - Workspace has a TOKEN BUDGET (~50K tokens, ~100 chunks). When full, oldest chunks are evicted
@@ -207,13 +211,19 @@ IMPORTANT: Chunks contain DIRECT file content dumps (raw code/text from files).
 - Use Read tool only if you need content OUTSIDE the indexed chunks
 
 Context management (CRITICAL — follow these rules):
-- BEFORE searching a new topic, you MUST call workspace_forget() to remove irrelevant old context
-- Workspace has LIMITED token budget. If budget >60%, evict old chunks with workspace_forget({ what: "5" })
-- Use workspace_clear() when switching to a completely different task
-- After editing files, forget stale chunks: workspace_forget({ what: "edited-file.ts" })
+- BEFORE searching a new topic, you MUST call forget() to remove irrelevant old context
+- Workspace has LIMITED token budget. If budget >60%, evict old chunks with forget({ queries: ["5"] })
+- Use clear() when switching to a completely different task
+- After editing files, forget stale chunks: forget({ queries: ["edited-file.ts"] })
 - The workspace is your working memory — KEEP IT FOCUSED. Stale context degrades search quality
 - Rule of thumb: forget BEFORE you search, not after
 
+Graph navigation workflow:
+1. search({ queries: ["authentication"] }) → find relevant chunks
+2. explore({ node: "chunk:src/auth.ts::AuthService" }) → see imports, callers, methods
+3. search({ queries: ["chunk:src/auth.ts::login", "chunk:src/types/User.ts::User"] }) → attach specific chunks
+4. forget() to clean up before next search
+
 Filter narrows results by path or language:
 - "internal/domain/" → only files under that path
 - "*.go" → only Go files
@@ -221,19 +231,22 @@ Filter narrows results by path or language:
 - "service" → files containing "service" in path
 
 Examples:
-- search({ query: "authentication logic" })
-- search({ query: "how to deploy", index: "docs" })
-- search({ query: "tenant management", filter: "internal/domain/" })
-- search({ query: "event handling", filter: "*.go" })
-- search({ query: "API routes", filter: "internal/**/*.go" })
-- search({ query: "metrics", searchAll: true })
-- search({ query: "docs/prd.md" })
-- search({ query: "src/auth.ts:chunk-5" })`,
+- search({ queries: ["authentication logic"] })
+- search({ queries: ["how to deploy"], index: "docs" })
+- search({ queries: ["tenant management"], filter: "internal/domain/" })
+- search({ queries: ["event handling"], filter: "*.go" })
+- search({ queries: ["API routes"], filter: "internal/**/*.go" })
+- search({ queries: ["metrics"], searchAll: true })
+- search({ queries: ["docs/prd.md"] })
+- search({ queries: ["src/auth.ts:chunk-5"] })
+- search({ queries: ["auth logic", "user model", "api routes"] })
+- search({ queries: ["src/auth.ts", "src/types/User.ts"] })
+- search({ queries: ["chunk:src/auth.ts::login", "src/types/User.ts"] })`,
 
   args: {
-    query: tool.schema.string().describe("What to search: semantic query, file path, or chunk ID"),
+    queries: tool.schema.array(tool.schema.string()).describe("Queries: semantic, file paths, or chunk IDs"),
     index: tool.schema.string().optional().default("code").describe("Where to search: 'code', 'docs', or leave empty for auto-detect"),
-    limit: tool.schema.number().optional().describe("Max results (default: 10)"),
+    limit: tool.schema.number().optional().describe("Max results per query (default: 10)"),
     searchAll: tool.schema.boolean().optional().default(false).describe("Search all indexes instead of one"),
     filter: tool.schema.string().optional().describe("Filter by path/language: 'internal/domain/', '*.go', 'service'"),
   },
@@ -242,36 +255,16 @@ Examples:
     const projectRoot = process.cwd()
 
     try {
-      if (!args.query) {
-        return `Error: query is required\n\nExamples:\n- search({ query: "authentication logic" })\n- search({ query: "docs/architecture.md" })\n- search({ query: "src/auth.ts:chunk-5" })`
-      }
+      const queryList: string[] = args.queries && args.queries.length > 0
+        ? args.queries
+        : []
 
-      // Auto-detect mode from query
-      let mode: "chunkId" | "path" | "semantic"
-      let chunkId: string | undefined
-      let filePath: string | undefined
-      let semanticQuery: string | undefined
-
-      // 1. Check if it's a chunk ID (contains ":chunk-")
-      if (args.query.includes(":chunk-")) {
-        mode = "chunkId"
-        chunkId = args.query
-      }
-      // 2. Check if it's a file path (has extension or starts with common paths)
-      else if (
-        args.query.match(/\.(md|ts|js|go|py|tsx|jsx|rs|java|kt|swift|txt|yaml|json|yml|toml)$/i) ||
-        args.query.match(/^(src|docs|internal|pkg|lib|app|pages|components|api)\//i) ||
-        args.query.includes("/")
-      ) {
-        mode = "path"
-        filePath = args.query
-      }
-      // 3. Otherwise, it's a semantic search
-      else {
-        mode = "semantic"
-        semanticQuery = args.query
+      if (queryList.length === 0) {
+        return `Error: queries is required\n\nExamples:\n- search({ queries: ["authentication logic"] })\n- search({ queries: ["auth logic", "user model"] })\n- search({ queries: ["src/auth.ts:chunk-5"] })`
       }
 
+      const isMulti = queryList.length > 1
+
       // Load config defaults (parsed from vectorizer.yaml)
       const cfg = getSearchConfig()
       const limit = args.limit || cfg.default_limit || 10
@@ -279,100 +272,120 @@ Examples:
       const minScore = cfg.min_score ?? 0.35
       const includeArchived = cfg.include_archived ?? false
 
-      // Workspace config
+      // Workspace config — refresh from parsed yaml (loadConfig may have run after plugin init)
+      const latestWsConfig = getWorkspaceConfig()
+      workspaceCache.updateConfig(latestWsConfig)
       const wsConfig = workspaceCache.getConfig()
 
       // ══════════════════════════════════════════════════════════════════════
-      // MODE 1: Direct chunk attach by chunkId
+      // Classify each query: chunkId / path / semantic
       // ══════════════════════════════════════════════════════════════════════
-      if (mode === "chunkId") {
-        const indexer = await getIndexer(projectRoot, indexName)
-        try {
-          const chunk = await indexer.findChunkById(chunkId!)
-          if (!chunk) {
-            return `Chunk "${chunkId}" not found in index "${indexName}".\n\nMake sure:\n1. The file is indexed\n2. The chunk ID is correct (format: "path:chunk-N")\n3. You're searching the right index`
-          }
-
-          // Attach to workspace
-          workspaceCache.attach({
-            chunkId: chunkId!,
-            path: chunk.file,
-            content: chunk.content,
-            chunkIndex: chunk.chunk_index ?? 0,
-            role: "manual",
-            attachedAt: Date.now(),
-            attachedBy: `direct:${chunkId}`,
-            metadata: {
-              language: chunk.language,
-              function_name: chunk.function_name,
-              class_name: chunk.class_name,
-              heading_context: chunk.heading_context,
-              startLine: chunk.start_line,
-              endLine: chunk.end_line,
-            },
-          })
-
-          workspaceCache.save().catch(() => {})
-
-          const entry = workspaceCache.get(chunkId!)!
-          let result = `✓ Attached chunk to workspace\n\nChunk: ${chunkId}\nFile: ${chunk.file}\nTokens: ${entry.tokens.toLocaleString()}\nLanguage: ${chunk.language}\nLines: ${chunk.start_line}-${chunk.end_line}`
-          result += buildWorkspaceOutput()
-          return result
-        } finally {
-          releaseIndexer(projectRoot, indexName)
+      const directAttachItems: Array<{ q: string; type: "chunkId" | "path" }> = []
+      const semanticQueries: string[] = []
+
+      for (const q of queryList) {
+        if (q.includes(":chunk-") || q.startsWith("chunk:")) {
+          directAttachItems.push({ q, type: "chunkId" })
+        } else if (
+          q.match(/\.(md|ts|js|go|py|tsx|jsx|rs|java|kt|swift|txt|yaml|json|yml|toml)$/i) ||
+          q.match(/^(src|docs|internal|pkg|lib|app|pages|components|api)\//i)
+        ) {
+          directAttachItems.push({ q, type: "path" })
+        } else {
+          semanticQueries.push(q)
         }
       }
 
       // ══════════════════════════════════════════════════════════════════════
-      // MODE 2: File attach by path (all chunks)
+      // Direct attach: chunkIds and file paths
       // ══════════════════════════════════════════════════════════════════════
-      if (mode === "path") {
+      const directResults: string[] = []
+      const directErrors: string[] = []
+
+      if (directAttachItems.length > 0) {
         const indexer = await getIndexer(projectRoot, indexName)
         try {
-          const chunks = await indexer.findChunksByPath(filePath!)
-          if (chunks.length === 0) {
-            return `No chunks found for file "${filePath}" in index "${indexName}".\n\nMake sure:\n1. The file exists and is indexed\n2. The path is correct (relative to project root)\n3. You're searching the right index\n\nRun: bunx usethis_search reindex`
-          }
-
-          // Attach all chunks to workspace
-          let totalTokens = 0
-          for (const chunk of chunks) {
-            const chunkIdForChunk = chunk.chunk_id || `${filePath}:chunk-${chunk.chunk_index ?? 0}`
-            
-            workspaceCache.attach({
-              chunkId: chunkIdForChunk,
-              path: filePath!,
-              content: chunk.content,
-              chunkIndex: chunk.chunk_index ?? 0,
-              role: "manual",
-              attachedAt: Date.now(),
-              attachedBy: `file:${filePath}`,
-              metadata: {
-                language: chunk.language,
-                function_name: chunk.function_name,
-                class_name: chunk.class_name,
-                heading_context: chunk.heading_context,
-                startLine: chunk.start_line,
-                endLine: chunk.end_line,
-              },
-            })
-
-            const entry = workspaceCache.get(chunkIdForChunk)!
-            totalTokens += entry.tokens
+          for (const { q, type } of directAttachItems) {
+            if (type === "chunkId") {
+              const chunk = await indexer.findChunkById(q)
+              if (!chunk) {
+                directErrors.push(`Chunk "${q}" not found`)
+                continue
+              }
+              workspaceCache.attach({
+                chunkId: q,
+                path: chunk.file,
+                content: chunk.content,
+                chunkIndex: chunk.chunk_index ?? 0,
+                role: "manual",
+                attachedAt: Date.now(),
+                attachedBy: `direct:${q}`,
+                metadata: {
+                  language: chunk.language,
+                  function_name: chunk.function_name,
+                  class_name: chunk.class_name,
+                  heading_context: chunk.heading_context,
+                  startLine: chunk.start_line,
+                  endLine: chunk.end_line,
+                },
+              })
+              const entry = workspaceCache.get(q)!
+              directResults.push(`✓ ${q} (${chunk.file}, ${entry.tokens} tokens)`)
+            } else {
+              const chunks = await indexer.findChunksByPath(q)
+              if (chunks.length === 0) {
+                directErrors.push(`"${q}" — no chunks found`)
+                continue
+              }
+              let fileTokens = 0
+              for (const chunk of chunks) {
+                const cid = chunk.chunk_id || `${q}:chunk-${chunk.chunk_index ?? 0}`
+                workspaceCache.attach({
+                  chunkId: cid,
+                  path: q,
+                  content: chunk.content,
+                  chunkIndex: chunk.chunk_index ?? 0,
+                  role: "manual",
+                  attachedAt: Date.now(),
+                  attachedBy: `file:${q}`,
+                  metadata: {
+                    language: chunk.language,
+                    function_name: chunk.function_name,
+                    class_name: chunk.class_name,
+                    heading_context: chunk.heading_context,
+                    startLine: chunk.start_line,
+                    endLine: chunk.end_line,
+                  },
+                })
+                const entry = workspaceCache.get(cid)
+                fileTokens += entry?.tokens ?? 0
+              }
+              directResults.push(`✓ ${q} (${chunks.length} chunks, ${fileTokens} tokens)`)
+            }
           }
-
-          workspaceCache.save().catch(() => {})
-
-          let result = `✓ Attached file to workspace\n\nFile: ${filePath}\nChunks: ${chunks.length}\nTokens: ${totalTokens.toLocaleString()}\nLanguage: ${chunks[0].language}`
-          result += buildWorkspaceOutput()
-          return result
         } finally {
           releaseIndexer(projectRoot, indexName)
         }
+        workspaceCache.save().catch(() => {})
+      }
+
+      // If all queries were direct attaches (no semantic), return early
+      if (semanticQueries.length === 0) {
+        let output = `## Attached\n\n`
+        for (const r of directResults) output += `- ${r}\n`
+        if (directErrors.length > 0) {
+          output += `\n**Errors:**\n`
+          for (const e of directErrors) output += `- ${e}\n`
+        }
+        output += buildWorkspaceOutput()
+        return output
       }
 
+      // Use first semantic query as the primary (for output header, reranking, etc.)
+      const semanticQuery = semanticQueries[0]
+
       // ══════════════════════════════════════════════════════════════════════
-      // MODE 3: Semantic search by query (original behavior)
+      // Semantic search (single or multi-query merge)
       // ══════════════════════════════════════════════════════════════════════
 
       // Parse filter into path/language constraints
@@ -386,8 +399,11 @@ Examples:
       if (cfg.freshen) {
         try {
           const indexer = await getIndexer(projectRoot, indexName)
-          await indexer.freshen()
-          releaseIndexer(projectRoot, indexName)
+          try {
+            await indexer.freshen()
+          } finally {
+            releaseIndexer(projectRoot, indexName)
+          }
         } catch {
           // non-fatal — search can proceed without freshen
         }
@@ -395,70 +411,82 @@ Examples:
 
       let allResults: any[] = []
 
+      // Determine which indexes to search
+      let targetIndexes: string[]
+
       if (args.searchAll) {
         const tempIndexer = await getIndexer(projectRoot, "code")
-        const indexes = await tempIndexer.listIndexes()
-        releaseIndexer(projectRoot, "code")
-
-        if (indexes.length === 0) {
-          return `No indexes found. The codebase needs to be indexed first.\n\nRun the CLI: bunx usethis_search reindex`
-        }
-
-        for (const idx of indexes) {
-          const indexer = await getIndexer(projectRoot, idx)
-          try {
-            const results = await indexer.search(semanticQuery!, limit, includeArchived, searchOptions)
-            allResults.push(...results.map((r: any) => ({ ...r, _index: idx })))
-          } finally {
-            releaseIndexer(projectRoot, idx)
-          }
+        try {
+          targetIndexes = await tempIndexer.listIndexes()
+        } finally {
+          releaseIndexer(projectRoot, "code")
         }
 
-        // Deduplicate chunks (searchAll may return same chunk from multiple indexes)
-        const seen = new Set<string>()
-        const deduplicated: any[] = []
-        
-        for (const result of allResults) {
-          const chunkId = result.chunkId || `${result.file}:chunk-${result.index ?? 0}`
-          if (!seen.has(chunkId)) {
-            seen.add(chunkId)
-            deduplicated.push(result)
-          }
+        if (targetIndexes.length === 0) {
+          return `No indexes found. The codebase needs to be indexed first.\n\nRun the CLI: bunx usethis_search reindex`
         }
-        
-        allResults = deduplicated
-        allResults.sort((a, b) => {
-          const scoreA = a._combinedScore ?? (a._distance != null ? Math.max(0, 1 - a._distance / 2) : 0)
-          const scoreB = b._combinedScore ?? (b._distance != null ? Math.max(0, 1 - b._distance / 2) : 0)
-          return scoreB - scoreA
-        })
-        allResults = allResults.slice(0, limit)
       } else {
+        // Verify index exists
         const hashesFile = path.join(projectRoot, ".opencode", "vectors", indexName, "hashes.json")
         try {
           await fs.access(hashesFile)
         } catch {
-          // Index doesn't exist — check what indexes ARE available
           const tempIndexer = await getIndexer(projectRoot, "code")
-          const available = await tempIndexer.listIndexes()
-          releaseIndexer(projectRoot, "code")
+          let available: string[]
+          try {
+            available = await tempIndexer.listIndexes()
+          } finally {
+            releaseIndexer(projectRoot, "code")
+          }
 
           if (available.length > 0) {
-            const list = available.map(i => `"${i}"`).join(", ")
-            return `Index "${indexName}" not found. Available indexes: ${list}.\n\nTry: search({ query: "${semanticQuery}", index: "${available[0]}" })\nOr search all: search({ query: "${semanticQuery}", searchAll: true })`
+            const availList = available.map(i => `"${i}"`).join(", ")
+            return `Index "${indexName}" not found. Available indexes: ${availList}.\n\nTry: search({ query: "${semanticQuery}", index: "${available[0]}" })\nOr search all: search({ query: "${semanticQuery}", searchAll: true })`
           }
           return `No indexes found. The codebase needs to be indexed first.\n\nRun the CLI: bunx usethis_search reindex`
         }
+        targetIndexes = [indexName]
+      }
 
-        const indexer = await getIndexer(projectRoot, indexName)
-        try {
-          const results = await indexer.search(semanticQuery!, limit, includeArchived, searchOptions)
-          allResults = results.map((r: any) => ({ ...r, _index: indexName }))
-        } finally {
-          releaseIndexer(projectRoot, indexName)
+      // Run each semantic query against each target index, collect results
+      for (const sq of semanticQueries) {
+        for (const idx of targetIndexes) {
+          const indexer = await getIndexer(projectRoot, idx)
+          try {
+            const results = await indexer.search(sq, limit, includeArchived, searchOptions)
+            allResults.push(...results.map((r: any) => ({ ...r, _index: idx, _query: sq })))
+          } finally {
+            releaseIndexer(projectRoot, idx)
+          }
+        }
+      }
+
+      // Deduplicate by chunk_id — keep highest score
+      {
+        const bestByChunk = new Map<string, any>()
+        for (const result of allResults) {
+          const chunkId = result.chunk_id || `${result.file}:chunk-${result.chunk_index ?? 0}`
+          const score = result._combinedScore ?? (result._distance != null ? Math.max(0, 1 - result._distance / 2) : 0)
+          const existing = bestByChunk.get(chunkId)
+          if (!existing) {
+            bestByChunk.set(chunkId, result)
+          } else {
+            const existingScore = existing._combinedScore ?? (existing._distance != null ? Math.max(0, 1 - existing._distance / 2) : 0)
+            if (score > existingScore) {
+              bestByChunk.set(chunkId, result)
+            }
+          }
         }
+        allResults = [...bestByChunk.values()]
       }
 
+      allResults.sort((a, b) => {
+        const scoreA = a._combinedScore ?? (a._distance != null ? Math.max(0, 1 - a._distance / 2) : 0)
+        const scoreB = b._combinedScore ?? (b._distance != null ? Math.max(0, 1 - b._distance / 2) : 0)
+        return scoreB - scoreA
+      })
+      allResults = allResults.slice(0, limit)
+
       // ── Score cutoff — drop low-relevance results ──────────────────────────
       allResults = allResults.filter(r => {
         const score = r._combinedScore ?? (r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0)
@@ -516,8 +544,8 @@ Examples:
         filterApplied = true
       }
 
-      // ── Reranking — boost results where query keywords appear in text ──────
-      const queryKeywords = semanticQuery!.toLowerCase().split(/\s+/).filter((w: string) => w.length > 2)
+      // ── Reranking — keyword match + metadata signals ──────────────────────
+      const queryKeywords = [...new Set(semanticQueries.flatMap(q => q.toLowerCase().split(/\s+/).filter((w: string) => w.length > 2)))]
       for (const r of allResults) {
         const isBM25Only = !!r._bm25Only
         const vectorScore = r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0
@@ -527,6 +555,7 @@ Examples:
           : (r._combinedScore != null ? Math.max(0, r._combinedScore - vectorScore) : 0)
         const baseScore = r._combinedScore ?? vectorScore
 
+        // ── Keyword bonus (content match) ──
         const text = (r.content || "").toLowerCase()
         const matchedKeywords: string[] = []
         if (queryKeywords.length > 0) {
@@ -537,17 +566,61 @@ Examples:
         r._matchedKeywords = matchedKeywords
         const keywordBonus = queryKeywords.length > 0 ? (matchedKeywords.length / queryKeywords.length) * 0.15 : 0
         r._keywordBonus = keywordBonus
-        r._finalScore = baseScore + keywordBonus
+
+        // ── Metadata reranking ──
+        let metadataBonus = 0
+        const filePath = (r.file || "") as string
+
+        // File type: boost source, penalize tests
+        const isTest = /[/.](?:test|spec|__test__|_test)\b/i.test(filePath)
+        const isHelper = /[/.](?:mock|fixture|helper|stub|fake)/i.test(filePath)
+        if (isTest) {
+          metadataBonus -= 0.05
+        } else if (isHelper) {
+          metadataBonus -= 0.03
+        } else {
+          // Source file — small boost
+          metadataBonus += 0.03
+        }
+
+        // Function name match — strong signal
+        if (r.function_name && queryKeywords.length > 0) {
+          const fnLower = (r.function_name as string).toLowerCase()
+          for (const kw of queryKeywords) {
+            if (fnLower.includes(kw)) {
+              metadataBonus += 0.12
+              break
+            }
+          }
+        }
+
+        // Class name match
+        if (r.class_name && queryKeywords.length > 0) {
+          const clsLower = (r.class_name as string).toLowerCase()
+          for (const kw of queryKeywords) {
+            if (clsLower.includes(kw)) {
+              metadataBonus += 0.08
+              break
+            }
+          }
+        }
+
+        r._metadataBonus = metadataBonus
+        r._finalScore = baseScore + keywordBonus + metadataBonus
       }
       allResults.sort((a: any, b: any) => (b._finalScore ?? 0) - (a._finalScore ?? 0))
 
        // ── Sort by final score (chunks, not files) ──────────────────────────
        const topChunks = allResults.slice(0, limit)
 
+       const queryLabel = semanticQueries.length === 1
+         ? `"${semanticQuery}"`
+         : semanticQueries.map(q => `"${q}"`).join(", ")
+
        if (topChunks.length === 0) {
          const scope = args.searchAll ? "any index" : `index "${indexName}"`
          const filterNote = args.filter ? ` with filter "${args.filter}"` : ""
-         let noResultsOutput = `No results found in ${scope}${filterNote} for: "${semanticQuery}" (min score: ${minScore})\n\nTry:\n- Different keywords or phrasing\n- Remove or broaden the filter\n- search({ query: "...", searchAll: true })`
+         let noResultsOutput = `No results found in ${scope}${filterNote} for: ${queryLabel} (min score: ${minScore})\n\nTry:\n- Different keywords or phrasing\n- Remove or broaden the filter\n- search({ query: "...", searchAll: true })`
          noResultsOutput += buildWorkspaceOutput()
          return noResultsOutput
        }
@@ -566,30 +639,31 @@ Examples:
 
        // Get indexer for context expansion (reuse same indexer)
        const indexerForExpansion = await getIndexer(projectRoot, indexName)
+       try {
 
        for (const chunk of mainChunks) {
          // Skip if score too low
          if ((chunk._finalScore ?? 0) < wsConfig.minScoreMain) continue
 
          // Attach main chunk
-         const chunkId = chunk.chunkId || `${chunk.file}:chunk-${chunk.index ?? 0}`
+         const chunkId = chunk.chunk_id || `${chunk.file}:chunk-${chunk.chunk_index ?? 0}`
          
           workspaceCache.attach({
             chunkId,
             path: chunk.file,
             content: chunk.content,
-            chunkIndex: chunk.index ?? 0,
+            chunkIndex: chunk.chunk_index ?? 0,
             role: "search-main",
             attachedAt: Date.now(),
-            attachedBy: semanticQuery!,
-            score: chunk._finalScore,
+            attachedBy: chunk._query || semanticQuery!,
+             score: chunk._finalScore,
            metadata: {
              language: chunk.language,
              function_name: chunk.function_name,
              class_name: chunk.class_name,
              heading_context: chunk.heading_context,
-             startLine: chunk.startLine,
-             endLine: chunk.endLine,
+             startLine: chunk.start_line,
+             endLine: chunk.end_line,
            },
          })
 
@@ -613,7 +687,7 @@ Examples:
                 chunkIndex: expChunk.chunk_index ?? 0,
                 role: "search-context",
                 attachedAt: Date.now(),
-                attachedBy: `${semanticQuery} (${reason})`,
+                attachedBy: `${chunk._query || semanticQuery} (${reason})`,
                score: chunk._finalScore * 0.9, // Slightly lower score than main
                metadata: {
                  language: expChunk.language,
@@ -642,24 +716,24 @@ Examples:
              .slice(0, wsConfig.attachRelatedPerChunk)
 
            for (const rel of topRelated) {
-             const relChunkId = rel.chunkId || `${rel.file}:chunk-${rel.index ?? 0}`
+             const relChunkId = rel.chunk_id || `${rel.file}:chunk-${rel.chunk_index ?? 0}`
              if (alreadyAttached.has(relChunkId)) continue
 
               workspaceCache.attach({
                 chunkId: relChunkId,
                 path: rel.file,
                 content: rel.content,
-                chunkIndex: rel.index ?? 0,
+                chunkIndex: rel.chunk_index ?? 0,
                 role: "search-graph",
                 attachedAt: Date.now(),
-                attachedBy: `${semanticQuery} (${rel.relation} from ${chunkId})`,
+                attachedBy: `${chunk._query || semanticQuery} (${rel.relation} from ${chunkId})`,
                score: rel.score,
                metadata: {
                  language: rel.language,
                  relation: rel.relation,
                  mainChunkId: chunkId,
-                 startLine: rel.startLine,
-                 endLine: rel.endLine,
+                 startLine: rel.start_line,
+                 endLine: rel.end_line,
                },
              })
 
@@ -669,8 +743,10 @@ Examples:
          }
        }
 
-      // Release indexer used for expansion
-      releaseIndexer(projectRoot, indexName)
+       } finally {
+         // Release indexer used for expansion
+         releaseIndexer(projectRoot, indexName)
+       }
 
       // ── Flush workspace to disk immediately (don't rely on debounce) ─────
       if (attachedMain.length > 0 || attachedGraph.length > 0 || attachedContext.length > 0) {
@@ -686,12 +762,14 @@ Examples:
       const hasRRF = allResults.some((r: any) => r._rrfScore != null)
       const scope = args.searchAll ? "all indexes" : `index "${indexName}"`
       const filterLabel = args.filter ? ` filter:"${args.filter}"` : ""
-      let output = `## Search: "${semanticQuery}" (${scope}${filterLabel})\n\n`
+      let output = `## Search: ${queryLabel} (${scope}${filterLabel})\n\n`
 
-      // Show decomposition info if query was decomposed
-      const decomposition = decomposeQuery(semanticQuery!, getDecomposerConfig())
-      if (decomposition.decomposed) {
-        output += `> **Query decomposed** (${decomposition.strategy}): ${decomposition.subQueries.map(q => `"${q}"`).join(", ")}\n\n`
+      // Show decomposition info if single query was decomposed
+      if (semanticQueries.length === 1) {
+        const decomposition = decomposeQuery(semanticQuery!, getDecomposerConfig())
+        if (decomposition.decomposed) {
+          output += `> **Query decomposed** (${decomposition.strategy}): ${decomposition.subQueries.map(q => `"${q}"`).join(", ")}\n\n`
+        }
       }
 
       if (hasBM25Only) {
@@ -744,7 +822,7 @@ Examples:
          output += `### Additional results (summary only)\n\n`
          for (let i = 0; i < restChunks.length; i++) {
            const chunk = restChunks[i]
-           const chunkId = chunk.chunkId || `${chunk.file}:chunk-${chunk.index ?? 0}`
+            const chunkId = chunk.chunk_id || `${chunk.file}:chunk-${chunk.chunk_index ?? 0}`
            const score = (chunk._finalScore ?? 0).toFixed(3)
            const indexLabel = args.searchAll ? ` [${chunk._index}]` : ""