@securecode-ai/mcp 0.6.1 → 0.9.0

package/dist/attack/agentScanLoop.js

@@ -39,6 +39,7 @@ const workItem_1 = require("./workItem");
 const handlerInventory_1 = require("../project-map/handlerInventory");
 const candidateStore_1 = require("./candidateStore");
 const scanScheduler_1 = require("./scanScheduler");
+const llmHealth_1 = require("./llmHealth");
 const finishGate_1 = require("./finishGate");
 const qualityMetrics_1 = require("./qualityMetrics");
 const agentScanExecutor_2 = require("./agentScanExecutor");
@@ -61,6 +62,24 @@ async function runAgentScan(ctx, target, options = {}) {
     let stepsGranted = budget.stepsGranted;
     let extensionsGranted = budget.extensionsGranted;
     let meaningfulProgressSinceLastExtension = false;
+    let activeRunId = null;
+    // Best-effort run close: on any exit that is not a delivered
+    // agent_finish, tell the API to mark the run terminal immediately
+    // instead of waiting up to 30 minutes for the janitor. The janitor
+    // remains the fallback (refund happens there, not here).
+    const closeRun = async (result) => {
+        if (activeRunId && result.terminationReason !== 'agent_finish') {
+            try {
+                await client.postJson('/agent/scan/close', {
+                    runId: activeRunId,
+                    status: result.status,
+                    terminationReason: result.terminationReason,
+                }, options.signal);
+            }
+            catch { /* best-effort — janitor will expire the run */ }
+        }
+        return result;
+    };
     try {
         const startRespRaw = await client.postJson('/agent/scan/start', {}, options.signal);
         const startValidation = (0, protocolValidator_1.validateStartResponse)(startRespRaw);
@@ -80,8 +99,13 @@ async function runAgentScan(ctx, target, options = {}) {
             };
         }
         const startResp = startValidation.value;
+        activeRunId = startResp.runId;
         const trace = new agentTrace_1.AgentTraceLogger(ctx.workspaceRoot, startResp.runId);
         trace.logRunStarted();
+        // LLM health monitor — trips on degraded-model pathologies
+        // (repeat bursts, A/B alternation, provider degraded streaks) that
+        // the consecutive-blocked counters miss.
+        const llmHealth = (0, llmHealth_1.createLlmHealthMonitor)();
         // 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.
@@ -241,6 +265,80 @@ async function runAgentScan(ctx, target, options = {}) {
                 return 8;
             }
         }
+        // Feed an EXECUTED action into the control plane: credit matching
+        // work items and record ledger evidence so requirements actually
+        // advance. Used for both model actions and deterministic-recovery
+        // executions — before recovery was wired in, scheduler-proposed
+        // actions executed without recording evidence, so the scheduler
+        // (a pure function of unchanged state) re-proposed the identical
+        // action until the run died on duplicate-recovery rejections.
+        // The ledger's content fingerprint dedups identical model/recovery
+        // evidence, so no double-counting occurs; work-item evidence ids
+        // carry a `:recovery` marker for traceability.
+        function recordActionEvidence(executedAction, stepIndex, source) {
+            const actionFile = String(executedAction.filePath || executedAction.path || target.filePath);
+            const actionFileNorm = 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',
+            };
+            if (workItemQueue.size() > 0) {
+                const evidenceKind = evidenceKindMap[executedAction.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 = source === 'recovery'
+                            ? `${executedAction.type}:${actionFileNorm}:${stepIndex}:recovery`
+                            : `${executedAction.type}:${actionFileNorm}:${stepIndex}`;
+                        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(executedAction.type))
+                                    continue;
+                            }
+                            workItemQueue.addEvidenceForRequirement(item.id, req.id, evidenceId);
+                        }
+                        if (workItemQueue.isFullyResolved(item.id)) {
+                            workItemQueue.resolve(item.id);
+                        }
+                    }
+                }
+            }
+            const kind = evidenceKindMap[executedAction.type];
+            if (kind) {
+                evidenceLedger.recordEvidence({
+                    kind: kind,
+                    tool: executedAction.type,
+                    filePath: actionFile,
+                    range: executedAction.type === 'read_file'
+                        ? { start: executedAction.startLine || 1, end: executedAction.endLine || 1 }
+                        : undefined,
+                    symbol: executedAction.symbol || executedAction.pattern || undefined,
+                    outcome: 'positive',
+                    transcriptStep: stepIndex,
+                });
+            }
+        }
         // 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();
