scai 0.1.178 → 1.0.0

package/dist/__tests__/search/SearchOrchestrator.test.js

@@ -0,0 +1,836 @@
+/**
+ * Verifies the shared search orchestrator keeps discovery modes separate and stable.
+ *
+ * Why this exists:
+ * - exact target, fragment, semantic, and operator search now route through one packet
+ * - fake explicit refs and ambiguous targets were known regressions
+ * - snippet and pattern modes must preserve raw matches without inventing execution state
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+const mocks = vi.hoisted(() => ({
+    resolveSymbolRows: vi.fn(),
+    resolveSymbolRowsByPattern: vi.fn(),
+    semanticSearchFiles: vi.fn(),
+    plannerSearchFiles: vi.fn(),
+    buildMethodSelectionRetrievalQuery: vi.fn(() => null),
+    isMethodSelectionRetrievalQuery: vi.fn(() => false),
+    scoreCandidateFiles: vi.fn((filePaths) => filePaths.map((filePath, index) => ({
+        filePath,
+        score: 10 - index,
+        reasons: [],
+    }))),
+}));
+vi.mock("../../db/client.js", () => ({
+    getDbForRepo: vi.fn(() => ({})),
+}));
+vi.mock("../../db/fileIndex.js", () => ({
+    resolveSymbolRows: mocks.resolveSymbolRows,
+    resolveSymbolRowsByPattern: mocks.resolveSymbolRowsByPattern,
+    resolveTargetRows: vi.fn(),
+    semanticSearchFiles: mocks.semanticSearchFiles,
+    plannerSearchFiles: mocks.plannerSearchFiles,
+}));
+vi.mock("../../search/sharedRankingPolicy.js", () => ({
+    buildMethodSelectionRetrievalQuery: mocks.buildMethodSelectionRetrievalQuery,
+    isMethodSelectionRetrievalQuery: mocks.isMethodSelectionRetrievalQuery,
+    scoreCandidateFiles: mocks.scoreCandidateFiles,
+}));
+vi.mock("child_process", () => ({
+    execFileSync: vi.fn(() => {
+        const error = new Error("rg missing");
+        error.code = "ENOENT";
+        throw error;
+    }),
+}));
+import { SearchOrchestrator } from "../../search/SearchOrchestrator.js";
+describe("SearchOrchestrator", () => {
+    const tempDirs = [];
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mocks.resolveSymbolRows.mockReturnValue([]);
+        mocks.resolveSymbolRowsByPattern.mockReturnValue([]);
+        mocks.semanticSearchFiles.mockResolvedValue([]);
+        mocks.plannerSearchFiles.mockResolvedValue([]);
+        mocks.buildMethodSelectionRetrievalQuery.mockReturnValue(null);
+        mocks.isMethodSelectionRetrievalQuery.mockReturnValue(false);
+        mocks.scoreCandidateFiles.mockImplementation((filePaths) => filePaths.map((filePath, index) => ({
+            filePath,
+            score: 10 - index,
+            reasons: [],
+        })));
+    });
+    afterEach(() => {
+        while (tempDirs.length > 0) {
+            const dir = tempDirs.pop();
+            if (dir)
+                fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("resolves exact files, folders, symbols, and rejects fake explicit refs", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const targetFile = path.join(repoRoot, "cli", "src", "commands", "EvalReportCmd.ts");
+        const folderPath = path.join(repoRoot, "cli", "src", "agents");
+        fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+        fs.mkdirSync(folderPath, { recursive: true });
+        fs.writeFileSync(targetFile, "export const report = true;\n", "utf8");
+        mocks.resolveSymbolRows.mockReturnValue([
+            {
+                id: 7,
+                path: targetFile,
+                filename: "EvalReportCmd.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace EvalReportCmd in cli/src/agents and run runSearch, not task.id",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace EvalReportCmd in cli/src/agents and run runSearch, not task.id",
+                        confidence: 0.9,
+                        targetFiles: ["EvalReportCmd", "cli/src/agents", "task.id"],
+                        targetSymbols: ["runSearch"],
+                    },
+                },
+            },
+            query: "Trace EvalReportCmd in cli/src/agents and run runSearch, not task.id",
+            mode: "exact-target",
+        });
+        expect(result.mode).toBe("exact-target");
+        expect(result.resolvedFiles.map(item => item.path)).toContain(targetFile);
+        expect(result.resolvedFolders).toContain(folderPath);
+        expect(result.resolvedSymbols).toEqual([{ symbol: "runSearch", filePath: targetFile }]);
+        expect(result.unresolvedRefs).toContain("task.id");
+        expect(result.ambiguousRefs).toEqual([]);
+    });
+    it("falls back to pattern symbol resolution when exact symbol lookup misses", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const targetFile = path.join(repoRoot, "cli", "src", "agents", "MainAgent.ts");
+        fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+        fs.writeFileSync(targetFile, "export function runSearchNow() {}\n", "utf8");
+        mocks.resolveSymbolRows.mockReturnValue([]);
+        mocks.resolveSymbolRowsByPattern.mockReturnValue([
+            {
+                id: 9,
+                path: targetFile,
+                filename: "MainAgent.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace run search now",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace run search now",
+                        confidence: 0.9,
+                        targetFiles: [],
+                        targetSymbols: ["run search now"],
+                    },
+                },
+            },
+            query: "Trace run search now",
+            mode: "exact-target",
+        });
+        expect(result.resolvedSymbols).toEqual([{ symbol: "run search now", filePath: targetFile }]);
+        expect(result.unresolvedRefs).toEqual([]);
+    });
+    it("marks pattern symbol fallback with multiple hits as ambiguous", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFile = path.join(repoRoot, "cli", "src", "agents", "MainAgent.ts");
+        const secondFile = path.join(repoRoot, "cli", "src", "search", "SearchOrchestrator.ts");
+        fs.mkdirSync(path.dirname(firstFile), { recursive: true });
+        fs.mkdirSync(path.dirname(secondFile), { recursive: true });
+        fs.writeFileSync(firstFile, "export function runSearchNow() {}\n", "utf8");
+        fs.writeFileSync(secondFile, "export function runSearchNow() {}\n", "utf8");
+        mocks.resolveSymbolRows.mockReturnValue([]);
+        mocks.resolveSymbolRowsByPattern.mockReturnValue([
+            {
+                id: 9,
+                path: firstFile,
+                filename: "MainAgent.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+            {
+                id: 10,
+                path: secondFile,
+                filename: "SearchOrchestrator.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace run search now",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace run search now",
+                        confidence: 0.9,
+                        targetFiles: [],
+                        targetSymbols: ["run search now"],
+                    },
+                },
+            },
+            query: "Trace run search now",
+            mode: "exact-target",
+        });
+        expect(result.resolvedSymbols).toEqual([]);
+        expect(result.ambiguousRefs).toContain("run search now");
+    });
+    it("marks ambiguous exact file refs instead of silently broadening", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFile = path.join(repoRoot, "cli", "src", "agents", "MainAgent.ts");
+        const secondFile = path.join(repoRoot, "dashboard", "src", "MainAgent.ts");
+        fs.mkdirSync(path.dirname(firstFile), { recursive: true });
+        fs.mkdirSync(path.dirname(secondFile), { recursive: true });
+        fs.writeFileSync(firstFile, "export const first = true;\n", "utf8");
+        fs.writeFileSync(secondFile, "export const second = true;\n", "utf8");
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace MainAgent.ts",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace MainAgent.ts",
+                        confidence: 0.9,
+                        targetFiles: ["MainAgent.ts"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "Trace MainAgent.ts",
+            mode: "exact-target",
+        });
+        expect(result.resolvedFiles).toHaveLength(0);
+        expect(result.ambiguousRefs).toContain("MainAgent.ts");
+    });
+    it("resolves basename-only and natural-language folder refs into folder-scoped child candidates", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const guardsDir = path.join(repoRoot, "cli", "src", "agents", "guards");
+        const guardFiles = [
+            path.join(guardsDir, "executionPolicyResolver.ts"),
+            path.join(guardsDir, "guardState.ts"),
+            path.join(guardsDir, "resolveProgressState.ts"),
+        ];
+        fs.mkdirSync(guardsDir, { recursive: true });
+        for (const filePath of guardFiles) {
+            fs.writeFileSync(filePath, "export const guard = true;\n", "utf8");
+        }
+        const context = {
+            initContext: {
+                userQuery: "please tell me what the three files in the guards folder do?",
+                executionPath: repoRoot,
+                repoRootPath: repoRoot,
+            },
+            analysis: {
+                intent: {
+                    intent: "explain",
+                    intentCategory: "explanation",
+                    normalizedQuery: "please tell me what the three files in the guards folder do?",
+                    confidence: 0.9,
+                    targetFiles: ["guards"],
+                    targetSymbols: [],
+                },
+            },
+        };
+        const result = await new SearchOrchestrator().run({
+            context,
+            query: "please tell me what the three files in the guards folder do?",
+            mode: "exact-target",
+        });
+        expect(result.resolvedFolders).toEqual([guardsDir]);
+        expect(result.fileCandidates.map(item => item.path).sort()).toEqual(guardFiles.sort());
+        expect(result.unresolvedRefs).toEqual([]);
+    });
+    it("marks ambiguous basename-only folder refs instead of picking one silently", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFolder = path.join(repoRoot, "cli", "src", "agents", "guards");
+        const secondFolder = path.join(repoRoot, "dashboard", "guards");
+        fs.mkdirSync(firstFolder, { recursive: true });
+        fs.mkdirSync(secondFolder, { recursive: true });
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "check guards",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "check",
+                        intentCategory: "explanation",
+                        normalizedQuery: "check guards",
+                        confidence: 0.9,
+                        targetFiles: ["guards"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "check guards",
+            mode: "exact-target",
+        });
+        expect(result.resolvedFolders).toEqual([]);
+        expect(result.ambiguousRefs).toContain("guards");
+    });
+    it("marks missing folder refs as unresolved", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "check missing-folder",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "check",
+                        intentCategory: "explanation",
+                        normalizedQuery: "check missing-folder",
+                        confidence: 0.9,
+                        targetFiles: ["missing-folder"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "check missing-folder",
+            mode: "exact-target",
+        });
+        expect(result.resolvedFolders).toEqual([]);
+        expect(result.unresolvedRefs).toContain("missing-folder");
+    });
+    it("falls back to semantic retrieval when exact-target resolves nothing at all", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 31,
+                path: path.join(repoRoot, "cli", "src", "commands", "TasksCmd.ts"),
+                filename: "TasksCmd.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "How does /resume work?",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "explain",
+                        intentCategory: "explanation",
+                        normalizedQuery: "How does /resume work?",
+                        confidence: 0.9,
+                        targetFiles: ["/resume"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "How does /resume work?",
+            mode: "exact-target",
+        });
+        expect(result.mode).toBe("exact-target");
+        expect(result.stagesRun).toContain("explicit-target-resolver");
+        expect(result.stagesRun).toContain("fallback-semantic-retriever");
+        expect(result.fallbackUsed).toBe(true);
+        expect(result.unresolvedRefs).toContain("/resume");
+        expect(result.fileCandidates.map(item => item.path)).toEqual([path.join(repoRoot, "cli", "src", "commands", "TasksCmd.ts")]);
+    });
+    it("does not fall back when exact-target is ambiguous", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFile = path.join(repoRoot, "cli", "src", "agents", "MainAgent.ts");
+        const secondFile = path.join(repoRoot, "dashboard", "src", "MainAgent.ts");
+        fs.mkdirSync(path.dirname(firstFile), { recursive: true });
+        fs.mkdirSync(path.dirname(secondFile), { recursive: true });
+        fs.writeFileSync(firstFile, "export const first = true;\n", "utf8");
+        fs.writeFileSync(secondFile, "export const second = true;\n", "utf8");
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 32,
+                path: path.join(repoRoot, "cli", "src", "commands", "TasksCmd.ts"),
+                filename: "TasksCmd.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace MainAgent.ts",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace MainAgent.ts",
+                        confidence: 0.9,
+                        targetFiles: ["MainAgent.ts"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "Trace MainAgent.ts",
+            mode: "exact-target",
+        });
+        expect(result.ambiguousRefs).toContain("MainAgent.ts");
+        expect(result.fallbackUsed).toBe(false);
+        expect(result.stagesRun).not.toContain("fallback-semantic-retriever");
+        expect(mocks.semanticSearchFiles).not.toHaveBeenCalled();
+    });
+    it("preserves identical sentence fragments across multiple files", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFile = path.join(repoRoot, "src", "a.ts");
+        const secondFile = path.join(repoRoot, "src", "b.ts");
+        fs.mkdirSync(path.dirname(firstFile), { recursive: true });
+        fs.writeFileSync(firstFile, "const value = \"alpha beta gamma\";\n", "utf8");
+        fs.writeFileSync(secondFile, "const value = \"alpha beta gamma\";\n", "utf8");
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "\"alpha beta gamma\"",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: { intent: { intent: "", intentCategory: "explanation", normalizedQuery: "\"alpha beta gamma\"", confidence: 0.8 } },
+            },
+            query: "\"alpha beta gamma\"",
+            mode: "sentence-fragment",
+        });
+        expect(result.fragmentMatches).toHaveLength(2);
+        expect(result.fileCandidates.map(item => item.path).sort()).toEqual([firstFile, secondFile].sort());
+    });
+    it("prefers sentence-fragment mode for pure quoted snippets even when intent extracted symbols", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const firstFile = path.join(repoRoot, "src", "analysisPlanGenStep.ts");
+        const secondFile = path.join(repoRoot, "src", "transformPlanGenStep.ts");
+        const snippet = "const currentQuestionId = currentStep.questionId ?? (orderedQuestions.length === 1 ? orderedQuestions[0].id : undefined);";
+        fs.mkdirSync(path.dirname(firstFile), { recursive: true });
+        fs.writeFileSync(firstFile, `${snippet}\n`, "utf8");
+        fs.writeFileSync(secondFile, `${snippet}\n`, "utf8");
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: `\"${snippet}\"`,
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "Locate the quoted code snippet",
+                        intentCategory: "codingTask",
+                        normalizedQuery: snippet,
+                        confidence: 0.95,
+                        targetFiles: [],
+                        targetSymbols: ["currentQuestionId", "currentStep", "questionId", "orderedQuestions", "id"],
+                    },
+                },
+            },
+            query: `\"${snippet}\"`,
+            mode: "auto",
+        });
+        expect(result.mode).toBe("sentence-fragment");
+        expect(result.fragmentMatches).toHaveLength(2);
+        expect(result.fileCandidates.map(item => item.path).sort()).toEqual([firstFile, secondFile].sort());
+    });
+    it("returns raw operator-pattern matches without semantic guessing", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const filePath = path.join(repoRoot, "src", "search.ts");
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, [
+            "function runSearch() {}",
+            "function semanticSearchFiles() {}",
+            "function plannerSearchFiles() {}",
+        ].join("\n"), "utf8");
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "runSearch|semanticSearchFiles|plannerSearchFiles",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: { intent: { intent: "", intentCategory: "explanation", normalizedQuery: "", confidence: 0.8 } },
+            },
+            query: "runSearch|semanticSearchFiles|plannerSearchFiles",
+            mode: "operator-pattern",
+        });
+        expect(result.patternMatches.length).toBeGreaterThan(0);
+        expect(result.fileCandidates.map(item => item.path)).toContain(filePath);
+    });
+    it("routes natural-language generate() questions to semantic retrieval", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const targetFile = path.join(repoRoot, "cli", "src", "lib", "generate.ts");
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 41,
+                path: targetFile,
+                filename: "generate.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace how generate() timing reaches structured logs",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: { intent: { intent: "trace", intentCategory: "explanation", normalizedQuery: "", confidence: 0.8 } },
+            },
+            query: "Trace how generate() timing reaches structured logs",
+            mode: "auto",
+        });
+        expect(result.mode).toBe("semantic-retrieval");
+        expect(result.fileCandidates.map(item => item.path)).toEqual([targetFile]);
+    });
+    it("falls back to semantic retrieval when operator-pattern search is empty", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const targetFile = path.join(repoRoot, "cli", "src", "lib", "generate.ts");
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 42,
+                path: targetFile,
+                filename: "generate.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "foo.*bar",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: { intent: { intent: "", intentCategory: "explanation", normalizedQuery: "", confidence: 0.8 } },
+            },
+            query: "foo.*bar",
+            mode: "operator-pattern",
+        });
+        expect(result.mode).toBe("operator-pattern");
+        expect(result.patternMatches).toEqual([]);
+        expect(result.stagesRun).toContain("fallback-semantic-retriever");
+        expect(result.fallbackUsed).toBe(true);
+        expect(result.fileCandidates.map(item => item.path)).toEqual([targetFile]);
+    });
+    it("does not treat shell command mentions as exact-target refs in auto mode", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const targetFile = path.join(repoRoot, "cli", "src", "commands", "TasksCmd.ts");
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 43,
+                path: targetFile,
+                filename: "TasksCmd.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "How does /resume work?",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: { intent: { intent: "explain", intentCategory: "explanation", normalizedQuery: "", confidence: 0.8 } },
+            },
+            query: "How does /resume work?",
+            mode: "auto",
+        });
+        expect(result.mode).toBe("semantic-retrieval");
+        expect(result.unresolvedRefs).toEqual([]);
+        expect(result.fileCandidates.map(item => item.path)).toEqual([targetFile]);
+    });
+    it("keeps semantic retrieval separate from exact-target resolution", async () => {
+        mocks.semanticSearchFiles.mockResolvedValue([
+            {
+                id: 11,
+                path: "/repo/src/search.ts",
+                filename: "search.ts",
+                summary: null,
+                type: "ts",
+                lastModified: new Date(0).toISOString(),
+                bm25Score: -1,
+            },
+        ]);
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "find the code that handles search",
+                    executionPath: "/repo",
+                    repoRootPath: "/repo",
+                },
+                analysis: { intent: { intent: "", intentCategory: "explanation", normalizedQuery: "", confidence: 0.8 } },
+            },
+            query: "find the code that handles search",
+            mode: "semantic-retrieval",
+        });
+        expect(result.resolvedFiles).toEqual([]);
+        expect(result.fileCandidates.map(item => item.path)).toEqual(["/repo/src/search.ts"]);
+    });
+    it("passes parsed intent into semantic retrieval", async () => {
+        mocks.semanticSearchFiles.mockResolvedValue([]);
+        await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "trace db client setup",
+                    executionPath: "/repo",
+                    repoRootPath: "/repo",
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace",
+                        intentCategory: "explanation",
+                        normalizedQuery: "trace db client setup",
+                        confidence: 0.8,
+                        targetFiles: ["db/client.ts"],
+                        targetSymbols: ["getDbForRepo"],
+                    },
+                },
+            },
+            query: "trace db client setup",
+            mode: "semantic-retrieval",
+        });
+        expect(mocks.semanticSearchFiles).toHaveBeenCalledWith("trace db client setup", 8, expect.objectContaining({
+            targetFiles: ["db/client.ts"],
+            targetSymbols: ["getDbForRepo"],
+        }));
+    });
+    it("runs planner retrieval for each ordered question in multi-question asks", async () => {
+        mocks.plannerSearchFiles.mockImplementation(async (_query, plannerQuery) => {
+            if (plannerQuery === "Where is search routed?") {
+                return [{
+                        id: 21,
+                        path: "/repo/cli/src/agents/routingDecisionStep.ts",
+                        filename: "routingDecisionStep.ts",
+                        summary: null,
+                        type: "ts",
+                        lastModified: new Date(0).toISOString(),
+                    }];
+            }
+            if (plannerQuery === "How is verify triggered?") {
+                return [{
+                        id: 22,
+                        path: "/repo/cli/src/agents/mainAgentVerify.ts",
+                        filename: "mainAgentVerify.ts",
+                        summary: null,
+                        type: "ts",
+                        lastModified: new Date(0).toISOString(),
+                    }];
+            }
+            return [];
+        });
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Where is search routed? How is verify triggered?",
+                    executionPath: "/repo",
+                    repoRootPath: "/repo",
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace routing and verify",
+                        intentCategory: "question",
+                        normalizedQuery: "Where is search routed and how is verify triggered?",
+                        confidence: 0.95,
+                        questions: [
+                            { id: "q1", order: 0, text: "Where is search routed?" },
+                            { id: "q2", order: 1, text: "How is verify triggered?" },
+                        ],
+                    },
+                },
+            },
+            query: "Where is search routed? How is verify triggered?",
+            mode: "semantic-retrieval",
+        });
+        expect(mocks.plannerSearchFiles).toHaveBeenCalledWith("Where is search routed? How is verify triggered?", "Where is search routed?", 6);
+        expect(mocks.plannerSearchFiles).toHaveBeenCalledWith("Where is search routed? How is verify triggered?", "How is verify triggered?", 6);
+        expect(result.fileCandidates.map(item => item.path)).toEqual([
+            "/repo/cli/src/agents/routingDecisionStep.ts",
+            "/repo/cli/src/agents/mainAgentVerify.ts",
+        ]);
+    });
+    it("adds path-scored implementation supplements for verify-focus queries", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const verifyFile = path.join(repoRoot, "cli", "src", "agents", "mainAgentVerify.ts");
+        const fileCheckFile = path.join(repoRoot, "cli", "src", "agents", "fileCheckStep.ts");
+        const readmeFile = path.join(repoRoot, "README.md");
+        fs.mkdirSync(path.dirname(verifyFile), { recursive: true });
+        fs.writeFileSync(verifyFile, "export function runVerify() {}\n", "utf8");
+        fs.writeFileSync(fileCheckFile, "export function fileCheckStep() {}\n", "utf8");
+        fs.writeFileSync(readmeFile, "selectedFiles candidateFiles verify\n", "utf8");
+        mocks.scoreCandidateFiles.mockImplementation(((filePaths, ...rest) => {
+            const retrievalQuery = String(rest[1] ?? "");
+            if (!retrievalQuery.includes("selectedFiles")) {
+                return filePaths.map((filePath, index) => ({ filePath, score: 5 - index, reasons: [] }));
+            }
+            return [
+                { filePath: verifyFile, score: 80, reasons: ["verify-focus"] },
+                { filePath: fileCheckFile, score: 74, reasons: ["verify-focus"] },
+                { filePath: readmeFile, score: 8, reasons: ["doc"] },
+            ];
+        }));
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "Trace how selectedFiles and candidateFiles evolve across verify waves for this query.",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "trace verify focus",
+                        intentCategory: "explanation",
+                        normalizedQuery: "Trace how selectedFiles and candidateFiles evolve across verify waves for this query.",
+                        confidence: 0.95,
+                    },
+                },
+            },
+            query: "Trace how selectedFiles and candidateFiles evolve across verify waves for this query.",
+            mode: "semantic-retrieval",
+        });
+        expect(result.fileCandidates.map(item => item.path)).toContain(verifyFile);
+        expect(result.fileCandidates.map(item => item.path)).toContain(fileCheckFile);
+        expect(result.fileCandidates.map(item => item.path)).not.toContain(readmeFile);
+    });
+    it("excludes hidden junk when exact-target resolves a folder", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const artifactsDir = path.join(repoRoot, "artifacts");
+        const nestedDir = path.join(artifactsDir, "integration");
+        fs.mkdirSync(nestedDir, { recursive: true });
+        fs.writeFileSync(path.join(artifactsDir, ".DS_Store"), "junk", "utf8");
+        fs.writeFileSync(path.join(artifactsDir, "report.md"), "# report\n", "utf8");
+        fs.writeFileSync(path.join(nestedDir, "deep.txt"), "deep\n", "utf8");
+        const result = await new SearchOrchestrator().run({
+            context: {
+                initContext: {
+                    userQuery: "check artifacts",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        intent: "check",
+                        intentCategory: "explanation",
+                        normalizedQuery: "check artifacts",
+                        confidence: 0.8,
+                        targetFiles: ["artifacts"],
+                        targetSymbols: [],
+                    },
+                },
+            },
+            query: "check artifacts",
+            mode: "exact-target",
+        });
+        expect(result.fileCandidates.map(item => path.basename(item.path)).sort()).toEqual(["deep.txt", "report.md"]);
+    });
+    it("returns a structured invalid-regex failure for broken regex specs", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const result = await new SearchOrchestrator().runRegexSearch({
+            context: {
+                initContext: {
+                    userQuery: "find broken regex results",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+            },
+            spec: {
+                target: "path",
+                pattern: "[broken",
+            },
+        });
+        expect(result.mode).toBe("regex-execution");
+        expect(result.failure?.failureClass).toBe("invalid-regex");
+    });
+    it("lists direct directory children without recursing", async () => {
+        const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "scai-search-orchestrator-"));
+        tempDirs.push(repoRoot);
+        const artifactsDir = path.join(repoRoot, "artifacts");
+        const nestedDir = path.join(artifactsDir, "integration");
+        fs.mkdirSync(nestedDir, { recursive: true });
+        fs.writeFileSync(path.join(artifactsDir, ".DS_Store"), "junk", "utf8");
+        fs.writeFileSync(path.join(artifactsDir, "report.md"), "# report\n", "utf8");
+        fs.writeFileSync(path.join(nestedDir, "deep.txt"), "deep\n", "utf8");
+        const result = new SearchOrchestrator().runDirectoryListing({
+            context: {
+                initContext: {
+                    userQuery: "what files are in the artifacts folder?",
+                    executionPath: repoRoot,
+                    repoRootPath: repoRoot,
+                },
+                analysis: {
+                    intent: {
+                        targetFiles: ["artifacts"],
+                    },
+                },
+            },
+            query: "what files are in the artifacts folder?",
+        });
+        expect(result.mode).toBe("directory-listing");
+        expect(result.directoryEntries).toEqual([
+            { path: path.join(artifactsDir, "integration"), name: "integration", kind: "folder" },
+            { path: path.join(artifactsDir, "report.md"), name: "report.md", kind: "file" },
+        ]);
+        expect(result.fileCandidates).toEqual([]);
+    });
+});
+//# sourceMappingURL=SearchOrchestrator.test.js.map