@securecode-ai/mcp 0.5.5 → 0.5.7

package/dist/attack/agentScanLoop.js

@@ -19,93 +19,374 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAgentScan = runAgentScan;
+exports.isCoherentText = isCoherentText;
+exports.estimateTranscriptSize = estimateTranscriptSize;
+exports.compactTranscript = compactTranscript;
+exports.compactTranscriptAggressive = compactTranscriptAggressive;
+exports.sanitizeFindings = sanitizeFindings;
 const client_1 = require("../api/client");
 const agentScanExecutor_1 = require("./agentScanExecutor");
+const agentTrace_1 = require("./agentTrace");
+const investigationState_1 = require("./investigationState");
+const investigationProfiles_1 = require("./investigationProfiles");
+const architectureContext_1 = require("../project-map/architectureContext");
+const endpointDiscovery_1 = require("../project-map/endpointDiscovery");
+const implementationResolver_1 = require("../project-map/implementationResolver");
+const searchIntent_1 = require("./searchIntent");
+const scanState_1 = require("./scanState");
+const evidenceLedger_1 = require("./evidenceLedger");
+const workItem_1 = require("./workItem");
+const handlerInventory_1 = require("../project-map/handlerInventory");
+const candidateStore_1 = require("./candidateStore");
+const scanScheduler_1 = require("./scanScheduler");
+const finishGate_1 = require("./finishGate");
+const qualityMetrics_1 = require("./qualityMetrics");
+const agentScanExecutor_2 = require("./agentScanExecutor");
+const protocolValidator_1 = require("./protocolValidator");
 const agentScanProtocol_1 = require("./agentScanProtocol");
 async function runAgentScan(ctx, target, options = {}) {
     const client = new client_1.ApiClient({ baseUrl: ctx.apiUrl, token: ctx.apiToken });
     const budget = {
-        stepsRemaining: options.budget?.stepsRemaining ?? agentScanProtocol_1.AGENT_SCAN_DEFAULTS.maxSteps,
+        stepsRemaining: options.budget?.stepsRemaining ?? agentScanProtocol_1.AGENT_SCAN_DEFAULTS.initialSteps,
         costSpentUsd: options.budget?.costSpentUsd ?? 0,
         costCapUsd: options.budget?.costCapUsd ?? agentScanProtocol_1.AGENT_SCAN_DEFAULTS.costCapUsd,
+        stepsGranted: options.budget?.stepsGranted ?? agentScanProtocol_1.AGENT_SCAN_DEFAULTS.initialSteps,
+        hardMaxSteps: options.budget?.hardMaxSteps ?? agentScanProtocol_1.AGENT_SCAN_DEFAULTS.hardMaxSteps,
+        extensionsGranted: options.budget?.extensionsGranted ?? 0,
     };
     const startTime = Date.now();
     const wallClockMs = agentScanProtocol_1.AGENT_SCAN_DEFAULTS.wallClockMs;
     let stepsTaken = 0;
     let costSpentUsd = 0;
+    let stepsGranted = budget.stepsGranted;
+    let extensionsGranted = budget.extensionsGranted;
+    let meaningfulProgressSinceLastExtension = false;
     try {
-        const startResp = await client.postJson('/agent/scan/start', {}, options.signal);
+        const startRespRaw = await client.postJson('/agent/scan/start', {}, options.signal);
+        const startValidation = (0, protocolValidator_1.validateStartResponse)(startRespRaw);
+        if (!startValidation.ok) {
+            return {
+                status: 'spawn_failed',
+                findings: [],
+                transcript: [],
+                stepsUsed: 0,
+                stepsGranted: agentScanProtocol_1.AGENT_SCAN_DEFAULTS.initialSteps,
+                extensionsGranted: 0,
+                costSpentUsd: 0,
+                terminationReason: 'api_error',
+                error: `API returned an invalid start response: ${startValidation.error}`,
+                investigationNotes: [],
+                coverageGaps: [],
+            };
+        }
+        const startResp = startValidation.value;
+        const trace = new agentTrace_1.AgentTraceLogger(ctx.workspaceRoot, startResp.runId);
+        trace.logRunStarted();
+        // Authoritative scan state — the single source of truth for phase,
+        // budget, recovery, and lifecycle. Local counters below are kept in
+        // sync with this state until they are fully replaced.
+        const scanState = (0, scanState_1.createScanRunState)(startResp.runId, target, budget);
+        scanState.budget.wallClockMs = wallClockMs;
+        const qualityTracker = new qualityMetrics_1.QualityMetricsTracker();
         const transcript = [];
+        const investigationState = new investigationState_1.InvestigationState();
+        // Select a target-specific investigation profile to set the required
+        // checklist steps. This prevents the agent from wasting steps on
+        // irrelevant tools (e.g., get_endpoints on a utility file) and ensures
+        // required steps for the target type are not skipped.
+        const profile = (0, investigationProfiles_1.selectInvestigationProfile)({
+            filePath: target.filePath,
+            architectureContext: target.architectureContext,
+            endpointContext: target.endpointContext,
+        });
+        investigationState.setRequiredSteps(profile.requiredSteps);
+        scanState.profileId = profile.name;
+        // Implementation resolution: if the target file looks like a
+        // contract-only file (interface, type declaration, abstract class),
+        // resolve the actual implementation so the investigation can follow
+        // the real code, not just signatures.
+        let implementationResolution = null;
+        try {
+            const fs = require('fs');
+            const absPath = require('path').resolve(ctx.workspaceRoot, target.filePath);
+            const content = fs.existsSync(absPath) ? fs.readFileSync(absPath, 'utf8') : '';
+            if (content && (0, implementationResolver_1.looksLikeContractOnly)(content)) {
+                const symbol = target.filePath.replace(/\.ts$/, '').replace(/.*\//, '');
+                const resolution = await (0, implementationResolver_1.resolveImplementation)(ctx.workspaceRoot, target.filePath, symbol);
+                if (!resolution.unresolved && resolution.implementationLocations.length > 0) {
+                    implementationResolution = (0, implementationResolver_1.formatImplementationResolution)(resolution);
+                    target.implementationHint = implementationResolution;
+                }
+            }
+        }
+        catch { /* best-effort */ }
+        // Control plane infrastructure — evidence ledger, work items, handler
+        // inventory, candidate store, and scheduler work together to ensure
+        // the investigation is complete before finish is accepted.
+        const evidenceLedger = new evidenceLedger_1.EvidenceLedger();
+        evidenceLedger.addRequirements(profile.requirements);
+        const workItemQueue = new workItem_1.WorkItemQueue();
+        // Note: profile requirements are tracked by the evidence ledger and
+        // checklist, not as work items. Work items are for architecture-risk
+        // tasks, handler reviews, and implementation reviews — structured
+        // work that the scheduler can prioritize and attempt-count.
+        const handlerInventory = new handlerInventory_1.HandlerInventory();
+        const candidateStore = new candidateStore_1.CandidateStore();
+        // Convert architecture risks relevant to this target into tracked
+        // investigation tasks. Unresolved tasks will appear as coverage gaps.
+        const archTasks = (0, architectureContext_1.createInvestigationTasksFromRisks)(target.architectureContext, target.filePath);
+        investigationState.addInvestigationTasks(archTasks);
+        // Create work items for architecture-risk tasks so the scheduler
+        // can prioritize them and suggest deterministic actions.
+        for (const task of archTasks) {
+            const requirements = [];
+            if (task.requiredProofDimensions?.includes('source') || task.requiredProofDimensions?.includes('reachability')) {
+                requirements.push({
+                    id: `${task.id}-req-source`,
+                    description: 'Trace the code path from input to the sensitive operation',
+                    acceptedKinds: ['source-range', 'cross-file-flow'],
+                    targetFiles: task.targetFiles,
+                    requiredTools: ['read_file', 'trace_flow_cross_file', 'trace_flow'],
+                    minimumCount: 1,
+                });
+            }
+            if (task.requiredProofDimensions?.includes('control')) {
+                requirements.push({
+                    id: `${task.id}-req-control`,
+                    description: 'Determine whether the control is present, bypassed, or missing',
+                    acceptedKinds: ['guard-result', 'policy-result', 'config-result'],
+                    targetFiles: task.targetFiles,
+                    requiredTools: ['check_guard', 'check_policy', 'read_config'],
+                    minimumCount: 1,
+                    acceptsNegative: true,
+                });
+            }
+            if (task.requiredProofDimensions?.includes('threat-model')) {
+                requirements.push({
+                    id: `${task.id}-req-threat-model`,
+                    description: 'Establish the threat model (is the attacker in scope?)',
+                    acceptedKinds: ['threat-model-result', 'config-result', 'source-range'],
+                    targetFiles: task.targetFiles,
+                    requiredTools: ['read_config', 'read_file', 'search_code'],
+                    minimumCount: 1,
+                    acceptsNegative: true,
+                });
+            }
+            if (task.requiredProofDimensions?.includes('impact')) {
+                requirements.push({
+                    id: `${task.id}-req-impact`,
+                    description: 'Verify the impact: trace to the actual sensitive sink and confirm reachability',
+                    acceptedKinds: ['cross-file-flow', 'capability-result', 'source-range'],
+                    targetFiles: task.targetFiles,
+                    requiredTools: ['trace_flow_cross_file', 'trace_flow'],
+                    minimumCount: 1,
+                });
+            }
+            if (task.requiredProofDimensions?.includes('verification')) {
+                requirements.push({
+                    id: `${task.id}-req-verification`,
+                    description: 'Verify the vulnerability with a test or exploit proof',
+                    acceptedKinds: ['test-location', 'test-result', 'proof-result'],
+                    targetFiles: task.targetFiles,
+                    requiredTools: ['find_tests', 'run_tests'],
+                    minimumCount: 1,
+                    acceptsNegative: true,
+                });
+            }
+            if (requirements.length === 0) {
+                requirements.push({
+                    id: `${task.id}-req-0`,
+                    description: task.requiredEvidence[0] || 'Investigate the risk',
+                    acceptedKinds: ['source-range', 'cross-file-flow', 'policy-result'],
+                    minimumCount: 1,
+                });
+            }
+            workItemQueue.add((0, workItem_1.createArchitectureRiskWorkItem)(task.claim, task.targetFiles, requirements));
+        }
         const readFiles = new Set();
         const readFileCounts = new Map();
+        // Pre-compute function boundaries for chunk alignment
+        let functionBoundaries;
+        try {
+            const fb = await (0, agentScanExecutor_2.extractFunctionBoundaries)(target.fileContent, target.filePath);
+            if (fb)
+                functionBoundaries = fb;
+        }
+        catch { /* best-effort */ }
         // Dynamic read cap based on file size:
         //   < 200 lines  → 5 reads (small file, 5 chunks is enough)
-        //   < 1000 lines  → 10 reads (medium file)
-        //   < 5000 lines  → 20 reads (large file, needs many sections)
-        //   >= 5000 lines → 30 reads (very large, allow thorough coverage)
+        //   < 1000 lines  → 8 reads (medium file)
+        //   < 5000 lines  → 12 reads (large file — use search_code/trace_flow, not brute reading)
+        //   >= 5000 lines → 15 reads (very large — still capped; the agent must use
+        //                  search_code and trace_flow for pattern discovery, not
+        //                  read the entire file section by section)
         function maxReadsForFile(filePath) {
             try {
                 const fs = require('fs');
                 const abs = require('path').resolve(ctx.workspaceRoot, filePath);
                 const stat = fs.statSync(abs);
                 if (stat.size > 200_000)
-                    return 30;
+                    return 15;
                 const content = fs.readFileSync(abs, 'utf8');
                 const lines = content.split('\n').length;
                 if (lines < 200)
                     return 5;
                 if (lines < 1000)
-                    return 10;
+                    return 8;
                 if (lines < 5000)
-                    return 20;
-                return 30;
+                    return 12;
+                return 15;
             }
             catch {
-                return 10;
+                return 8;
             }
         }
         // Track non-read tool calls to prevent the agent from looping on the
         // same search_code/trace_flow call repeatedly. Keyed by (type + args).
         const toolCallCounts = new Map();
         const MAX_SAME_TOOL_CALL = 2;
+        // Track normalized search patterns to detect equivalent searches
+        // (same terms, different order) that the raw toolKey dedup misses.
+        const searchedPatterns = new Set();
+        let equivalentSearchCount = 0;
         let consecutiveErrors = 0;
         let consecutiveBlockedReads = 0;
+        let meaningfulProgressSinceRecovery = true;
+        let aggressiveCompaction = false;
         while (true) {
             // Wall clock check
             if (Date.now() - startTime > wallClockMs) {
+                (0, scanState_1.terminateScan)(scanState, 'wall_clock', `Wall clock limit (${wallClockMs}ms) exceeded.`);
                 return {
                     status: 'capped',
                     findings: [],
                     transcript,
                     stepsUsed: stepsTaken,
+                    stepsGranted,
+                    extensionsGranted,
                     costSpentUsd,
+                    terminationReason: 'wall_clock',
                     summary: `Wall clock limit (${wallClockMs}ms) exceeded.`,
+                    investigationNotes: [],
+                    coverageGaps: [],
                 };
             }
             // Abort check
             if (options.signal?.aborted) {
+                (0, scanState_1.terminateScan)(scanState, 'cancelled', 'Cancelled by user.');
                 return {
                     status: 'cancelled',
                     findings: [],
                     transcript,
                     stepsUsed: stepsTaken,
+                    stepsGranted,
+                    extensionsGranted,
                     costSpentUsd,
+                    terminationReason: 'cancelled',
                     summary: 'Cancelled by user.',
+                    investigationNotes: [],
+                    coverageGaps: [],
                 };
             }
+            // Build action constraint for blocked-read recovery.
+            //   0-1 blocked reads: normal (no constraint)
+            //   2 blocked reads: recovery mode — if unread ranges exist,
+            //     require the next unread range; if no unread ranges remain,
+            //     forbid read_file entirely and require an analysis tool.
+            //   3 blocked reads: MCP selects a deterministic recovery action (skip API)
+            let actionConstraint;
+            if (consecutiveBlockedReads >= 2 && consecutiveBlockedReads < 3) {
+                const nextRange = target.fileContent
+                    ? investigationState.getPrioritizedUnreadRange(target.filePath, target.fileContent)
+                    : investigationState.getNextUnreadRange(target.filePath);
+                if (nextRange) {
+                    actionConstraint = {
+                        mode: 'recovery',
+                        requiredAction: {
+                            type: 'read_file',
+                            path: target.filePath,
+                            startLine: nextRange.start,
+                            endLine: nextRange.end,
+                            rationale: `Read next unread range: lines ${nextRange.start}-${nextRange.end}`,
+                        },
+                        reason: `You have been blocked by duplicate/overlapping reads. Read the next unread range: lines ${nextRange.start}-${nextRange.end}, or use an analysis tool (trace_flow, check_guard, check_policy).`,
+                    };
+                }
+                else {
+                    const recoveryAction = investigationState.getRecommendedRecoveryAction();
+                    actionConstraint = {
+                        mode: 'recovery',
+                        forbiddenActions: ['read_file'],
+                        requiredAction: recoveryAction || undefined,
+                        reason: 'You have been blocked by duplicate/overlapping reads and no unread ranges remain. Switch to an analysis tool.',
+                    };
+                }
+            }
+            const compactedTranscript = aggressiveCompaction
+                ? compactTranscriptAggressive(transcript)
+                : compactTranscript(transcript);
             const stepReq = {
                 runId: startResp.runId,
                 target,
-                transcript,
+                transcript: compactedTranscript,
                 budget: {
                     stepsRemaining: budget.stepsRemaining,
                     costSpentUsd,
                     costCapUsd: budget.costCapUsd,
+                    stepsGranted,
+                    hardMaxSteps: budget.hardMaxSteps,
+                    extensionsGranted,
+                },
+                clientCapabilities: (0, agentScanProtocol_1.defaultClientCapabilities)(),
+                investigationProgress: {
+                    completedSteps: investigationState.getCompletedSteps(),
+                    incompleteSteps: investigationState.getIncompleteSteps(),
+                    consecutiveBlockedReads,
+                    meaningfulProgressSinceLastExtension,
                 },
+                actionConstraint,
             };
             let stepResp;
             try {
-                stepResp = await client.postJson('/agent/scan/step', stepReq, options.signal);
+                const stepRespRaw = await client.postJson('/agent/scan/step', stepReq, options.signal);
+                const stepValidation = (0, protocolValidator_1.validateStepResponse)(stepRespRaw);
+                if (!stepValidation.ok) {
+                    // Wire-level malformed response. Don't execute the
+                    // potentially-dangerous `next` action; treat it as a
+                    // controlled error so the agent can retry against a
+                    // well-formed response on the next call.
+                    const vErr = stepValidation.error;
+                    console.warn(`[Agent Scan Loop] Step ${stepsTaken + 1} returned a malformed response: ${vErr}`);
+                    consecutiveErrors++;
+                    stepsTaken++;
+                    budget.stepsRemaining--;
+                    const errMsg = `API returned a malformed step response: ${vErr}`;
+                    transcript.push({
+                        action: {
+                            type: 'system_event',
+                            eventType: 'error',
+                            message: errMsg,
+                        },
+                        observation: errMsg,
+                    });
+                    if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
+                        return {
+                            status: 'capped',
+                            findings: [],
+                            transcript,
+                            stepsUsed: stepsTaken,
+                            stepsGranted,
+                            extensionsGranted,
+                            costSpentUsd,
+                            terminationReason: 'api_error',
+                            summary: `Step budget exhausted after ${consecutiveErrors} consecutive malformed API responses. Last error: ${vErr}`,
+                            investigationNotes: [],
+                            coverageGaps: [],
+                        };
+                    }
+                    continue;
+                }
+                stepResp = stepValidation.value;
             }
             catch (stepErr) {
                 const errMsg = stepErr?.message || String(stepErr);
@@ -119,8 +400,13 @@ async function runAgentScan(ctx, target, options = {}) {
                         findings: [],
                         transcript,
                         stepsUsed: stepsTaken,
+                        stepsGranted,
+                        extensionsGranted,
                         costSpentUsd,
+                        terminationReason: 'api_error',
                         error: 'API server restarted mid-scan — the run was lost. Please retry the scan.',
+                        investigationNotes: [],
+                        coverageGaps: [],
                     };
                 }
                 // Detect abort — the user cancelled. Don't treat as error.
@@ -130,26 +416,38 @@ async function runAgentScan(ctx, target, options = {}) {
                         findings: [],
                         transcript,
                         stepsUsed: stepsTaken,
+                        stepsGranted,
+                        extensionsGranted,
                         costSpentUsd,
+                        terminationReason: 'cancelled',
                         summary: 'Cancelled by user.',
+                        investigationNotes: [],
+                        coverageGaps: [],
                     };
                 }
+                // Detect timeout / network errors — retry once with aggressive compaction
+                if (!aggressiveCompaction && /timeout|ETIMEDOUT|ESOCKETTIMEDOUT|socket hang up|ECONNRESET|fetch failed/i.test(errMsg)) {
+                    console.warn(`[Agent Scan Loop] Step ${stepsTaken + 1} timeout/network error — retrying with aggressive compaction: ${errMsg}`);
+                    aggressiveCompaction = true;
+                    continue;
+                }
                 // The API rejected the action (malformed, missing field, etc).
-                // Add the error to the transcript so the LLM sees it on the
-                // next step and can correct itself. Then retry — don't waste
-                // the step silently.
+                // Add a first-class system_event to the transcript so the LLM
+                // sees the error on the next step and can correct itself.
+                // Previously this piggybacked on `read_file('__ERROR__')`,
+                // which the executor would have tried to open and failed.
                 console.warn(`[Agent Scan Loop] Step ${stepsTaken + 1} error: ${errMsg}`);
                 consecutiveErrors++;
                 stepsTaken++;
                 budget.stepsRemaining--;
-                // Push the error into the transcript so the LLM sees it
+                const errorMsg = `ERROR: Your previous action was rejected: ${errMsg}. Please try a DIFFERENT action with ALL required fields. Set unused fields to null.`;
                 transcript.push({
                     action: {
-                        type: 'read_file',
-                        path: '__ERROR__',
-                        rationale: 'Previous action was invalid',
+                        type: 'system_event',
+                        eventType: 'error',
+                        message: errorMsg,
                     },
-                    observation: `ERROR: Your previous action was rejected: ${errMsg}. Please try a DIFFERENT action with ALL required fields. Set unused fields to null.`,
+                    observation: errorMsg,
                 });
                 if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
                     return {
@@ -157,74 +455,367 @@ async function runAgentScan(ctx, target, options = {}) {
                         findings: [],
                         transcript,
                         stepsUsed: stepsTaken,
+                        stepsGranted,
+                        extensionsGranted,
                         costSpentUsd,
+                        terminationReason: 'api_error',
                         summary: `Step budget exhausted after ${consecutiveErrors} consecutive API errors. Last error: ${errMsg}`,
+                        investigationNotes: [],
+                        coverageGaps: [],
                     };
                 }
                 continue;
             }
             costSpentUsd += stepResp.costUsd || 0;
+            scanState.budget.costSpentUsd = costSpentUsd;
             consecutiveErrors = 0;
+            trace.logStepRequested(stepResp.model, stepResp.tokens, stepResp.costUsd, stepResp.latencyMs);
+            // Transition from planning to surveying on first successful step
+            if (scanState.phase === 'planning') {
+                (0, scanState_1.transitionScanPhase)(scanState, 'surveying', 'first step received');
+            }
+            // Budget extension — the API may grant additional steps when the
+            // agent demonstrates meaningful progress. Update our local tracking.
+            if (stepResp.budgetExtension) {
+                const ext = stepResp.budgetExtension;
+                stepsGranted = ext.totalGranted;
+                extensionsGranted = ext.granted > 0 ? extensionsGranted + 1 : extensionsGranted;
+                budget.stepsRemaining = stepResp.stepsRemaining;
+                budget.stepsGranted = ext.totalGranted;
+                budget.extensionsGranted = extensionsGranted;
+                scanState.budget.stepsGranted = ext.totalGranted;
+                scanState.budget.extensionsGranted = extensionsGranted;
+                scanState.budget.stepsRemaining = stepResp.stepsRemaining;
+                meaningfulProgressSinceLastExtension = false;
+                if (options.onProgress) {
+                    options.onProgress(stepsTaken, ext.hardMaxSteps, `Budget extended +${ext.granted} steps (${ext.totalGranted}/${ext.hardMaxSteps}): ${ext.reason}`);
+                }
+            }
+            // System event (e.g., critique from the senior reviewer) — append
+            // to the transcript WITHOUT executing it, then continue the loop
+            // so the next step's prompt sees the event and re-plans. This
+            // replaces the previous `read_file('__CRITIQUE__')` pattern that
+            // lost the critique content over the wire.
+            if (stepResp.systemEvent) {
+                const ev = stepResp.systemEvent;
+                if (ev.eventType === 'critique')
+                    qualityTracker.recordCritique();
+                if (ev.eventType === 'finish_gate')
+                    qualityTracker.recordFinishGate();
+                transcript.push({
+                    action: ev,
+                    observation: ev.message,
+                });
+                stepsTaken++;
+                budget.stepsRemaining = stepResp.stepsRemaining;
+                if (options.onProgress) {
+                    options.onProgress(stepsTaken, stepsGranted, `Step ${stepsTaken}: system_event(${ev.eventType})`);
+                }
+                // Re-loop: ask the API for the next action now that the
+                // critique is in the transcript. The agent will see the
+                // critique in the next step's prompt and either re-investigate
+                // or call finish again with an updated selfCritique.
+                continue;
+            }
             // Null next = done (cost capped or steps exhausted)
             if (!stepResp.next) {
                 const status = stepResp.costCapped
                     ? 'capped'
                     : (stepResp.degraded ? 'degraded' : 'completed');
+                trace.logRunCompleted(status);
                 return {
                     status,
                     findings: [],
                     transcript,
                     stepsUsed: stepsTaken,
+                    stepsGranted,
+                    extensionsGranted,
                     costSpentUsd,
+                    terminationReason: stepResp.costCapped ? 'cost_cap' : 'budget_exhausted',
                     summary: stepResp.costCapped
                         ? `Cost cap ($${budget.costCapUsd.toFixed(2)}) reached.`
                         : 'Agent completed without explicit finish.',
+                    investigationNotes: [],
+                    coverageGaps: [],
                 };
             }
             const action = stepResp.next;
             stepsTaken++;
             budget.stepsRemaining = stepResp.stepsRemaining;
+            scanState.budget.stepsUsed = stepsTaken;
+            scanState.budget.stepsRemaining = stepResp.stepsRemaining;
+            trace.nextStep();
+            trace.logActionSelected(action.type, stepResp.model, stepResp.degraded || stepResp.fallbackFired);
             // Progress callback
             if (options.onProgress) {
                 const actionDesc = describeAction(action);
-                options.onProgress(stepsTaken, agentScanProtocol_1.AGENT_SCAN_DEFAULTS.maxSteps, `Step ${stepsTaken}: ${actionDesc}`);
+                options.onProgress(stepsTaken, stepsGranted, `Step ${stepsTaken}: ${actionDesc}`);
             }
             // Finish = done with findings
             if (action.type === 'finish') {
-                return {
-                    status: 'completed',
-                    findings: action.findings,
-                    transcript,
-                    stepsUsed: stepsTaken,
-                    costSpentUsd,
-                    summary: action.summary,
-                };
+                scanState.finishAttempts++;
+                qualityTracker.recordFinishAttempt();
+                // Register candidates from findings — each finding becomes a
+                // tracked candidate. If the candidate is new (discovered), the
+                // finish gate will reject and the agent must gather evidence.
+                for (const finding of action.findings) {
+                    const rootCauseId = finding.rootCause?.rootCauseId || `${finding.type}:${finding.line}`;
+                    const existing = candidateStore.getCandidatesByRootCause(rootCauseId);
+                    if (existing.length === 0) {
+                        const candidateId = candidateStore.register({
+                            rootCauseId,
+                            type: finding.type,
+                            severity: finding.severity,
+                            locations: [{ filePath: target.filePath, line: finding.line }],
+                            claim: finding.why,
+                            requiredEvidence: [
+                                {
+                                    id: `${rootCauseId}-flow`,
+                                    description: 'Verify data flow to the vulnerable location',
+                                    acceptedKinds: ['cross-file-flow'],
+                                    targetFiles: [target.filePath],
+                                    requiredTools: ['trace_flow_cross_file', 'trace_flow'],
+                                    minimumCount: 1,
+                                },
+                                {
+                                    id: `${rootCauseId}-guard`,
+                                    description: 'Check for guards/controls on the vulnerable location',
+                                    acceptedKinds: ['guard-result', 'policy-result'],
+                                    targetFiles: [target.filePath],
+                                    requiredTools: ['check_guard', 'check_policy'],
+                                    minimumCount: 1,
+                                },
+                            ],
+                        });
+                        // Backfill evidence: scan the transcript for prior
+                        // verification actions on this candidate's location.
+                        // If the agent already ran trace_flow/check_guard on
+                        // the file before calling finish, credit that evidence.
+                        const targetFileNorm = target.filePath.replace(/\\/g, '/').toLowerCase();
+                        const verificationActions = new Set([
+                            'trace_flow', 'trace_flow_cross_file', 'check_guard', 'check_policy',
+                        ]);
+                        for (const step of transcript) {
+                            if (verificationActions.has(step.action.type)) {
+                                const stepFile = step.action.filePath || step.action.path || target.filePath;
+                                const stepFileNorm = String(stepFile).replace(/\\/g, '/').toLowerCase();
+                                if (stepFileNorm === targetFileNorm) {
+                                    const cat = step.action.type === 'trace_flow' || step.action.type === 'trace_flow_cross_file' ? 'flow'
+                                        : step.action.type === 'check_guard' ? 'guard'
+                                            : step.action.type === 'check_policy' ? 'policy'
+                                                : undefined;
+                                    const dim = step.action.type === 'trace_flow' || step.action.type === 'trace_flow_cross_file' ? 'reachability'
+                                        : step.action.type === 'check_guard' || step.action.type === 'check_policy' ? 'control'
+                                            : undefined;
+                                    candidateStore.addEvidence(candidateId, `backfill:${step.action.type}:${stepFileNorm}`, cat, dim);
+                                }
+                            }
+                            if (step.action.type === 'read_file') {
+                                const stepFile = step.action.path || target.filePath;
+                                const stepFileNorm = String(stepFile).replace(/\\/g, '/').toLowerCase();
+                                if (stepFileNorm === targetFileNorm) {
+                                    candidateStore.addEvidence(candidateId, `backfill:source:${stepFileNorm}`, 'source', 'source');
+                                }
+                            }
+                            if (step.action.type === 'read_config') {
+                                const stepFile = target.filePath;
+                                const stepFileNorm = stepFile.replace(/\\/g, '/').toLowerCase();
+                                candidateStore.addEvidence(candidateId, `backfill:config:${stepFileNorm}`, undefined, 'threat-model');
+                            }
+                        }
+                    }
+                }
+                // Evaluate the finish proposal through the hard finish gate
+                const schedDecision = (0, scanScheduler_1.schedule)({
+                    state: scanState,
+                    evidence: evidenceLedger,
+                    workItems: workItemQueue,
+                    handlers: handlerInventory,
+                    candidates: candidateStore,
+                    investigation: investigationState,
+                    target,
+                    functionBoundaries,
+                });
+                const gateResult = (0, finishGate_1.evaluateFinishGate)({
+                    proposal: action,
+                    state: scanState,
+                    evidence: evidenceLedger,
+                    workItems: workItemQueue,
+                    handlers: handlerInventory,
+                    candidates: candidateStore,
+                    investigation: investigationState,
+                    scheduler: schedDecision,
+                    target: { filePath: target.filePath, fileContent: target.fileContent },
+                });
+                if (gateResult.accepted) {
+                    trace.logRunCompleted('completed');
+                    if (gateResult.mode === 'forced-incomplete') {
+                        (0, scanState_1.terminateScan)(scanState, 'forced_incomplete', 'Budget exhausted with incomplete investigation');
+                        qualityTracker.recordForcedTermination('forced_incomplete');
+                    }
+                    else {
+                        (0, scanState_1.terminateScan)(scanState, 'agent_finish', gateResult.normalizedFinish?.summary);
+                        qualityTracker.recordTermination('agent_finish');
+                    }
+                    // Merge gate-generated coverage gaps with model-provided gaps
+                    let coverageGaps = action.coverageGaps ?? [];
+                    if (gateResult.coverageGaps) {
+                        coverageGaps = [...coverageGaps, ...gateResult.coverageGaps];
+                    }
+                    const covSummary = investigationState.getCoverageSummary(target.filePath);
+                    qualityTracker.recordCoverage(covSummary.totalLines, covSummary.coveredLines, covSummary.uncoveredRangeCount, covSummary.largestUncoveredRange);
+                    qualityTracker.recordBudget(stepsTaken, stepsGranted, extensionsGranted, costSpentUsd, budget.costCapUsd, wallClockMs, Date.now() - startTime);
+                    const investigationNotes = [...(action.investigationNotes ?? [])];
+                    for (const candidate of candidateStore.getActive()) {
+                        if (candidate.status === 'discovered' || candidate.status === 'investigating' || candidate.status === 'supported') {
+                            const missingDims = candidate.requiredProofDimensions?.filter(d => !candidate.satisfiedDimensions?.includes(d)) || [];
+                            investigationNotes.push({
+                                title: candidate.claim,
+                                detail: `Candidate was not fully verified. Status: ${candidate.status}. Missing proof dimensions: ${missingDims.join(', ') || 'none'}. Evidence refs: ${candidate.evidenceRefs.length}.`,
+                                file: candidate.locations[0]?.filePath || target.filePath,
+                                line: candidate.locations[0]?.line,
+                                verificationLevel: 'logic-confirmed',
+                                rootCauseId: candidate.rootCauseId,
+                                requiredEvidence: missingDims.map(d => `Satisfy the ${d} proof dimension`),
+                                priority: candidate.severity === 'critical' || candidate.severity === 'high' ? 'high' : 'medium',
+                            });
+                            candidateStore.setUnproven(candidate.id, `Converted to note: missing proof dimensions ${missingDims.join(', ')}`);
+                        }
+                    }
+                    return {
+                        status: 'completed',
+                        findings: sanitizeFindings(action.findings),
+                        investigationNotes,
+                        coverageGaps,
+                        transcript,
+                        stepsUsed: stepsTaken,
+                        stepsGranted,
+                        extensionsGranted,
+                        costSpentUsd,
+                        terminationReason: gateResult.mode === 'forced-incomplete' ? 'forced_incomplete' : 'agent_finish',
+                        summary: action.summary,
+                        qualityMetrics: qualityTracker.getMetrics(),
+                    };
+                }
+                // Finish rejected — continue investigation
+                trace.logToolBlocked('finish', `Finish rejected: ${gateResult.reasons.map(r => r.description).join('; ')}`);
+                qualityTracker.recordFinishRejection();
+                // Add a system event so the model sees the rejection
+                const rejectionMessage = `FINISH REJECTED — your investigation is incomplete:\n${gateResult.reasons.map(r => `  - ${r.description}`).join('\n')}\n\nYou must complete the remaining investigation steps before calling finish.${gateResult.recoveryAction ? `\n\nYour next action MUST be: ${gateResult.recoveryAction.type}` : ''}`;
+                transcript.push({
+                    action: {
+                        type: 'system_event',
+                        eventType: 'finish_rejected',
+                        message: rejectionMessage,
+                    },
+                    observation: rejectionMessage,
+                });
+                // Execute the recovery action if the scheduler has one
+                if (gateResult.recoveryAction) {
+                    const recoveryAction = gateResult.recoveryAction;
+                    stepsTaken++;
+                    budget.stepsRemaining--;
+                    scanState.budget.stepsUsed = stepsTaken;
+                    scanState.budget.stepsRemaining = budget.stepsRemaining;
+                    trace.nextStep();
+                    trace.logActionSelected(recoveryAction.type, 'finish-gate-recovery', false);
+                    if (options.onProgress) {
+                        options.onProgress(stepsTaken, stepsGranted, `Step ${stepsTaken}: finish-gate recovery: ${describeAction(recoveryAction)}`);
+                    }
+                    let recoveryObservation;
+                    if (recoveryAction.type === 'read_file') {
+                        const readResult = await (0, agentScanExecutor_1.executeReadFileAction)(recoveryAction, ctx);
+                        recoveryObservation = readResult.observation;
+                        if (readResult.totalLines > 0) {
+                            investigationState.recordActualRead(recoveryAction.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
+                        }
+                    }
+                    else {
+                        recoveryObservation = await (0, agentScanExecutor_1.executeAction)(recoveryAction, ctx, startResp.runId, client, target);
+                    }
+                    qualityTracker.recordToolUse(recoveryAction.type);
+                    investigationState.recordToolUse(recoveryAction.type);
+                    trace.logToolCompleted(recoveryAction.type, recoveryObservation);
+                    transcript.push({ action: recoveryAction, observation: `[FINISH GATE RECOVERY] ${recoveryObservation}` });
+                }
+                continue;
+            }
+            // Sync candidates-verified: when all candidates are ready for the
+            // Juror (supported or terminal) or there are none, the
+            // candidates-verified step is complete.
+            if (candidateStore.allReadyForJuror()) {
+                investigationState.markCandidatesVerified();
             }
             // Execute the action locally
             let observation;
             let wasBlocked = false;
+            let flowResult = null;
+            // Reset progress flag — only set to true when actual progress is made
+            meaningfulProgressSinceRecovery = false;
             if (action.type === 'read_file') {
                 const normalizedPath = action.path.replace(/\\/g, '/').toLowerCase();
-                // Track by (path, startLine, endLine) — allow re-reading with different ranges
-                const rangeKey = `${normalizedPath}:${action.startLine || 0}:${action.endLine || 0}`;
-                if (readFiles.has(rangeKey)) {
-                    observation = `File "${action.path}" (lines ${action.startLine || 'all'}-${action.endLine || 'all'}) was already read. The content is in the transcript above. Use a DIFFERENT line range or a different tool.`;
+                let totalLines;
+                try {
+                    const fs = require('fs');
+                    const abs = require('path').resolve(ctx.workspaceRoot, action.path);
+                    const content = fs.readFileSync(abs, 'utf8');
+                    totalLines = content.split('\n').length;
+                }
+                catch { /* best-effort */ }
+                const readValue = investigationState.classifyRead(action.path, action.startLine, action.endLine, totalLines);
+                const checklist = investigationState.formatChecklistForPrompt();
+                const fileMax = maxReadsForFile(action.path);
+                const count = investigationState.getReadCount(action.path);
+                if (readValue.classification === 'duplicate') {
+                    qualityTracker.recordRead('duplicate', false);
+                    investigationState.recordBlockedRead(action.path);
+                    const nextHint = readValue.nextUnreadRange
+                        ? `\nNext unread range: lines ${readValue.nextUnreadRange.start}-${readValue.nextUnreadRange.end}. Use read_file with startLine=${readValue.nextUnreadRange.start} and endLine=${readValue.nextUnreadRange.end}.`
+                        : '';
+                    observation = `BLOCKED: Lines ${action.startLine || 'all'}-${action.endLine || 'all'} of "${action.path}" were already read. The content is in the transcript above.${nextHint}\n\n${checklist}`;
+                    wasBlocked = true;
+                }
+                else if (readValue.classification === 'high-overlap') {
+                    qualityTracker.recordRead('high-overlap', false);
+                    investigationState.recordBlockedRead(action.path);
+                    const nextHint = readValue.nextUnreadRange
+                        ? `\nNext unread range: lines ${readValue.nextUnreadRange.start}-${readValue.nextUnreadRange.end}. Use read_file with startLine=${readValue.nextUnreadRange.start} and endLine=${readValue.nextUnreadRange.end}.`
+                        : '';
+                    observation = `BLOCKED: Lines ${action.startLine || 1}-${action.endLine || totalLines || '?'} of "${action.path}" substantially overlap already-read ranges (${readValue.newLines} new lines of ${(action.endLine || 0) - (action.startLine || 1) + 1} requested). The content is in the transcript above. Read a DIFFERENT section or use trace_flow/check_guard/check_policy to analyze what you've already read.${nextHint}\n\n${checklist}`;
+                    wasBlocked = true;
+                }
+                else if (readValue.classification === 'invalid') {
+                    qualityTracker.recordRead('invalid', false);
+                    investigationState.recordBlockedRead(action.path);
+                    observation = `BLOCKED: Invalid range for "${action.path}" (startLine=${action.startLine}, endLine=${action.endLine}). The requested range is inverted or out of bounds. Use a valid line range.\n\n${checklist}`;
                     wasBlocked = true;
                 }
                 else {
-                    // Per-file read cap: dynamic based on file size.
-                    // Small files (7 lines) get 5 reads; large files (5000 lines)
-                    // get up to 30 reads so the agent can cover the whole file.
-                    const fileMax = maxReadsForFile(action.path);
-                    const count = (readFileCounts.get(normalizedPath) || 0) + 1;
-                    if (count > fileMax) {
-                        observation = `BLOCKED: You have already read "${action.path}" ${fileMax} times. Further read_file calls on this file will also be blocked. You MUST use a different tool (search_code, trace_flow, check_guard, check_policy, list_imports, or finish) to proceed.`;
-                        wasBlocked = true;
+                    qualityTracker.recordRead(readValue.classification, false);
+                    const readResult = await (0, agentScanExecutor_1.executeReadFileAction)(action, ctx);
+                    observation = readResult.observation;
+                    qualityTracker.recordRead(readValue.classification, readResult.truncated);
+                    if (readResult.totalLines > 0 && !readResult.truncated) {
+                        investigationState.recordActualRead(action.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
+                        const rangeKey = `${normalizedPath}:${readResult.actualStart || 0}:${readResult.actualEnd || 0}`;
+                        readFiles.add(rangeKey);
+                        qualityTracker.recordToolUse('read_file');
+                        investigationState.recordToolUse('read_file');
+                        meaningfulProgressSinceLastExtension = true;
+                        meaningfulProgressSinceRecovery = true;
+                        if (count >= fileMax) {
+                            observation += `\n\nNOTE: You have read "${action.path}" ${count + 1} times. Consider using search_code, trace_flow, check_guard, or check_policy to analyze the code you've read. If you have enough evidence, call finish to report your findings.\n\n${checklist}`;
+                        }
+                    }
+                    else if (readResult.truncated) {
+                        investigationState.recordActualRead(action.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
+                        qualityTracker.recordToolUse('read_file');
+                        investigationState.recordToolUse('read_file');
+                        meaningfulProgressSinceLastExtension = false;
+                        meaningfulProgressSinceRecovery = false;
                     }
                     else {
-                        readFileCounts.set(normalizedPath, count);
-                        readFiles.add(rangeKey);
-                        observation = await (0, agentScanExecutor_1.executeAction)(action, ctx, startResp.runId, client, target);
+                        investigationState.recordBlockedRead(action.path);
                     }
                 }
             }
@@ -245,7 +836,73 @@ async function runAgentScan(ctx, target, options = {}) {
                 else if (action.type === 'check_policy') {
                     toolKey = `check_policy:${action.filePath || ''}`;
                 }
+                else if (action.type === 'call_graph') {
+                    toolKey = `call_graph:${action.filePath || ''}:${action.functionName || ''}`;
+                }
+                else if (action.type === 'git_blame') {
+                    toolKey = `git_blame:${action.filePath || ''}:${action.startLine || 0}:${action.endLine || 0}`;
+                }
+                else if (action.type === 'git_history') {
+                    toolKey = `git_history:${action.filePath || ''}:${action.functionName || ''}`;
+                }
+                else if (action.type === 'git_diff') {
+                    toolKey = `git_diff:${action.baseRef || ''}:${action.headRef || 'HEAD'}`;
+                }
+                else if (action.type === 'check_dependencies') {
+                    toolKey = `check_dependencies`;
+                }
+                else if (action.type === 'read_config') {
+                    toolKey = `read_config:${action.configKind || 'all'}`;
+                }
+                else if (action.type === 'find_definition') {
+                    toolKey = `find_definition:${action.filePath || ''}:${action.symbol || ''}`;
+                }
+                else if (action.type === 'find_references') {
+                    toolKey = `find_references:${action.filePath || ''}:${action.symbol || ''}`;
+                }
+                else if (action.type === 'find_tests') {
+                    toolKey = `find_tests:${action.filePath || ''}:${action.symbol || ''}`;
+                }
+                else if (action.type === 'run_tests') {
+                    const a = action;
+                    if (a.mode === 'existing') {
+                        toolKey = `run_tests:existing:${(a.testFiles || []).join(',')}:${a.testPattern || ''}:${a.packageManager || ''}`;
+                    }
+                    else {
+                        const crypto = require('crypto');
+                        const scriptHash = a.script ? crypto.createHash('sha256').update(a.script).digest('hex').substring(0, 16) : '';
+                        toolKey = `run_tests:generated:${a.runner || ''}:${scriptHash}`;
+                    }
+                }
                 if (toolKey) {
+                    // Check for equivalent search intent (same terms, different
+                    // order) before the raw toolKey dedup.
+                    if (action.type === 'search_code') {
+                        const pattern = action.pattern || '';
+                        const normalized = (0, searchIntent_1.normalizeSearchPattern)(pattern);
+                        let isEquivalent = false;
+                        for (const prev of searchedPatterns) {
+                            if ((0, searchIntent_1.isEquivalentSearchIntent)(prev, pattern)) {
+                                isEquivalent = true;
+                                break;
+                            }
+                        }
+                        if (isEquivalent) {
+                            equivalentSearchCount++;
+                            if (equivalentSearchCount >= 2) {
+                                observation = `BLOCKED: This search is equivalent to a previous search (same terms, different order). The results are in the transcript above. Use find_definition, find_references, call_graph, a targeted read_file with specific line numbers, or trace_flow_cross_file instead.`;
+                                wasBlocked = true;
+                                const checklist = investigationState.formatChecklistForPrompt();
+                                observation += `\n\n${checklist}`;
+                                // Skip execution — jump to the blocked handling
+                                transcript.push({ action, observation });
+                                trace.logToolBlocked(action.type, observation.slice(0, 200));
+                                consecutiveBlockedReads++;
+                                continue;
+                            }
+                        }
+                        searchedPatterns.add(normalized);
+                    }
                     const count = (toolCallCounts.get(toolKey) || 0) + 1;
                     toolCallCounts.set(toolKey, count);
                     if (count > MAX_SAME_TOOL_CALL) {
@@ -253,34 +910,374 @@ async function runAgentScan(ctx, target, options = {}) {
                         wasBlocked = true;
                     }
                     else {
-                        observation = await (0, agentScanExecutor_1.executeAction)(action, ctx, startResp.runId, client, target);
+                        if (action.type === 'trace_flow' || action.type === 'trace_flow_cross_file') {
+                            const flowAction = await (0, agentScanExecutor_1.executeFlowAction)(action, ctx, startResp.runId, client, target);
+                            observation = flowAction.observation;
+                            flowResult = flowAction.flowResult;
+                        }
+                        else {
+                            observation = await (0, agentScanExecutor_1.executeAction)(action, ctx, startResp.runId, client, target);
+                        }
+                        qualityTracker.recordToolUse(action.type);
+                        investigationState.recordToolUse(action.type);
+                        if (action.type === 'search_code') {
+                            investigationState.recordSymbolSearch(action.pattern || '');
+                        }
+                        // First call with these args = meaningful progress.
+                        // Repeated call (count > 1) does NOT reset recovery state.
+                        const isFirstCall = count === 1;
+                        meaningfulProgressSinceLastExtension = isFirstCall;
+                        if (isFirstCall) {
+                            meaningfulProgressSinceRecovery = true;
+                        }
                     }
                 }
                 else {
-                    observation = await (0, agentScanExecutor_1.executeAction)(action, ctx, startResp.runId, client, target);
+                    if (action.type === 'trace_flow' || action.type === 'trace_flow_cross_file') {
+                        const flowAction = await (0, agentScanExecutor_1.executeFlowAction)(action, ctx, startResp.runId, client, target);
+                        observation = flowAction.observation;
+                        flowResult = flowAction.flowResult;
+                    }
+                    else {
+                        observation = await (0, agentScanExecutor_1.executeAction)(action, ctx, startResp.runId, client, target);
+                    }
+                    qualityTracker.recordToolUse(action.type);
+                    investigationState.recordToolUse(action.type);
+                    meaningfulProgressSinceLastExtension = true;
+                    meaningfulProgressSinceRecovery = true;
                 }
             }
-            // Track consecutive blocked reads — if the agent keeps requesting
-            // read_file on blocked files, force-finish to stop wasting steps.
+            // Track consecutive blocked reads — quality-first: don't
+            // force-finish while unread ranges remain and budget is available.
+            // Instead, force a deterministic recovery action.
             if (wasBlocked) {
+                trace.logToolBlocked(action.type, observation.slice(0, 200));
                 consecutiveBlockedReads++;
-                if (consecutiveBlockedReads >= 8) {
-                    console.warn(`[Agent Scan Loop] ${consecutiveBlockedReads} consecutive blocked reads — force-finishing to stop wasting steps.`);
-                    transcript.push({ action, observation });
-                    return {
-                        status: 'completed',
-                        findings: [],
-                        transcript,
-                        stepsUsed: stepsTaken,
-                        costSpentUsd,
-                        summary: `Investigation cut short — agent was stuck re-reading files. No findings reported.`,
-                    };
+                scanState.recovery.consecutiveBlockedActions = consecutiveBlockedReads;
+                scanState.recovery.totalBlockedActions++;
+                scanState.recovery.lastBlockedAction = action.type;
+                scanState.recovery.meaningfulProgressSinceRecovery = false;
+                const recoveryLimit = agentScanProtocol_1.AGENT_SCAN_DEFAULTS.blockedReadRecoveryLimit;
+                if (consecutiveBlockedReads >= 2 && consecutiveBlockedReads < 3) {
+                    const nextRange = target.fileContent
+                        ? investigationState.getPrioritizedUnreadRange(target.filePath, target.fileContent)
+                        : investigationState.getNextUnreadRange(target.filePath);
+                    if (nextRange) {
+                        observation += `\n\nRECOVERY REQUIRED: You have been blocked ${consecutiveBlockedReads} time(s). Read the next unread range: lines ${nextRange.start}-${nextRange.end}, or use an analysis tool (trace_flow, check_guard, check_policy).`;
+                    }
+                    else {
+                        const recommendedTool = investigationState.getRecommendedRecoveryAction();
+                        if (recommendedTool) {
+                            observation += `\n\nRECOVERY REQUIRED: You have been blocked ${consecutiveBlockedReads} time(s). No unread ranges remain. Your next action MUST be: ${recommendedTool}. If you have enough evidence, call finish.`;
+                        }
+                    }
+                }
+                if (consecutiveBlockedReads >= recoveryLimit) {
+                    const nextRange = target.fileContent
+                        ? investigationState.getPrioritizedUnreadRange(target.filePath, target.fileContent)
+                        : investigationState.getNextUnreadRange(target.filePath);
+                    const hasBudget = budget.stepsRemaining > 0 && costSpentUsd < budget.costCapUsd;
+                    const hasWallClock = Date.now() - startTime < wallClockMs;
+                    if (nextRange && hasBudget && hasWallClock) {
+                        console.warn(`[Agent Scan Loop] ${consecutiveBlockedReads} consecutive blocked reads — forcing deterministic recovery to unread range ${nextRange.start}-${nextRange.end}.`);
+                    }
+                    else {
+                        console.warn(`[Agent Scan Loop] ${consecutiveBlockedReads} consecutive blocked reads — no recovery available, force-finishing.`);
+                        transcript.push({ action, observation });
+                        trace.logRunCompleted('completed');
+                        const incompleteSteps = investigationState.getIncompleteSteps();
+                        const autoGaps = incompleteSteps.map(step => ({
+                            title: `Investigation step not completed: ${step}`,
+                            detail: `The agent was force-finished after repeated blocked reads without completing this required investigation step: ${step}. The investigation was incomplete and vulnerabilities may have been missed.`,
+                            file: target.filePath,
+                            requiredEvidence: [`Complete the ${step} step before concluding no vulnerabilities exist`],
+                            suggestedNextAction: step === 'config-inspection' ? 'read_config'
+                                : step === 'policy-check' ? 'check_policy'
+                                    : step === 'cross-file-flow' ? 'trace_flow_cross_file'
+                                        : step === 'route-discovery' ? 'get_endpoints'
+                                            : step === 'auth-symbol-search' ? 'search_code'
+                                                : 'continue investigation',
+                            priority: 'high',
+                        }));
+                        const unresolvedTasks = investigationState.getUnresolvedTasks();
+                        const taskGaps = unresolvedTasks.map(task => ({
+                            title: `Architecture risk unresolved: ${task.claim}`,
+                            detail: `This architecture-risk investigation task was not resolved: ${task.claim}. Required evidence: ${task.requiredEvidence.join('; ')}.`,
+                            file: task.targetFiles[0] || target.filePath,
+                            requiredEvidence: task.requiredEvidence,
+                            suggestedNextAction: task.requiredTools[0] || 'continue investigation',
+                            priority: 'high',
+                        }));
+                        const uncoveredRanges = investigationState.getUncoveredRanges(target.filePath);
+                        const rangeGaps = uncoveredRanges.map(r => ({
+                            title: `Unread range: lines ${r.start}-${r.end} of ${target.filePath}`,
+                            detail: `This range was never read during the investigation. Vulnerabilities in this range were not checked.`,
+                            file: target.filePath,
+                            requiredEvidence: [`Read lines ${r.start}-${r.end} and analyze for vulnerabilities`],
+                            suggestedNextAction: 'read_file',
+                            priority: 'high',
+                        }));
+                        const allGaps = [...autoGaps, ...taskGaps, ...rangeGaps];
+                        (0, scanState_1.terminateScan)(scanState, 'blocked_read_recovery', `Agent stuck re-reading files. ${allGaps.length} coverage gaps.`);
+                        qualityTracker.recordForcedTermination('blocked_read_recovery');
+                        const covSummary = investigationState.getCoverageSummary(target.filePath);
+                        qualityTracker.recordCoverage(covSummary.totalLines, covSummary.coveredLines, covSummary.uncoveredRangeCount, covSummary.largestUncoveredRange);
+                        qualityTracker.recordBudget(stepsTaken, stepsGranted, extensionsGranted, costSpentUsd, budget.costCapUsd, wallClockMs, Date.now() - startTime);
+                        return {
+                            status: 'completed',
+                            findings: [],
+                            transcript,
+                            stepsUsed: stepsTaken,
+                            stepsGranted,
+                            extensionsGranted,
+                            costSpentUsd,
+                            terminationReason: 'blocked_read_recovery',
+                            summary: `Investigation cut short — agent was stuck re-reading files. ${allGaps.length} coverage gaps identified.`,
+                            investigationNotes: [],
+                            coverageGaps: allGaps,
+                        };
+                    }
                 }
             }
             else {
-                consecutiveBlockedReads = 0;
+                trace.logToolCompleted(action.type, observation);
+                // Only reset the blocked counter when meaningful progress was
+                // made. Repeated searches and truncated reads do NOT reset
+                // recovery state — only new coverage, new symbols, or new
+                // tool calls (first invocation with these args) do.
+                if (meaningfulProgressSinceRecovery) {
+                    consecutiveBlockedReads = 0;
+                    scanState.recovery.consecutiveBlockedActions = 0;
+                    scanState.recovery.meaningfulProgressSinceRecovery = true;
+                }
             }
+            // The agent needs both the action it tried and the block/observation
+            // message — the original {action, observation} pair carries both.
+            // We don't need a separate system_event for blocked (unlike
+            // critique, the blocked case is tied to an action the agent took).
             transcript.push({ action, observation });
+            // Link evidence to candidates: when the agent runs a verification
+            // action (trace_flow, check_guard, check_policy, trace_flow_cross_file)
+            // on a file that matches a candidate's location, add evidence to
+            // that candidate. This auto-transitions candidates through
+            // discovered → investigating → supported as evidence accumulates.
+            if (!wasBlocked && candidateStore.size() > 0) {
+                const verificationActions = new Set([
+                    'trace_flow', 'trace_flow_cross_file', 'check_guard', 'check_policy',
+                ]);
+                if (verificationActions.has(action.type)) {
+                    const actionFile = action.filePath || action.path || target.filePath;
+                    const actionFileNorm = String(actionFile).replace(/\\/g, '/').toLowerCase();
+                    for (const candidate of candidateStore.getAll()) {
+                        const matchesLocation = candidate.locations.some(loc => loc.filePath.replace(/\\/g, '/').toLowerCase() === actionFileNorm);
+                        if (matchesLocation) {
+                            const evidenceId = `${action.type}:${actionFileNorm}:${stepsTaken}`;
+                            const category = action.type === 'trace_flow' || action.type === 'trace_flow_cross_file' ? 'flow'
+                                : action.type === 'check_guard' ? 'guard'
+                                    : action.type === 'check_policy' ? 'policy'
+                                        : undefined;
+                            candidateStore.addEvidence(candidate.id, evidenceId, category);
+                        }
+                    }
+                }
+                if (action.type === 'read_file' && candidateStore.size() > 0) {
+                    const actionFileNorm = String(action.path || target.filePath).replace(/\\/g, '/').toLowerCase();
+                    for (const candidate of candidateStore.getAll()) {
+                        const matchesLocation = candidate.locations.some(loc => loc.filePath.replace(/\\/g, '/').toLowerCase() === actionFileNorm);
+                        if (matchesLocation && candidate.evidenceCategories?.includes('source') !== true) {
+                            candidateStore.addEvidence(candidate.id, `source:${actionFileNorm}:${stepsTaken}`, 'source');
+                        }
+                    }
+                }
+            }
+            // Link evidence to work items: when the agent runs an action on
+            // a file that matches a work item's target files, add evidence
+            // and resolve the work item if it has enough evidence.
+            if (!wasBlocked && workItemQueue.size() > 0) {
+                const actionFile = action.filePath || action.path || target.filePath;
+                const actionFileNorm = String(actionFile).replace(/\\/g, '/').toLowerCase();
+                const evidenceKindMap = {
+                    read_file: 'source-range',
+                    search_code: 'symbol-reference',
+                    trace_flow: 'cross-file-flow',
+                    trace_flow_cross_file: 'cross-file-flow',
+                    check_guard: 'guard-result',
+                    check_policy: 'policy-result',
+                    get_endpoints: 'handler-inventory',
+                    list_imports: 'symbol-reference',
+                    find_definition: 'symbol-definition',
+                    find_references: 'symbol-reference',
+                    find_tests: 'test-location',
+                    run_tests: 'test-result',
+                    read_config: 'config-result',
+                    call_graph: 'cross-file-flow',
+                };
+                const evidenceKind = evidenceKindMap[action.type] || 'source-range';
+                for (const item of workItemQueue.getExecutable()) {
+                    const matchesFile = item.targetFiles.length === 0 ||
+                        item.targetFiles.some(f => f.replace(/\\/g, '/').toLowerCase() === actionFileNorm);
+                    if (matchesFile) {
+                        const evidenceId = `${action.type}:${actionFileNorm}:${stepsTaken}`;
+                        workItemQueue.addEvidence(item.id, evidenceId);
+                        for (const req of item.requirements) {
+                            if (!req.acceptedKinds.includes(evidenceKind))
+                                continue;
+                            if (req.targetFiles && req.targetFiles.length > 0) {
+                                const reqMatches = req.targetFiles.some(f => f.replace(/\\/g, '/').toLowerCase() === actionFileNorm);
+                                if (!reqMatches)
+                                    continue;
+                            }
+                            if (req.requiredTools && req.requiredTools.length > 0) {
+                                if (!req.requiredTools.includes(action.type))
+                                    continue;
+                            }
+                            workItemQueue.addEvidenceForRequirement(item.id, req.id, evidenceId);
+                        }
+                        if (workItemQueue.isFullyResolved(item.id)) {
+                            workItemQueue.resolve(item.id);
+                        }
+                    }
+                }
+            }
+            // Re-sync candidates-verified after evidence linking
+            if (candidateStore.allReadyForJuror()) {
+                investigationState.markCandidatesVerified();
+            }
+            // Evidence ledger: record evidence for each action type. This
+            // populates the evidence ledger so the scheduler can suggest
+            // actions for unsatisfied requirements and the finish gate can
+            // verify all evidence requirements are met.
+            if (!wasBlocked) {
+                const actionFile = String(action.filePath || action.path || target.filePath);
+                const evidenceKindMap = {
+                    read_file: 'source-range',
+                    search_code: 'symbol-reference',
+                    trace_flow: 'cross-file-flow',
+                    trace_flow_cross_file: 'cross-file-flow',
+                    check_guard: 'guard-result',
+                    check_policy: 'policy-result',
+                    get_endpoints: 'handler-inventory',
+                    list_imports: 'symbol-reference',
+                    find_definition: 'symbol-definition',
+                    find_references: 'symbol-reference',
+                    find_tests: 'test-location',
+                    run_tests: 'test-result',
+                    read_config: 'config-result',
+                    call_graph: 'cross-file-flow',
+                };
+                const kind = evidenceKindMap[action.type];
+                if (kind) {
+                    evidenceLedger.recordEvidence({
+                        kind: kind,
+                        tool: action.type,
+                        filePath: actionFile,
+                        range: action.type === 'read_file'
+                            ? { start: action.startLine || 1, end: action.endLine || 1 }
+                            : undefined,
+                        symbol: action.symbol || action.pattern || undefined,
+                        outcome: wasBlocked ? 'blocked' : 'positive',
+                        transcriptStep: stepsTaken,
+                    });
+                }
+            }
+            // Flow verification: classify trace_flow/trace_flow_cross_file
+            // results using structured data from the executor, not observation
+            // text heuristics. This prevents the cross-file-flow checklist step
+            // from completing until a flow result has been explicitly classified.
+            if (action.type === 'trace_flow' || action.type === 'trace_flow_cross_file') {
+                const flowFile = String(action.filePath || target.filePath);
+                if (wasBlocked) {
+                    investigationState.recordFlowVerification(flowFile, action.type, 'blocked', 0, 'Action was blocked');
+                }
+                else if (flowResult) {
+                    investigationState.recordFlowVerification(flowFile, action.type, flowResult.status, flowResult.hops.length, flowResult.error || `${flowResult.hops.length} hop(s)`, {
+                        source: flowResult.source,
+                        sink: flowResult.sink,
+                        hops: flowResult.hops,
+                        truncated: flowResult.truncated,
+                        error: flowResult.error,
+                    });
+                }
+                else {
+                    investigationState.recordFlowVerification(flowFile, action.type, 'inconclusive', 0, 'No structured flow result available');
+                }
+            }
+            // handlers and populate the handler inventory. Create handler
+            // review work items for security-sensitive handlers.
+            if (!wasBlocked && action.type === 'get_endpoints') {
+                try {
+                    const endpoints = await (0, endpointDiscovery_1.discoverEndpoints)(ctx.workspaceRoot, action.glob);
+                    if (endpoints.length > 0) {
+                        handlerInventory.addFromEndpoints(endpoints, target.filePath);
+                        // Create work items for newly discovered handlers
+                        for (const handler of handlerInventory.getAll()) {
+                            if (!workItemQueue.all().some(w => w.title === `Review handler: ${handler.symbol || 'unknown'}`)) {
+                                workItemQueue.add((0, workItem_1.createHandlerReviewWorkItem)(handler.filePath, handler.symbol || 'unknown'));
+                            }
+                        }
+                    }
+                    else {
+                        // No handlers found — auto-complete all-handlers-reviewed
+                        investigationState.markAllHandlersReviewed();
+                    }
+                }
+                catch { /* best-effort */ }
+            }
+            // Auto-complete all-handlers-reviewed if handler inventory is
+            // empty (no handlers to review for this file type)
+            if (handlerInventory.size() === 0 && !investigationState.getCompletedSteps().includes('all-handlers-reviewed')) {
+                investigationState.markAllHandlersReviewed();
+            }
+            // Handler review tracking: when the agent reads a file range that
+            // covers a handler's range, mark that handler as reviewed.
+            if (!wasBlocked && action.type === 'read_file' && handlerInventory.size() > 0) {
+                const readStart = action.startLine || 1;
+                const readEnd = action.endLine || 9999;
+                const readFileNorm = String(action.path || target.filePath).replace(/\\/g, '/').toLowerCase();
+                for (const handler of handlerInventory.getAll()) {
+                    if (!handler.reviewed) {
+                        const handlerFileNorm = handler.filePath.replace(/\\/g, '/').toLowerCase();
+                        if (handlerFileNorm === readFileNorm) {
+                            if (handler.range.start >= readStart && handler.range.end <= readEnd) {
+                                handlerInventory.markReviewed(handler.id);
+                            }
+                        }
+                    }
+                }
+            }
+            // Deterministic recovery: on the third consecutive blocked read,
+            // skip the API and directly execute a recovery action selected by
+            // the MCP. This prevents wasting API calls on an agent that is
+            // stuck re-reading files.
+            if (wasBlocked && consecutiveBlockedReads >= 3) {
+                const recoveryAction = selectDeterministicRecoveryAction(investigationState, target, ctx);
+                if (recoveryAction) {
+                    stepsTaken++;
+                    budget.stepsRemaining--;
+                    trace.nextStep();
+                    trace.logActionSelected(recoveryAction.type, 'deterministic-recovery', false);
+                    if (options.onProgress) {
+                        options.onProgress(stepsTaken, stepsGranted, `Step ${stepsTaken}: deterministic recovery: ${describeAction(recoveryAction)}`);
+                    }
+                    let recoveryObservation;
+                    if (recoveryAction.type === 'read_file') {
+                        const readResult = await (0, agentScanExecutor_1.executeReadFileAction)(recoveryAction, ctx);
+                        recoveryObservation = readResult.observation;
+                        if (readResult.totalLines > 0) {
+                            investigationState.recordActualRead(recoveryAction.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
+                        }
+                    }
+                    else {
+                        recoveryObservation = await (0, agentScanExecutor_1.executeAction)(recoveryAction, ctx, startResp.runId, client, target);
+                    }
+                    qualityTracker.recordToolUse(recoveryAction.type);
+                    investigationState.recordToolUse(recoveryAction.type);
+                    consecutiveBlockedReads = 0; // recovery resets the counter
+                    meaningfulProgressSinceRecovery = true; // recovery is meaningful progress
+                    trace.logToolCompleted(recoveryAction.type, recoveryObservation);
+                    transcript.push({ action: recoveryAction, observation: `[DETERMINISTIC RECOVERY] ${recoveryObservation}` });
+                }
+            }
         }
     }
     catch (err) {
@@ -289,11 +1286,162 @@ async function runAgentScan(ctx, target, options = {}) {
             findings: [],
             transcript: [],
             stepsUsed: stepsTaken,
+            stepsGranted,
+            extensionsGranted,
             costSpentUsd,
+            terminationReason: 'api_error',
             error: err.message || String(err),
+            investigationNotes: [],
+            coverageGaps: [],
         };
     }
 }
+function isCoherentText(text) {
+    if (!text || text.length < 5)
+        return false;
+    const asciiLetters = (text.match(/[a-zA-Z]/g) || []).length;
+    const totalChars = text.length;
+    if (totalChars > 0 && asciiLetters / totalChars < 0.3)
+        return false;
+    const controlChars = (text.match(/[\x00-\x08\x0B\x0C\x0E-\x1F\uFFFD]/g) || []).length;
+    if (controlChars > 0)
+        return false;
+    const words = text.split(/\s+/).filter(w => w.length > 1);
+    if (words.length < 3)
+        return false;
+    return true;
+}
+const TRANSCRIPT_CHAR_BUDGET = 120_000;
+const TRANSCRIPT_KEEP_RECENT = 12;
+const TRANSCRIPT_SUMMARY_LEN = 200;
+function estimateTranscriptSize(transcript) {
+    let size = 0;
+    for (const step of transcript) {
+        size += (step.observation || '').length;
+        size += JSON.stringify(step.action || {}).length;
+    }
+    return size;
+}
+function compactTranscript(transcript) {
+    const totalSize = estimateTranscriptSize(transcript);
+    if (totalSize <= TRANSCRIPT_CHAR_BUDGET || transcript.length <= TRANSCRIPT_KEEP_RECENT) {
+        return transcript;
+    }
+    const cutoff = transcript.length - TRANSCRIPT_KEEP_RECENT;
+    const compacted = [];
+    for (let i = 0; i < transcript.length; i++) {
+        if (i < cutoff) {
+            const obs = transcript[i].observation || '';
+            const actionType = transcript[i].action?.type || 'unknown';
+            if (actionType === 'system_event' || actionType === 'finish') {
+                compacted.push(transcript[i]);
+            }
+            else if (obs.length > TRANSCRIPT_SUMMARY_LEN) {
+                compacted.push({
+                    action: transcript[i].action,
+                    observation: obs.slice(0, TRANSCRIPT_SUMMARY_LEN) + '\n...[compacted]',
+                });
+            }
+            else {
+                compacted.push(transcript[i]);
+            }
+        }
+        else {
+            compacted.push(transcript[i]);
+        }
+    }
+    return compacted;
+}
+function compactTranscriptAggressive(transcript) {
+    const keepRecent = 6;
+    const summaryLen = 100;
+    if (transcript.length <= keepRecent) {
+        return transcript;
+    }
+    const cutoff = transcript.length - keepRecent;
+    const compacted = [];
+    for (let i = 0; i < transcript.length; i++) {
+        if (i < cutoff) {
+            const obs = transcript[i].observation || '';
+            const actionType = transcript[i].action?.type || 'unknown';
+            if (actionType === 'system_event' || actionType === 'finish') {
+                compacted.push(transcript[i]);
+            }
+            else if (obs.length > summaryLen) {
+                compacted.push({
+                    action: transcript[i].action,
+                    observation: obs.slice(0, summaryLen) + '\n...[compacted]',
+                });
+            }
+            else {
+                compacted.push(transcript[i]);
+            }
+        }
+        else {
+            compacted.push(transcript[i]);
+        }
+    }
+    return compacted;
+}
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+function sanitizeFindingText(text) {
+    if (!text)
+        return text;
+    return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\uFFFD]/g, '').trim();
+}
+function validateFinding(f, index) {
+    const issues = [];
+    const sanitized = { ...f };
+    if (typeof sanitized.line !== 'number' || sanitized.line < 1 || !Number.isFinite(sanitized.line)) {
+        issues.push(`finding[${index}]: invalid line "${sanitized.line}" — defaulting to 0`);
+        sanitized.line = 0;
+    }
+    if (typeof sanitized.type !== 'string' || sanitized.type.trim().length === 0) {
+        issues.push(`finding[${index}]: missing or empty type — defaulting to "unknown"`);
+        sanitized.type = 'unknown';
+    }
+    if (typeof sanitized.severity !== 'string' || !VALID_SEVERITIES.has(sanitized.severity)) {
+        issues.push(`finding[${index}]: invalid severity "${sanitized.severity}" — defaulting to "low"`);
+        sanitized.severity = 'low';
+    }
+    if (typeof sanitized.confidence !== 'number' || !Number.isFinite(sanitized.confidence)) {
+        issues.push(`finding[${index}]: invalid confidence — defaulting to 0.3`);
+        sanitized.confidence = 0.3;
+    }
+    else {
+        sanitized.confidence = Math.max(0, Math.min(1, sanitized.confidence));
+    }
+    if (sanitized.lineEnd !== undefined && (typeof sanitized.lineEnd !== 'number' || sanitized.lineEnd < sanitized.line)) {
+        delete sanitized.lineEnd;
+    }
+    sanitized.why = sanitizeFindingText(sanitized.why || '');
+    if (!isCoherentText(sanitized.why)) {
+        issues.push(`finding[${index}]: incoherent "why" — downgrading severity`);
+        sanitized.why = `[Quality warning: model produced incoherent explanation] ${sanitized.why || '(empty)'}`;
+        if (sanitized.severity === 'high' || sanitized.severity === 'critical') {
+            sanitized.severity = 'medium';
+        }
+        sanitized.confidence = Math.min(sanitized.confidence, 0.3);
+    }
+    sanitized.evidence = sanitizeFindingText(sanitized.evidence || '');
+    return { finding: sanitized, issues };
+}
+function sanitizeFindings(findings) {
+    if (!Array.isArray(findings))
+        return [];
+    const seen = new Set();
+    const result = [];
+    for (let i = 0; i < findings.length; i++) {
+        const { finding, issues } = validateFinding(findings[i], i);
+        const dedupKey = `${finding.type}:${finding.line}`;
+        if (seen.has(dedupKey)) {
+            continue;
+        }
+        seen.add(dedupKey);
+        result.push(finding);
+    }
+    return result;
+}
 function describeAction(action) {
     switch (action.type) {
         case 'read_file': return `read_file(${action.path})`;
@@ -305,7 +1453,63 @@ function describeAction(action) {
         case 'get_endpoints': return `get_endpoints(${action.glob || 'all'})`;
         case 'list_imports': return `list_imports(${action.filePath})`;
         case 'list_files': return `list_files(${action.path || 'root'})`;
+        case 'call_graph': return `call_graph(${action.filePath})`;
+        case 'git_blame': return `git_blame(${action.filePath})`;
+        case 'git_history': return `git_history(${action.filePath || 'repo'})`;
+        case 'git_diff': return `git_diff(${action.baseRef}..${action.headRef || 'HEAD'})`;
+        case 'check_dependencies': return 'check_dependencies';
+        case 'read_config': return `read_config(${action.configKind || 'all'})`;
+        case 'find_definition': return `find_definition(${action.symbol})`;
+        case 'find_references': return `find_references(${action.symbol})`;
+        case 'find_tests': return `find_tests(${action.filePath}${action.symbol ? ':' + action.symbol : ''})`;
+        case 'run_tests': return `run_tests(${action.mode}${action.testFiles?.length ? ':' + action.testFiles.length + ' files' : ''})`;
         case 'finish': return 'finish';
+        case 'system_event': return `system_event(${action.eventType})`;
+    }
+}
+/**
+ * Select a deterministic recovery action based on investigation state.
+ *
+ * Priority:
+ *   1. Unread range exists on the target file → read_file(next unread range)
+ *   2. route-discovery missing → get_endpoints
+ *   3. policy-check missing → check_policy
+ *   4. auth-symbol-search missing → search_code
+ *   5. cross-file-flow missing → trace_flow_cross_file
+ *   6. config-inspection missing → read_config
+ *   7. tests-found missing → find_tests
+ *   8. otherwise → null (force-finish will handle it)
+ */
+function selectDeterministicRecoveryAction(state, target, ctx) {
+    // Priority 1: unread range on the target file
+    const nextRange = state.getNextUnreadRange(target.filePath);
+    if (nextRange) {
+        return {
+            type: 'read_file',
+            path: target.filePath,
+            startLine: nextRange.start,
+            endLine: nextRange.end,
+            rationale: 'Deterministic recovery: reading next unread range',
+        };
+    }
+    // Priority 2-7: incomplete investigation steps
+    const incomplete = state.getIncompleteSteps();
+    for (const step of incomplete) {
+        switch (step) {
+            case 'route-discovery':
+                return { type: 'get_endpoints', rationale: 'Deterministic recovery: route discovery' };
+            case 'policy-check':
+                return { type: 'check_policy', filePath: target.filePath, rationale: 'Deterministic recovery: policy check' };
+            case 'auth-symbol-search':
+                return { type: 'search_code', pattern: 'auth|require|guard|permission|owner', rationale: 'Deterministic recovery: auth symbol search' };
+            case 'cross-file-flow':
+                return { type: 'trace_flow_cross_file', filePath: target.filePath, rationale: 'Deterministic recovery: cross-file flow' };
+            case 'config-inspection':
+                return { type: 'read_config', configKind: 'all', rationale: 'Deterministic recovery: config inspection' };
+            case 'tests-found':
+                return { type: 'find_tests', filePath: target.filePath, rationale: 'Deterministic recovery: find tests' };
+        }
     }
+    return null;
 }
 //# sourceMappingURL=agentScanLoop.js.map