@@ -257,11 +355,49 @@ async function runAgentScan(ctx, target, options = {}) {
         let lastFinishRejectionReasons = [];
         const attemptedRecoveryFingerprints = new Set();
         const RECOVERY_FAILURE_LIMIT = 3;
+        // Coverage-gap snapshot for abnormal terminations — documents what
+        // the investigation did NOT get to, so "no findings" is never read
+        // as "clean" after a cut-short run.
+        const buildCoverageGaps = () => {
+            const incompleteSteps = investigationState.getIncompleteSteps();
+            const autoGaps = incompleteSteps.map(step => ({
+                title: `Investigation step not completed: ${step}`,
+                detail: `The agent was terminated 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',
+            }));
+            return [...autoGaps, ...taskGaps, ...rangeGaps];
+        };
         while (true) {
             // Wall clock check
             if (Date.now() - startTime > wallClockMs) {
                 (0, scanState_1.terminateScan)(scanState, 'wall_clock', `Wall clock limit (${wallClockMs}ms) exceeded.`);
-                return {
+                return closeRun({
                     status: 'incomplete',
                     findings: [],
                     transcript,
@@ -273,12 +409,12 @@ async function runAgentScan(ctx, target, options = {}) {
                     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 {
+                return closeRun({
                     status: 'cancelled',
                     findings: [],
                     transcript,
@@ -290,16 +426,18 @@ async function runAgentScan(ctx, target, options = {}) {
                     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 via scheduler
+            //   2+ blocked reads: recovery mode — if the scheduler has a
+            //     deterministic action, require it; otherwise forbid
+            //     read_file entirely and require an analysis tool. The
+            //     constraint keeps being sent while blocked reads continue,
+            //     so the model always has guidance while the MCP's own
+            //     deterministic recovery (3+ blocked) executes.
             let actionConstraint;
-            if (consecutiveBlockedReads >= 2 && consecutiveBlockedReads < 3) {
+            if (consecutiveBlockedReads >= 2) {
                 const schedDecision = (0, scanScheduler_1.schedule)({
                     state: scanState,
                     evidence: evidenceLedger,
@@ -375,7 +513,7 @@ async function runAgentScan(ctx, target, options = {}) {
                         observation: errMsg,
                     });
                     if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
-                        return {
+                        return closeRun({
                             status: 'incomplete',
                             findings: [],
                             transcript,
@@ -387,7 +525,7 @@ async function runAgentScan(ctx, target, options = {}) {
                             summary: `Step budget exhausted after ${consecutiveErrors} consecutive malformed API responses. Last error: ${vErr}`,
                             investigationNotes: [],
                             coverageGaps: [],
-                        };
+                        });
                     }
                     continue;
                 }
@@ -412,7 +550,7 @@ async function runAgentScan(ctx, target, options = {}) {
                                 priority: 'medium',
                             });
                         }
-                        return {
+                        return closeRun({
                             status: 'completed',
                             findings: sanitizeFindings(finish.findings),
                             investigationNotes: finish.investigationNotes ?? [],
@@ -424,10 +562,10 @@ async function runAgentScan(ctx, target, options = {}) {
                             costSpentUsd,
                             terminationReason: 'agent_finish',
                             summary: finish.summary,
-                        };
+                        });
                     }
                     console.warn(`[Agent Scan Loop] Agent run expired (API server restarted?). Stopping scan.`);
-                    return {
+                    return closeRun({
                         status: 'failed',
                         findings: [],
                         transcript,
@@ -439,11 +577,11 @@ async function runAgentScan(ctx, target, options = {}) {
                         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.
                 if (options.signal?.aborted || /aborted/i.test(errMsg)) {
-                    return {
+                    return closeRun({
                         status: 'cancelled',
                         findings: [],
                         transcript,
@@ -455,7 +593,7 @@ async function runAgentScan(ctx, target, options = {}) {
                         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)) {
@@ -482,7 +620,7 @@ async function runAgentScan(ctx, target, options = {}) {
                     observation: errorMsg,
                 });
                 if (consecutiveErrors >= 3 || budget.stepsRemaining <= 0) {
-                    return {
+                    return closeRun({
                         status: 'incomplete',
                         findings: [],
                         transcript,
@@ -494,13 +632,14 @@ async function runAgentScan(ctx, target, options = {}) {
                         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;
+            llmHealth.recordStepTelemetry(!!stepResp.degraded || !!stepResp.fallbackFired);
             trace.logStepRequested(stepResp.model, stepResp.tokens, stepResp.costUsd, stepResp.latencyMs);
             // Transition from planning to surveying on first successful step
             if (scanState.phase === 'planning') {
@@ -555,7 +694,7 @@ async function runAgentScan(ctx, target, options = {}) {
                     ? 'incomplete'
                     : (stepResp.degraded ? 'incomplete' : 'completed');
                 trace.logRunCompleted(status);
-                return {
+                return closeRun({
                     status,
                     findings: [],
                     transcript,
@@ -569,9 +708,46 @@ async function runAgentScan(ctx, target, options = {}) {
                         : 'Agent completed without explicit finish.',
                     investigationNotes: [],
                     coverageGaps: [],
-                };
+                });
             }
             const action = stepResp.next;
+            llmHealth.recordModelAction((0, scanScheduler_1.actionFingerprint)(action));
+            const healthTrip = llmHealth.evaluate();
+            if (healthTrip.tripped) {
+                // Degraded-model circuit breaker — the model is looping
+                // (repeat bursts / alternation) or the provider reports a
+                // sustained degraded streak. Continuing burns budget without
+                // producing evidence; terminate with documented gaps instead.
+                console.warn(`[Agent Scan Loop] LLM health trip (${healthTrip.signal}) at step ${stepsTaken + 1}: ${healthTrip.detail}`);
+                (0, scanState_1.terminateScan)(scanState, 'llm_degraded', healthTrip.detail);
+                qualityTracker.recordForcedTermination('llm_degraded');
+                transcript.push({
+                    action: {
+                        type: 'system_event',
+                        eventType: 'error',
+                        message: `Scan terminated: the model server appears degraded (${healthTrip.detail})`,
+                    },
+                    observation: healthTrip.detail,
+                });
+                trace.logRunCompleted('incomplete');
+                const allGaps = buildCoverageGaps();
+                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 closeRun({
+                    status: 'incomplete',
+                    findings: [],
+                    transcript,
+                    stepsUsed: stepsTaken,
+                    stepsGranted,
+                    extensionsGranted,
+                    costSpentUsd,
+                    terminationReason: 'llm_degraded',
+                    summary: `Model server degraded — ${healthTrip.detail} ${allGaps.length} coverage gaps identified. Retry the scan later; no credits are lost (the run is auto-refunded).`,
+                    investigationNotes: [],
+                    coverageGaps: allGaps,
+                });
+            }
             stepsTaken++;
             budget.stepsRemaining = stepResp.stepsRemaining;
             scanState.budget.stepsUsed = stepsTaken;
@@ -716,7 +892,7 @@ async function runAgentScan(ctx, target, options = {}) {
                             candidateStore.setUnproven(candidate.id, `Converted to note: missing proof dimensions ${missingDims.join(', ')}`);
                         }
                     }
-                    return {
+                    return closeRun({
                         status: 'completed',
                         findings: sanitizeFindings(action.findings),
                         investigationNotes,
@@ -729,7 +905,7 @@ async function runAgentScan(ctx, target, options = {}) {
                         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('; ')}`);
@@ -795,6 +971,7 @@ async function runAgentScan(ctx, target, options = {}) {
                     const abs = require('path').resolve(ctx.workspaceRoot, action.path);
                     const content = fs.readFileSync(abs, 'utf8');
                     totalLines = content.split('\n').length;
+                    investigationState.recordLineDensity(action.path, content);
                 }
                 catch { /* best-effort */ }
                 const readValue = investigationState.classifyRead(action.path, action.startLine, action.endLine, totalLines);
@@ -825,12 +1002,27 @@ async function runAgentScan(ctx, target, options = {}) {
                     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 if (readValue.classification === 'function-map') {
+                    qualityTracker.recordRead('function-map', 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: The function map for "${action.path}" is already in the transcript above — it delivers no source coverage. Use read_file with explicit startLine/endLine to read the actual code.${nextHint}\n\n${checklist}`;
+                    wasBlocked = true;
+                }
                 else {
                     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) {
+                    // Record coverage for the DELIVERED range only. A ranged
+                    // read on a dense file can be cut at the observation
+                    // cap — the executor reports the last line actually
+                    // delivered, and recording only that range leaves the
+                    // cut-off tail re-readable instead of silently marking
+                    // it covered.
+                    if (readResult.totalLines > 0 && readResult.actualStart > 0 && readResult.actualEnd >= readResult.actualStart) {
                         investigationState.recordActualRead(action.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
                         const rangeKey = `${normalizedPath}:${readResult.actualStart || 0}:${readResult.actualEnd || 0}`;
                         readFiles.add(rangeKey);
@@ -842,7 +1034,11 @@ async function runAgentScan(ctx, target, options = {}) {
                             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) {
+                    else if (readResult.totalLines > 0 && readResult.truncated) {
+                        // Function-map read (large file, no range): no
+                        // content lines delivered. recordActualRead registers
+                        // the fnmap key so an immediate identical repeat is
+                        // blocked with a ranged-read hint.
                         investigationState.recordActualRead(action.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
                         qualityTracker.recordToolUse('read_file');
                         investigationState.recordToolUse('read_file');
@@ -1008,45 +1204,13 @@ async function runAgentScan(ctx, target, options = {}) {
                         console.warn(`[Agent Scan Loop] ${consecutiveBlockedReads} consecutive blocked reads — no recovery available, terminating as incomplete.`);
                         transcript.push({ action, observation });
                         trace.logRunCompleted('incomplete');
-                        const incompleteSteps = investigationState.getIncompleteSteps();
-                        const autoGaps = incompleteSteps.map(step => ({
-                            title: `Investigation step not completed: ${step}`,
-                            detail: `The agent was terminated 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];
+                        const allGaps = buildCoverageGaps();
                         (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 {
+                        return closeRun({
                             status: 'incomplete',
                             findings: [],
                             transcript,
@@ -1058,7 +1222,7 @@ async function runAgentScan(ctx, target, options = {}) {
                             summary: `Investigation cut short — agent was stuck re-reading files. ${allGaps.length} coverage gaps identified.`,
                             investigationNotes: [],
                             coverageGaps: allGaps,
-                        };
+                        });
                     }
                 }
             }
@@ -1115,96 +1279,21 @@ async function runAgentScan(ctx, target, options = {}) {
                     }
                 }
             }
-            // 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);
-                        }
-                    }
-                }
+            // Link evidence to work items and the evidence ledger: 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. The ledger record populates requirements so
+            // the scheduler can suggest actions for unsatisfied requirements
+            // and the finish gate can verify all evidence requirements are
+            // met. Deterministic-recovery executions go through the same
+            // path (see recordActionEvidence).
+            if (!wasBlocked) {
+                recordActionEvidence(action, stepsTaken, 'model');
             }
             // 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
