scai 0.1.178 → 1.0.1

package/dist/__tests__/agents/agentLoop.test.js

@@ -0,0 +1,1723 @@
+/**
+ * Covers the first simple agent loop slice without touching the legacy MainAgent.
+ *
+ * Why this file exists:
+ * - the new runtime needs one tight end-to-end test while it is still small
+ * - read-only answer flow should stay stable before more actions are reintroduced
+ * - mocked model calls let the test focus on loop behavior instead of model variance
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+const configState = vi.hoisted(() => ({
+    getDevOutput: vi.fn(() => false),
+}));
+const searchState = vi.hoisted(() => ({
+    dbFileCandidates: new Map(),
+}));
+vi.mock("../../config.js", () => ({
+    Config: {
+        getDevOutput: configState.getDevOutput,
+    },
+}));
+import { runAgentLoop } from "../../agents/agentLoop.js";
+import { createAgentMemory } from "../../agents/agentMemory.js";
+const generateMock = vi.fn();
+const state = vi.hoisted(() => ({
+    logRuntimeRecord: vi.fn(),
+}));
+vi.mock("../../lib/generate.js", () => ({
+    generate: (...args) => generateMock(...args),
+}));
+vi.mock("../../utils/promptLogHelper.js", () => ({
+    logInputOutput: vi.fn(),
+}));
+vi.mock("../../search/SearchOrchestrator.js", () => ({
+    SearchOrchestrator: class {
+        async runDbSearch(args) {
+            const filePaths = searchState.dbFileCandidates.get(args.query) ?? [];
+            return {
+                route: "db",
+                mode: args.query.includes("/resume") ? "exact-target" : "semantic-retrieval",
+                stagesRun: args.query.includes("/resume")
+                    ? ["explicit-target-resolver", "fallback-semantic-retriever", "result-merger-and-ranker"]
+                    : ["semantic-retriever", "result-merger-and-ranker"],
+                resolvedFiles: [],
+                resolvedFolders: [],
+                resolvedSymbols: [],
+                unresolvedRefs: args.query.includes("/resume") ? ["/resume"] : [],
+                ambiguousRefs: [],
+                fileCandidates: filePaths.map((filePath) => ({
+                    id: 1,
+                    path: filePath,
+                    filename: path.basename(filePath),
+                    summary: null,
+                    type: path.extname(filePath).replace(/^\./, "") || "ts",
+                    lastModified: new Date(0).toISOString(),
+                })),
+                folderCandidates: [],
+                symbolCandidates: [],
+                fragmentMatches: [],
+                patternMatches: [],
+                directoryEntries: [],
+                fallbackUsed: args.query.includes("/resume"),
+            };
+        }
+        async runRegexSearch() {
+            return {
+                route: "regex",
+                mode: "regex-execution",
+                stagesRun: ["regex-searcher", "result-merger-and-ranker"],
+                resolvedFiles: [],
+                resolvedFolders: [],
+                resolvedSymbols: [],
+                unresolvedRefs: [],
+                ambiguousRefs: [],
+                fileCandidates: [{
+                        id: 1,
+                        path: "/repo/mock-regex-hit.ts",
+                        filename: "mock-regex-hit.ts",
+                        summary: null,
+                        type: "ts",
+                        lastModified: new Date(0).toISOString(),
+                    }],
+                folderCandidates: [],
+                symbolCandidates: [],
+                fragmentMatches: [],
+                patternMatches: [{
+                        path: "/repo/mock-regex-hit.ts",
+                        line: 1,
+                        column: 1,
+                        snippet: "mock regex hit",
+                    }],
+                directoryEntries: [],
+                fallbackUsed: false,
+            };
+        }
+        runDirectoryListing(args) {
+            return {
+                route: "list-directory",
+                mode: "directory-listing",
+                stagesRun: ["directory-listing"],
+                resolvedFiles: [],
+                resolvedFolders: [args.query],
+                resolvedSymbols: [],
+                unresolvedRefs: [],
+                ambiguousRefs: [],
+                fileCandidates: [],
+                folderCandidates: [args.query],
+                symbolCandidates: [],
+                fragmentMatches: [],
+                patternMatches: [],
+                directoryEntries: [],
+                fallbackUsed: false,
+            };
+        }
+    },
+}));
+vi.mock("../../utils/runtimeLogger.js", () => ({
+    logRuntimeRecord: state.logRuntimeRecord,
+    clearRuntimeLogs: vi.fn(),
+    appendHumanRuntimeEntry: vi.fn(),
+}));
+describe("runAgentLoop", () => {
+    let tempDir;
+    let targetFile;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "scai-agent-loop-"));
+        targetFile = path.join(tempDir, "sample.ts");
+        fs.writeFileSync(targetFile, [
+            "/**",
+            " * Sample file for the new agent loop test.",
+            " * It exposes a few exported contracts for grounding checks.",
+            " */",
+            "export interface SampleConfig {",
+            "  enabled: boolean;",
+            "}",
+            "export function sampleAnswer() {",
+            "  return 'answer';",
+            "}",
+            "export const sampleLabel = 'sample';",
+        ].join("\n"), "utf-8");
+        generateMock.mockReset();
+        state.logRuntimeRecord.mockReset();
+        searchState.dbFileCandidates.clear();
+        configState.getDevOutput.mockReset();
+        configState.getDevOutput.mockReturnValue(false);
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    it("reads one explicit file and produces a final answer", async () => {
+        configState.getDevOutput.mockReturnValue(true);
+        generateMock
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0001-agent-understand",
+                startedAt: "2026-05-01T06:16:21.000+02:00",
+                finishedAt: "2026-05-01T06:16:23.000+02:00",
+                durationMs: 2000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                normalizedQuery: `Explain ${targetFile}`,
+                explicitTargets: [targetFile],
+                constraints: [],
+                primaryIntent: "Explain the target file.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0002-agent-action-choice",
+                startedAt: "2026-05-01T06:16:24.000+02:00",
+                finishedAt: "2026-05-01T06:16:25.000+02:00",
+                durationMs: 1000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the explicit file first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0003-agent-read-file",
+                startedAt: "2026-05-01T06:16:25.100+02:00",
+                finishedAt: "2026-05-01T06:16:25.400+02:00",
+                durationMs: 300,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                summary: "Sample file for the new agent loop test.",
+                relevanceExplanation: "This file defines sampleAnswer and the exported sample contracts used by the query.",
+                role: "primary",
+                keySymbols: ["SampleConfig", "sampleAnswer", "sampleLabel"],
+                excerpts: [{
+                        description: "The main answer function.",
+                        startLine: 8,
+                        endLine: 10,
+                        symbols: ["sampleAnswer"],
+                        code: "export function sampleAnswer() {\n  return 'answer';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0004-agent-action-choice",
+                startedAt: "2026-05-01T06:16:25.500+02:00",
+                finishedAt: "2026-05-01T06:16:26.000+02:00",
+                durationMs: 500,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The file read is enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0005-agent-final-answer",
+                startedAt: "2026-05-01T06:16:26.000+02:00",
+                finishedAt: "2026-05-01T06:16:29.000+02:00",
+                durationMs: 3000,
+                attemptCount: 1,
+            },
+            data: "The file defines sampleAnswer in sample.ts.",
+        });
+        const memory = createAgentMemory(`Explain ${targetFile}`, tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        const finalStep = memory.steps.find((step) => step.action === "final-answer");
+        expect(memory.task.status).toBe("done");
+        expect(memory.artifacts.finalAnswer).toContain("sampleAnswer");
+        expect(Object.keys(memory.evidence.fileReads)).toContain(targetFile);
+        expect(memory.events.map((event) => event.type)).toContain("task-finalized");
+        expect(finalStep).toMatchObject({
+            status: "done",
+            resultSummary: "Task completed with a final answer.",
+        });
+        expect(finalStep?.startedAt).toBeTruthy();
+        expect(finalStep?.completedAt).toBeTruthy();
+        expect(ui.update).toHaveBeenCalledWith("Understanding request");
+        expect(ui.update).toHaveBeenCalledWith("Choosing next action (turn 1/12)");
+        expect(ui.update).toHaveBeenCalledWith("Reading file (turn 1/12)");
+        expect(ui.update).toHaveBeenCalledWith("Producing final answer (turn 2/12)");
+        expect(ui.message).toHaveBeenCalledWith("[LLM] understand finished | 2s");
+        expect(ui.message).toHaveBeenCalledWith("[LLM] action-choice finished | 1s");
+        expect(ui.message).toHaveBeenCalledWith("[LLM] action-choice finished | 500ms");
+        expect(ui.message).toHaveBeenCalledWith("[LLM] final-answer finished | 3s");
+        expect(ui.message).toHaveBeenCalledWith("[STATE] step step-001 created -> pending | action=read-file");
+        expect(ui.message).toHaveBeenCalledWith(expect.stringContaining("[STATE] step step-001 pending -> running | action=read-file"));
+        expect(ui.message).toHaveBeenCalledWith("[STATE] step step-002 created -> pending | action=final-answer");
+        expect(ui.message).toHaveBeenCalledWith("[STATE] task active -> done | reason=completed");
+        expect(ui.message).not.toHaveBeenCalledWith("Understanding request.");
+        expect(ui.message).not.toHaveBeenCalledWith("Chose direct file read.");
+        expect(ui.message).not.toHaveBeenCalledWith("Producing final answer.");
+        expect(state.logRuntimeRecord).toHaveBeenCalledWith(expect.objectContaining({
+            kind: "llm",
+            phase: "output",
+            payload: expect.objectContaining({
+                durationMs: 3000,
+                attemptCount: 1,
+                callId: "llm-0005-agent-final-answer",
+            }),
+        }));
+        expect(generateMock).toHaveBeenLastCalledWith(expect.objectContaining({
+            content: expect.stringContaining('"keySymbols": ['),
+        }), expect.objectContaining({
+            inputContext: expect.objectContaining({
+                fileReads: [
+                    expect.objectContaining({
+                        filePath: targetFile,
+                        keySymbols: expect.arrayContaining(["SampleConfig", "sampleAnswer", "sampleLabel"]),
+                    }),
+                ],
+            }),
+        }));
+    });
+    it("lists a resolved folder first and then reads canonical folder files before answering", async () => {
+        const guardsDir = path.join(tempDir, "cli", "src", "agents", "guards");
+        const resolverFile = path.join(guardsDir, "executionPolicyResolver.ts");
+        const stateFile = path.join(guardsDir, "guardState.ts");
+        fs.mkdirSync(guardsDir, { recursive: true });
+        fs.writeFileSync(resolverFile, "export const resolver = true;\n", "utf-8");
+        fs.writeFileSync(stateFile, "export const guard = true;\n", "utf-8");
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: guardsDir,
+                explicitTargets: [guardsDir],
+                constraints: [],
+                primaryIntent: "Explain the guards directory.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: guardsDir },
+                reason: "Read the directory directly.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: guardsDir },
+                reason: "Read one file from the directory.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Execution policy owner.",
+                relevanceExplanation: "This file resolves execution policy for the guards area.",
+                role: "primary",
+                excerpts: [{
+                        description: "Resolver export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["resolver"],
+                        code: "export const resolver = true;",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "One file should be enough.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Guard state owner.",
+                relevanceExplanation: "This file holds guard state used by the directory the user asked about.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Guard export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["guard"],
+                        code: "export const guard = true;",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The folder evidence is grounded now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The guards directory includes executionPolicyResolver.ts and guardState.ts.",
+        });
+        const memory = createAgentMemory(guardsDir, tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.steps.map((step) => step.action)).toEqual([
+            "search-list-directory",
+            "read-file",
+            "read-file",
+            "final-answer",
+        ]);
+        expect(memory.steps.some((step) => step.status === "failed")).toBe(false);
+        expect(Object.keys(memory.evidence.fileReads)).toEqual(expect.arrayContaining([resolverFile, stateFile]));
+        expect(memory.artifacts.finalAnswer).toContain("executionPolicyResolver.ts");
+    });
+    it("does not allow final-answer until all explicit targets have been read", async () => {
+        const secondFile = path.join(tempDir, "factory.ts");
+        const thirdFile = path.join(tempDir, "runQueryWithDaemonControl.ts");
+        fs.writeFileSync(secondFile, "export function createFactory() {}\n", "utf-8");
+        fs.writeFileSync(thirdFile, "export function runQueryWithDaemonControl() {}\n", "utf-8");
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Summarize CLI architecture",
+                explicitTargets: [targetFile, secondFile, thirdFile],
+                constraints: [],
+                primaryIntent: "Summarize the CLI architecture.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the first explicit target.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Primary sample file.",
+                relevanceExplanation: "This file is one explicit target in the requested architecture summary.",
+                role: "primary",
+                excerpts: [{
+                        description: "Sample answer export.",
+                        startLine: 8,
+                        endLine: 10,
+                        symbols: ["sampleAnswer"],
+                        code: "export function sampleAnswer() {\n  return 'answer';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "One file seems enough.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Factory file.",
+                relevanceExplanation: "This explicit target contributes the factory step in the requested architecture summary.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Factory export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["createFactory"],
+                        code: "export function createFactory() {}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the next explicit target instead of answering.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Daemon control file.",
+                relevanceExplanation: "This final explicit target completes the architecture path the user asked about.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Daemon control export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["runQueryWithDaemonControl"],
+                        code: "export function runQueryWithDaemonControl() {}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "Two files seem enough.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the last explicit target instead of answering.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "README install guide.",
+                relevanceExplanation: "This README is the resolved documentation file that contains the install instructions.",
+                role: "primary",
+                excerpts: [{
+                        description: "Install section.",
+                        startLine: 1,
+                        endLine: 3,
+                        symbols: ["README"],
+                        code: "# Install\n\nRun `npm install -g scai-cli`.",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "All explicit targets are grounded now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The architecture flows from sample.ts into factory.ts and then runQueryWithDaemonControl.ts.",
+        });
+        const memory = createAgentMemory("Summarize CLI architecture", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.steps.map((step) => step.action)).toEqual([
+            "read-file",
+            "read-file",
+            "read-file",
+            "final-answer",
+        ]);
+        expect(Object.keys(memory.evidence.fileReads)).toEqual(expect.arrayContaining([targetFile, secondFile, thirdFile]));
+    });
+    it("auto-resolves the scoped duplicate filename before reading when sibling explicit targets make the scope clear", async () => {
+        const cliIndex = path.join(tempDir, "cli", "src", "index.ts");
+        const webIndex = path.join(tempDir, "web", "src", "index.ts");
+        const factoryFile = path.join(tempDir, "cli", "src", "commands", "factory.ts");
+        const daemonFile = path.join(tempDir, "cli", "src", "runQueryWithDaemonControl.ts");
+        fs.mkdirSync(path.dirname(cliIndex), { recursive: true });
+        fs.mkdirSync(path.dirname(webIndex), { recursive: true });
+        fs.mkdirSync(path.dirname(factoryFile), { recursive: true });
+        fs.writeFileSync(cliIndex, "export const cli = true;\n", "utf-8");
+        fs.writeFileSync(webIndex, "export const web = true;\n", "utf-8");
+        fs.writeFileSync(factoryFile, "export function createFactory() {}\n", "utf-8");
+        fs.writeFileSync(daemonFile, "export function runQueryWithDaemonControl() {}\n", "utf-8");
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Summarize CLI architecture from index.ts, commands/factory.ts, and runQueryWithDaemonControl.ts",
+                explicitTargets: ["index.ts", "commands/factory.ts", "runQueryWithDaemonControl.ts"],
+                constraints: [],
+                primaryIntent: "Summarize the CLI architecture from the requested files.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "Summarize CLI architecture from index.ts, commands/factory.ts, and runQueryWithDaemonControl.ts" },
+                reason: "Resolve the explicit targets first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "Try to answer immediately.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "CLI index entrypoint.",
+                relevanceExplanation: "This is the scoped CLI index target selected from the duplicate basename candidates.",
+                role: "primary",
+                excerpts: [{
+                        description: "CLI export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["cli"],
+                        code: "export const cli = true;",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "Try to answer again.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Factory file.",
+                relevanceExplanation: "This file contributes the command factory step in the requested architecture summary.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Factory export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["createFactory"],
+                        code: "export function createFactory() {}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "Try to answer a third time.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Daemon control file.",
+                relevanceExplanation: "This file completes the daemon-controlled query path the user asked about.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Daemon control export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["runQueryWithDaemonControl"],
+                        code: "export function runQueryWithDaemonControl() {}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "All requested files are grounded now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The CLI architecture flows from cli/src/index.ts into commands/factory.ts and then runQueryWithDaemonControl.ts.",
+        });
+        const memory = createAgentMemory("Summarize CLI architecture from index.ts, commands/factory.ts, and runQueryWithDaemonControl.ts", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.task.dialogState).toBeUndefined();
+        expect(memory.steps.map((step) => step.action)).toEqual([
+            "search-db",
+            "read-file",
+            "read-file",
+            "read-file",
+            "final-answer",
+        ]);
+        expect(Object.keys(memory.evidence.fileReads)).toEqual(expect.arrayContaining([cliIndex, factoryFile, daemonFile]));
+        expect(Object.keys(memory.evidence.fileReads)).not.toContain(webIndex);
+    });
+    it("waits for user input immediately when a duplicate filename stays ambiguous", async () => {
+        const cliIndex = path.join(tempDir, "cli", "src", "index.ts");
+        const webIndex = path.join(tempDir, "web", "src", "index.ts");
+        fs.mkdirSync(path.dirname(cliIndex), { recursive: true });
+        fs.mkdirSync(path.dirname(webIndex), { recursive: true });
+        fs.writeFileSync(cliIndex, "export const cli = true;\n", "utf-8");
+        fs.writeFileSync(webIndex, "export const web = true;\n", "utf-8");
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Summarize architecture from index.ts",
+                explicitTargets: ["index.ts"],
+                constraints: [],
+                primaryIntent: "Summarize the requested file.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "Summarize architecture from index.ts" },
+                reason: "Resolve the explicit target first.",
+            }),
+        });
+        const memory = createAgentMemory("Summarize architecture from index.ts", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("waiting");
+        expect(memory.steps.map((step) => step.action)).toEqual([
+            "search-db",
+            "request-user-input",
+        ]);
+        expect(memory.task.dialogState).toMatchObject({
+            status: "awaiting-user",
+            target: "index.ts",
+            options: [cliIndex, webIndex],
+        });
+        expect(ui.message).toHaveBeenCalledWith("Requesting user input.");
+    });
+    it("reads a resolved README candidate before answering doc-style install questions", async () => {
+        const readmeFile = path.join(tempDir, "README.md");
+        fs.writeFileSync(readmeFile, "# Install\n\nRun `npm install -g scai-cli`.\n", "utf-8");
+        searchState.dbFileCandidates.set("please check the readme for how to install scai cli?", [readmeFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "please check the readme for how to install scai cli?",
+                explicitTargets: ["readme"],
+                constraints: [],
+                primaryIntent: "Explain the install instructions from the docs.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "please check the readme for how to install scai cli?" },
+                reason: "Find the likely documentation file first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: "readme" },
+                reason: "Read the resolved README before answering.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "README completeness audit target.",
+                relevanceExplanation: "This README is the explicit file the user asked to audit for missing sections.",
+                role: "primary",
+                excerpts: [{
+                        description: "Install and usage sections.",
+                        startLine: 1,
+                        endLine: 9,
+                        symbols: ["README"],
+                        code: "# CLI\n\n## Install\n\nRun `npm install -g scai-cli`.\n\n## Usage\n\nUse `scai ask` to query the repo.",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The grounded README read is enough to answer.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The install instructions are in README.md.",
+        });
+        const memory = createAgentMemory("please check the readme for how to install scai cli?", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(Object.keys(memory.evidence.fileReads)).toContain(readmeFile);
+        expect(memory.steps.map((step) => step.action)).toEqual(["search-db", "read-file", "final-answer"]);
+    });
+    it("uses one read-file step for README completeness questions and avoids rereading the same file", async () => {
+        const readmeFile = path.join(tempDir, "README.md");
+        fs.writeFileSync(readmeFile, [
+            "# CLI",
+            "",
+            "## Install",
+            "",
+            "Run `npm install -g scai-cli`.",
+            "",
+            "## Usage",
+            "",
+            "Use `scai ask` to query the repo.",
+        ].join("\n"), "utf-8");
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "is anything missing from the readme?",
+                explicitTargets: [readmeFile],
+                constraints: [],
+                primaryIntent: "Audit the README for missing information.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: readmeFile },
+                reason: "Read the README first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Matching scai README.",
+                relevanceExplanation: "The resolved README directly matches the search request and contains the scai docs.",
+                role: "primary",
+                excerpts: [{
+                        description: "README body.",
+                        startLine: 1,
+                        endLine: 2,
+                        code: "# Scai\n\nThis README explains how to find and use the scai project docs.",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The grounded README read is enough to answer.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The README covers install and usage, but I do not see sections for configuration or contribution guidance.",
+        });
+        const memory = createAgentMemory("is anything missing from the readme?", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.steps.map((step) => step.action)).toEqual(["read-file", "final-answer"]);
+        expect(memory.evidence.fileReads[readmeFile]).toMatchObject({
+            filePath: readmeFile,
+            relevantContext: expect.arrayContaining([
+                expect.objectContaining({ kind: "purpose" }),
+            ]),
+        });
+        expect(memory.artifacts.finalAnswer).toContain("configuration");
+    });
+    it("normalizes search-db pattern args into query before validation", async () => {
+        const readmeFile = path.join(tempDir, "README.md");
+        fs.writeFileSync(readmeFile, "# Scai\n\nThis README explains how to find and use the scai project docs.\n", "utf-8");
+        searchState.dbFileCandidates.set("scai", [readmeFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "find readme files for scai",
+                explicitTargets: ["readme"],
+                constraints: [],
+                primaryIntent: "Locate readme files for scai.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { pattern: "scai" },
+                reason: "Search for likely scai docs first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: "readme" },
+                reason: "Read the matching readme.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The grounded readme is enough to answer.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "README.md matches the scai search.",
+        });
+        const memory = createAgentMemory("find readme files for scai", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.events.some((event) => event.type === "validation-failed")).toBe(false);
+        expect(memory.evidence.searches[0]).toMatchObject({
+            action: "search-db",
+            query: "find readme files for scai",
+        });
+        expect(Object.keys(memory.evidence.fileReads)).toContain(readmeFile);
+        expect(memory.task.status).toBe("done");
+    });
+    it("keeps new-agent timing out of console milestones when dev output is off", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0001-agent-understand",
+                startedAt: "2026-05-01T06:16:21.000+02:00",
+                finishedAt: "2026-05-01T06:16:23.000+02:00",
+                durationMs: 2000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                normalizedQuery: `Explain ${targetFile}`,
+                explicitTargets: [targetFile],
+                constraints: [],
+                primaryIntent: "Explain the target file.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0002-agent-action-choice",
+                startedAt: "2026-05-01T06:16:24.000+02:00",
+                finishedAt: "2026-05-01T06:16:25.000+02:00",
+                durationMs: 1000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the explicit file first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0003-agent-read-file",
+                startedAt: "2026-05-01T06:16:25.100+02:00",
+                finishedAt: "2026-05-01T06:16:25.400+02:00",
+                durationMs: 300,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                summary: "Sample file for the new agent loop test.",
+                relevanceExplanation: "This file defines sampleAnswer and the exported sample contracts used by the query.",
+                role: "primary",
+                excerpts: [{
+                        description: "The main answer function.",
+                        startLine: 8,
+                        endLine: 10,
+                        symbols: ["sampleAnswer"],
+                        code: "export function sampleAnswer() {\n  return 'answer';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0004-agent-action-choice",
+                startedAt: "2026-05-01T06:16:25.500+02:00",
+                finishedAt: "2026-05-01T06:16:26.000+02:00",
+                durationMs: 500,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The file read is enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0005-agent-final-answer",
+                startedAt: "2026-05-01T06:16:26.000+02:00",
+                finishedAt: "2026-05-01T06:16:29.000+02:00",
+                durationMs: 3000,
+                attemptCount: 1,
+            },
+            data: "The file defines sampleAnswer in sample.ts.",
+        });
+        const memory = createAgentMemory(`Explain ${targetFile}`, tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(ui.message).not.toHaveBeenCalledWith("Understanding request (2s).");
+        expect(ui.message).not.toHaveBeenCalledWith("Choosing next action (1s).");
+        expect(ui.message).not.toHaveBeenCalledWith("Producing final answer (3s).");
+    });
+    it("requests one focused user input when no grounded evidence exists and scope stays broad", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0001-agent-understand",
+                startedAt: "2026-05-01T06:16:21.000+02:00",
+                finishedAt: "2026-05-01T06:16:23.000+02:00",
+                durationMs: 2000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                normalizedQuery: "Explain how missing evidence flow works",
+                queryScope: "broad-repo",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Explain how missing evidence flow works.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0002-agent-action-choice",
+                startedAt: "2026-05-01T06:16:24.000+02:00",
+                finishedAt: "2026-05-01T06:16:25.000+02:00",
+                durationMs: 1000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                action: "plan",
+                args: {},
+                reason: "Plan the next step.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            trace: {
+                callId: "llm-0003-agent-plan",
+                startedAt: "2026-05-01T06:16:26.000+02:00",
+                finishedAt: "2026-05-01T06:16:28.000+02:00",
+                durationMs: 2000,
+                attemptCount: 1,
+            },
+            data: JSON.stringify({
+                goal: "Explain missing evidence flow",
+                why: "Need one step first.",
+                steps: [
+                    {
+                        action: "search-db",
+                        args: { query: "missing evidence flow" },
+                        purpose: "Try indexed search.",
+                        expectedEvidence: ["candidate files"],
+                    },
+                ],
+            }),
+        });
+        const memory = createAgentMemory("Explain how missing evidence flow works", tempDir, tempDir);
+        memory.task.maxTurns = 2;
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        const waitingStep = memory.steps.find((step) => step.action === "request-user-input");
+        expect(memory.task.status).toBe("waiting");
+        expect(memory.artifacts.stopMessage).toContain("I could not answer yet.");
+        expect(memory.artifacts.stopMessage).toContain("I need one thing from you:");
+        expect(memory.task.dialogState).toMatchObject({
+            status: "awaiting-user",
+            kind: "clarification",
+        });
+        expect(waitingStep).toMatchObject({
+            status: "done",
+            resultSummary: "Requested one focused user input.",
+        });
+        expect(waitingStep?.startedAt).toBeTruthy();
+        expect(waitingStep?.completedAt).toBeTruthy();
+        expect(ui.message).toHaveBeenCalledWith("Requesting user input.");
+    });
+    it("normalizes loose regex-search args before validation", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Find action names with regex",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Find action names with regex.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-regex",
+                args: {
+                    pattern: "plan|search-db|search-regex",
+                    directory: ".",
+                },
+                reason: "Search action names by regex.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "I searched file content for the requested regex pattern.",
+        });
+        const memory = createAgentMemory("Find action names with regex", tempDir, tempDir);
+        memory.task.maxTurns = 1;
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.events.map((event) => event.type)).not.toContain("validation-failed");
+        expect(memory.evidence.searches.some((search) => search.action === "search-regex")).toBe(true);
+        expect(memory.task.status).toBe("blocked");
+        expect(memory.artifacts.stopMessage).toContain("I could not answer from grounded repo evidence.");
+    });
+    it("reports cannot-answer when explicit targets still do not produce grounded evidence", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Explain how /etc/hosts is handled",
+                explicitTargets: ["/etc/hosts"],
+                constraints: [],
+                primaryIntent: "Explain how the target file is handled.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "plan",
+                args: {},
+                reason: "The explicit path is outside the repo, so plan a safer stop.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                goal: "Find a safe next step.",
+                why: "The direct file read failed.",
+                steps: [],
+            }),
+        });
+        const memory = createAgentMemory("Explain how /etc/hosts is handled", tempDir, tempDir);
+        memory.task.maxTurns = 1;
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        const stopStep = memory.steps.find((step) => step.action === "cannot-answer");
+        expect(memory.task.status).toBe("blocked");
+        expect(memory.artifacts.stopMessage).toContain("I could not answer from grounded repo evidence.");
+        expect(stopStep).toMatchObject({
+            status: "done",
+            resultSummary: "Reported that the agent could not answer.",
+        });
+        expect(Object.keys(memory.evidence.fileReads)).toHaveLength(0);
+    });
+    it("logs validation failures without pretending the step started", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Run a regex search for test files",
+                queryScope: "targeted",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Run a regex search safely.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-regex",
+                args: {},
+                reason: "Try a regex search first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                goal: "Find a safer step.",
+                why: "The first step was invalid.",
+                steps: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "I could not complete the regex search because the step arguments were invalid.",
+        });
+        const memory = createAgentMemory("Run a regex search for test files", tempDir, tempDir);
+        memory.task.maxTurns = 2;
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        const blockedStep = memory.steps.find((step) => step.action === "search-regex");
+        expect(memory.events.map((event) => event.type)).toContain("validation-failed");
+        expect(blockedStep?.status).toBe("blocked");
+        expect(blockedStep?.startedAt).toBeUndefined();
+        expect(memory.events.some((event) => event.type === "step-started" && event.stepId === blockedStep?.id)).toBe(false);
+        expect(ui.update).toHaveBeenCalledWith("Planning next steps (turn 1/2)");
+        expect(ui.message).toHaveBeenCalledWith("Planning next steps.");
+    });
+    it("marks a running step failed and finalizes once when the end-of-run answer throws", async () => {
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: `Explain ${targetFile}`,
+                explicitTargets: [targetFile],
+                constraints: [],
+                primaryIntent: "Explain the target file.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: targetFile },
+                reason: "Read the explicit file first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Sample file for the explicit-target explanation.",
+                relevanceExplanation: "This explicit file is the user-requested answer source.",
+                role: "primary",
+                excerpts: [{
+                        description: "Main export block.",
+                        startLine: 8,
+                        endLine: 10,
+                        symbols: ["sampleAnswer"],
+                        code: "export function sampleAnswer() {\n  return 'answer';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The file read is enough to answer now.",
+            }),
+        })
+            .mockRejectedValueOnce(Object.assign(new Error("final answer model failure"), {
+            trace: {
+                callId: "llm-0004-agent-final-answer",
+            },
+        }));
+        const memory = createAgentMemory(`Explain ${targetFile}`, tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await expect(runAgentLoop(memory, ui)).rejects.toThrow("final answer model failure");
+        const finalStep = memory.steps.find((step) => step.action === "final-answer");
+        const finalizedEvents = memory.events.filter((event) => event.type === "task-finalized");
+        expect(finalStep).toMatchObject({
+            status: "failed",
+            resultSummary: "final answer model failure",
+        });
+        expect(memory.task.status).toBe("failed");
+        expect(memory.task.stopReason).toBe("final-answer");
+        expect(finalizedEvents).toHaveLength(1);
+    });
+    it("uses search fallback results for /resume-style queries instead of ending empty", async () => {
+        const resumeFile = path.join(tempDir, "cli", "src", "commands", "TasksCmd.ts");
+        fs.mkdirSync(path.dirname(resumeFile), { recursive: true });
+        fs.writeFileSync(resumeFile, [
+            "/**",
+            " * Handles task shell commands, including resume.",
+            " */",
+            "export function runResumeCommand() {",
+            "  return 'resume';",
+            "}",
+        ].join("\n"), "utf-8");
+        searchState.dbFileCandidates.set("How does /resume for the simple agent work?", [resumeFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "How does /resume for the simple agent work?",
+                explicitTargets: ["/resume"],
+                constraints: [],
+                primaryIntent: "Explain the resume command flow.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "How does /resume for the simple agent work?" },
+                reason: "Search for the command implementation first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: resumeFile },
+                reason: "Read the best fallback candidate before answering.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Resume command implementation.",
+                relevanceExplanation: "This fallback candidate implements the resume command flow the user asked about.",
+                role: "primary",
+                excerpts: [{
+                        description: "Resume command function.",
+                        startLine: 4,
+                        endLine: 6,
+                        symbols: ["runResumeCommand"],
+                        code: "export function runResumeCommand() {\n  return 'resume';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The candidate read is enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The resume flow is handled in TasksCmd.ts.",
+        });
+        const memory = createAgentMemory("How does /resume for the simple agent work?", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.evidence.candidateFiles).toContain(resumeFile);
+        expect(Object.keys(memory.evidence.fileReads).length).toBeGreaterThan(0);
+        expect(memory.artifacts.finalAnswer).toContain("TasksCmd.ts");
+        expect(memory.steps.some((step) => step.action === "cannot-answer")).toBe(false);
+    });
+    it("searches before reading when the explicit target is only a basename", async () => {
+        const indexFile = path.join(tempDir, "cli", "src", "index.ts");
+        fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+        fs.writeFileSync(indexFile, [
+            "/**",
+            " * CLI entrypoint for the basename resolution test.",
+            " */",
+            "export function runCliEntry() {",
+            "  return 'cli';",
+            "}",
+        ].join("\n"), "utf-8");
+        searchState.dbFileCandidates.set("Explain index.ts", [indexFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Explain index.ts",
+                explicitTargets: ["index.ts"],
+                constraints: [],
+                primaryIntent: "Explain the index file.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "Explain index.ts" },
+                reason: "Resolve the basename before reading.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: "index.ts" },
+                reason: "Read the resolved basename target.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Resolved basename target.",
+                relevanceExplanation: "This file is the resolved index.ts target and contains the CLI entrypoint.",
+                role: "primary",
+                excerpts: [{
+                        description: "CLI entrypoint export.",
+                        startLine: 4,
+                        endLine: 6,
+                        symbols: ["runCliEntry"],
+                        code: "export function runCliEntry() {\n  return 'cli';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The grounded read is enough to answer.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The basename target resolves to cli/src/index.ts and defines runCliEntry.",
+        });
+        const memory = createAgentMemory("Explain index.ts", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(memory.evidence.candidateFiles).toContain(indexFile);
+        expect(Object.keys(memory.evidence.fileReads)).toContain(indexFile);
+        expect(memory.steps.filter((step) => step.action === "read-file" && step.status === "failed")).toHaveLength(0);
+        expect(memory.artifacts.finalAnswer).toContain("cli/src/index.ts");
+    });
+    it("normalizes read-file path aliases from model output so /resume-style reads do not block", async () => {
+        const resumeFile = path.join(tempDir, "cli", "src", "agents", "resumeContinuityStep.ts");
+        fs.mkdirSync(path.dirname(resumeFile), { recursive: true });
+        fs.writeFileSync(resumeFile, [
+            "/**",
+            " * Explains how resume continuity works.",
+            " */",
+            "export function resumeContinuityStep() {",
+            "  return 'resume continuity';",
+            "}",
+        ].join("\n"), "utf-8");
+        searchState.dbFileCandidates.set("How does /resume for the simple agent work, and when is in-memory glob data reused?", [resumeFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "How does /resume for the simple agent work, and when is in-memory glob data reused?",
+                explicitTargets: ["/resume"],
+                constraints: [],
+                primaryIntent: "Explain the resume command flow and continuity reuse.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: { query: "How does /resume for the simple agent work, and when is in-memory glob data reused?" },
+                reason: "Find likely implementation files first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: {
+                    path: resumeFile,
+                    target: "/resume",
+                },
+                reason: "Read the most relevant candidate file next.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Resume continuity implementation.",
+                relevanceExplanation: "This candidate contains the resume continuity logic named in the question.",
+                role: "primary",
+                excerpts: [{
+                        description: "Resume continuity export.",
+                        startLine: 4,
+                        endLine: 6,
+                        symbols: ["resumeContinuityStep"],
+                        code: "export function resumeContinuityStep() {\n  return 'resume continuity';\n}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The file read is enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "The resume continuity flow is handled in resumeContinuityStep.ts.",
+        });
+        const memory = createAgentMemory("How does /resume for the simple agent work, and when is in-memory glob data reused?", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.task.status).toBe("done");
+        expect(Object.keys(memory.evidence.fileReads)).toContain(resumeFile);
+        expect(memory.steps.find((step) => step.action === "read-file")).toMatchObject({
+            status: "done",
+        });
+        expect(memory.events.some((event) => event.type === "validation-failed")).toBe(false);
+    });
+    it("keeps reading ranked candidates until the model has enough evidence", async () => {
+        const loopFile = path.join(tempDir, "cli", "src", "agents", "agentLoop.ts");
+        const actionsFile = path.join(tempDir, "cli", "src", "agents", "agentActions.ts");
+        const stateFile = path.join(tempDir, "cli", "src", "agents", "agentStateMachine.ts");
+        fs.mkdirSync(path.dirname(loopFile), { recursive: true });
+        fs.writeFileSync(loopFile, "export function runAgentLoop() {}\n", "utf-8");
+        fs.writeFileSync(actionsFile, "export const buildActionMenu = () => [];\n", "utf-8");
+        fs.writeFileSync(stateFile, "export const startStep = () => {};\n", "utf-8");
+        searchState.dbFileCandidates.set("Explain how agentMemory, agentLoop, agentActions, and agentStateMachine divide responsibilities", [loopFile, actionsFile, stateFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Explain how agentMemory, agentLoop, agentActions, and agentStateMachine divide responsibilities",
+                queryScope: "multi-file",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Explain how the simple-agent parts divide responsibilities.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: {
+                    query: "Explain how agentMemory, agentLoop, agentActions, and agentStateMachine divide responsibilities",
+                },
+                reason: "Find likely source files first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: {
+                    target: loopFile,
+                },
+                reason: "Read the top-ranked candidate first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Loop coordinator file.",
+                relevanceExplanation: "This top-ranked candidate owns the loop execution part of the responsibilities question.",
+                role: "primary",
+                excerpts: [{
+                        description: "Loop export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["runAgentLoop"],
+                        code: "export function runAgentLoop() {}",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: {},
+                reason: "One read was not enough, so read the next ranked candidate.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Action menu file.",
+                relevanceExplanation: "This second candidate owns action construction and complements the loop file for the requested explanation.",
+                role: "supporting",
+                excerpts: [{
+                        description: "Action menu export.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["buildActionMenu"],
+                        code: "export const buildActionMenu = () => [];",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The grounded file reads are enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "agentLoop coordinates execution, agentActions normalizes and runs actions, and agentStateMachine owns transitions.",
+        });
+        const memory = createAgentMemory("Explain how agentMemory, agentLoop, agentActions, and agentStateMachine divide responsibilities", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.events.map((event) => event.type)).not.toContain("validation-failed");
+        expect(Object.keys(memory.evidence.fileReads)).toEqual(expect.arrayContaining([loopFile, actionsFile]));
+        expect(Object.keys(memory.evidence.fileReads)).not.toContain(stateFile);
+        expect(memory.task.status).toBe("done");
+        expect(memory.artifacts.finalAnswer).toContain("agentLoop coordinates execution");
+    });
+    it("uses triage-file before full reads on broad candidate sets", async () => {
+        const loopFile = path.join(tempDir, "cli", "src", "agents", "agentLoop.ts");
+        const actionsFile = path.join(tempDir, "cli", "src", "agents", "agentActions.ts");
+        const stateFile = path.join(tempDir, "cli", "src", "agents", "agentStateMachine.ts");
+        const policyFile = path.join(tempDir, "cli", "src", "agents", "agentPolicyState.ts");
+        fs.mkdirSync(path.dirname(loopFile), { recursive: true });
+        fs.writeFileSync(loopFile, "export function runAgentLoop() {}\n", "utf-8");
+        fs.writeFileSync(actionsFile, "export const buildActionMenu = () => [];\n", "utf-8");
+        fs.writeFileSync(stateFile, "export const startStep = () => {};\n", "utf-8");
+        fs.writeFileSync(policyFile, "export const resolvePolicyState = () => ({});\n", "utf-8");
+        searchState.dbFileCandidates.set("Explain how the modular agent chooses between triage-file and read-file", [loopFile, actionsFile, stateFile, policyFile]);
+        generateMock
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                normalizedQuery: "Explain how the modular agent chooses between triage-file and read-file",
+                queryScope: "multi-file",
+                explicitTargets: [],
+                constraints: [],
+                primaryIntent: "Explain read and triage decision ownership.",
+                alternativeIntents: [],
+                ambiguityFlags: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "search-db",
+                args: {
+                    query: "Explain how the modular agent chooses between triage-file and read-file",
+                },
+                reason: "Find likely source files first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "triage-file",
+                args: { target: loopFile },
+                reason: "Triage the strongest ranked candidate first.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "triage-file",
+                args: { target: actionsFile },
+                reason: "Triage one more top candidate before a full read.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "read-file",
+                args: { target: actionsFile },
+                reason: "The second triaged candidate now looks like the clearest owner.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                summary: "Action normalization and menu wiring.",
+                relevanceExplanation: "This file owns action contracts and shows how triage-file and read-file are surfaced to the runtime.",
+                role: "primary",
+                excerpts: [{
+                        description: "Action registration block.",
+                        startLine: 1,
+                        endLine: 1,
+                        symbols: ["buildActionMenu"],
+                        code: "export const buildActionMenu = () => [];",
+                    }],
+                risks: [],
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: JSON.stringify({
+                action: "final-answer",
+                args: {},
+                reason: "The promoted full read is enough to answer now.",
+            }),
+        })
+            .mockResolvedValueOnce({
+            data: "agentActions owns action contracts while policy decides when triage-file or read-file should run.",
+        });
+        const memory = createAgentMemory("Explain how the modular agent chooses between triage-file and read-file", tempDir, tempDir);
+        const ui = {
+            update: vi.fn(),
+            message: vi.fn(),
+            pause: vi.fn((fn) => fn()),
+            succeed: vi.fn(),
+            fail: vi.fn(),
+            stop: vi.fn(),
+        };
+        await runAgentLoop(memory, ui);
+        expect(memory.steps.map((step) => step.action)).toEqual([
+            "search-db",
+            "triage-file",
+            "triage-file",
+            "read-file",
+            "final-answer",
+        ]);
+        expect(Object.values(memory.evidence.fileReads).filter((read) => read.readMode === "triage").length).toBeGreaterThanOrEqual(1);
+        expect(Object.values(memory.evidence.fileReads).filter((read) => read.readMode === "full")).toHaveLength(1);
+        expect(memory.artifacts.finalAnswer).toContain("triage-file");
+    });
+});
+//# sourceMappingURL=agentLoop.test.js.map