@@ -1333,7 +1422,7 @@ async function runAgentScan(ctx, target, options = {}) {
                                 suggestedNextAction: 'read_file',
                                 priority: 'high',
                             }));
-                            return {
+                            return closeRun({
                                 status: 'incomplete',
                                 findings: [],
                                 transcript,
@@ -1345,7 +1434,7 @@ async function runAgentScan(ctx, target, options = {}) {
                                 summary: `Investigation incomplete — ${RECOVERY_FAILURE_LIMIT} recovery failures without progress. Model blocked ${scanState.recovery.totalModelBlockedActions} time(s), recovery attempted ${scanState.recovery.totalRecoveryAttempts} time(s).`,
                                 investigationNotes: [],
                                 coverageGaps: [...autoGaps, ...taskGaps, ...rangeGaps],
-                            };
+                            });
                         }
                     }
                     else {
@@ -1364,9 +1453,17 @@ async function runAgentScan(ctx, target, options = {}) {
                         if (recoveryAction.type === 'read_file') {
                             const readResult = await (0, agentScanExecutor_1.executeReadFileAction)(recoveryAction, ctx);
                             recoveryObservation = readResult.observation;
-                            if (readResult.totalLines > 0 && !readResult.truncated) {
+                            if (readResult.totalLines > 0) {
+                                // Record the DELIVERED range only — a ranged
+                                // recovery read on a dense file can be cut
+                                // at the observation cap; recording only the
+                                // delivered lines keeps the cut-off tail
+                                // re-readable. Function-map results (0/0)
+                                // register the fnmap key without coverage.
                                 investigationState.recordActualRead(recoveryAction.path, readResult.actualStart, readResult.actualEnd, readResult.totalLines, readResult.truncated);
-                                recoveryMadeProgress = true;
+                                if (readResult.actualStart > 0 && readResult.actualEnd >= readResult.actualStart) {
+                                    recoveryMadeProgress = true;
+                                }
                             }
                         }
                         else {
@@ -1375,6 +1472,13 @@ async function runAgentScan(ctx, target, options = {}) {
                         }
                         qualityTracker.recordToolUse(recoveryAction.type);
                         investigationState.recordToolUse(recoveryAction.type);
+                        // Feed the same evidence/work-item recording as
+                        // model actions so scheduler requirements actually
+                        // advance — otherwise the scheduler (a pure function
+                        // of unchanged state) re-proposes the identical
+                        // action and its already-burned fingerprint gets
+                        // rejected as a duplicate.
+                        recordActionEvidence(recoveryAction, stepsTaken, 'recovery');
                         if (recoveryMadeProgress) {
                             scanState.recovery.successfulRecoveryAttempts++;
                             scanState.recovery.consecutiveRecoveryFailures = 0;
@@ -1401,7 +1505,7 @@ async function runAgentScan(ctx, target, options = {}) {
                         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 {
+                        return closeRun({
                             status: 'incomplete',
                             findings: [],
                             transcript,
@@ -1413,13 +1517,23 @@ async function runAgentScan(ctx, target, options = {}) {
                             summary: 'Investigation incomplete — scheduler determined no executable work remains during recovery.',
                             investigationNotes: [],
                             coverageGaps: [],
-                        };
+                        });
                     }
                 }
             }
         }
     }
     catch (err) {
+        if (activeRunId) {
+            try {
+                await client.postJson('/agent/scan/close', {
+                    runId: activeRunId,
+                    status: 'failed',
+                    terminationReason: 'api_error',
+                }, options.signal);
+            }
+            catch { /* best-effort — janitor will expire the run */ }
+        }
         return {
             status: 'failed',
             findings: [],