@securecode-ai/mcp 0.5.5 → 0.5.6

package/dist/tools/agentScan.js

@@ -51,20 +51,115 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolAgentScan = toolAgentScan;
+exports.confidenceCeilingForFinding = confidenceCeilingForFinding;
+exports.applyConfidenceClamp = applyConfidenceClamp;
 const client_1 = require("../api/client");
 const path = __importStar(require("path"));
 const files_1 = require("../utils/files");
 const mapContext_1 = require("../project-map/mapContext");
 const scanCache_1 = require("../project-map/scanCache");
 const agentMemory_1 = require("../project-map/agentMemory");
+const capabilityRegistry_1 = require("../project-map/capabilityRegistry");
+const cache_1 = require("../project-map/cache");
+const architectureContext_1 = require("../project-map/architectureContext");
 const agentScanLoop_1 = require("../attack/agentScanLoop");
 const verifyLoop_1 = require("../attack/verifyLoop");
+const fixVerifyLoop_1 = require("../attack/fixVerifyLoop");
+const agentScanProtocol_1 = require("../attack/agentScanProtocol");
+const localTestRunner_1 = require("../utils/localTestRunner");
+const broker_1 = require("../approval/broker");
+const gitContext_1 = require("../utils/gitContext");
+const blastRadius_1 = require("../project-map/blastRadius");
+const scanAuditLog_1 = require("../audit/scanAuditLog");
+const findingReviewQueue_1 = require("../audit/findingReviewQueue");
 /** Prove high/critical/medium findings — skip only low. */
 function shouldProve(finding) {
     return finding.severity === 'critical' || finding.severity === 'high' || finding.severity === 'medium';
 }
+/**
+ * Map a verification verdict to a precision verification level.
+ *
+ * PROVEN via local sandbox → exploit-confirmed (end-to-end test ran)
+ * PROVEN via API sandbox → impact-confirmed (server-side test ran)
+ * UNPROVEN → logic-confirmed (test proved behavior is safe)
+ * INCONCLUSIVE/SKIPPED → logic-confirmed (couldn't determine)
+ *
+ * If the finding already has a verificationLevel from the agent, keep the
+ * higher of the two (agent's level vs verify-mapped level).
+ */
+function mapVerificationLevel(proven, viaApiSandbox, agentLevel) {
+    let mapped;
+    if (proven === 'PROVEN') {
+        mapped = viaApiSandbox ? 'impact-confirmed' : 'exploit-confirmed';
+    }
+    else if (proven === 'UNPROVEN') {
+        mapped = 'logic-confirmed';
+    }
+    else {
+        mapped = 'logic-confirmed';
+    }
+    const order = ['logic-confirmed', 'path-confirmed', 'impact-confirmed', 'exploit-confirmed'];
+    if (agentLevel) {
+        const agentIdx = order.indexOf(agentLevel);
+        const mappedIdx = order.indexOf(mapped);
+        return agentIdx > mappedIdx ? agentLevel : mapped;
+    }
+    return mapped;
+}
+/**
+ * Map a verify loop sub-verdict to a human-readable review reason.
+ * Falls back to 'inconclusive-verification' when no specific reason is known.
+ */
+function mapToReviewReason(finding) {
+    const sv = finding.verifySubVerdict;
+    switch (sv) {
+        case 'sandbox-unavailable': return 'sandbox-unavailable';
+        case 'budget-exhausted': return 'verification-budget-exhausted';
+        case 'runtime-blocked': return 'runtime-blocked';
+        case 'cannot-test': return 'test-generation-failed';
+        case 'blocked': return 'runtime-blocked';
+        default: return 'inconclusive-verification';
+    }
+}
+/**
+ * Determine whether a finding should be queued for human review.
+ *
+ * Queue when:
+ *   - proven === 'INCONCLUSIVE' (verification couldn't decide)
+ *   - proven === 'SKIPPED' for medium/high/critical (intentionally skipped but
+ *     still potentially real)
+ *   - proven === 'UNPROVEN' but confidence remains high (≥60) — the LLM still
+ *     believes it's real despite the verify test not reproducing
+ *
+ * Do NOT queue:
+ *   - Low-severity SKIPPED findings (intentionally not verified)
+ *   - PROVEN findings (already confirmed by exploit)
+ *   - UNPROVEN findings with low confidence (likely false positive)
+ *   - Cancelled/aborted findings (user ended the scan)
+ */
+function shouldQueueForHumanReview(finding) {
+    if (finding.proven === 'PROVEN')
+        return false;
+    if (finding.proven === 'NOT_REPRODUCIBLE')
+        return false;
+    // Don't queue aborted/cancelled findings.
+    if (finding.verifySubVerdict === 'cancelled' || finding.verifySubVerdict === 'aborted') {
+        return false;
+    }
+    if (finding.proven === 'INCONCLUSIVE')
+        return true;
+    // SKIPPED: queue medium/high/critical, skip low.
+    if (finding.proven === 'SKIPPED') {
+        return finding.severity === 'critical' || finding.severity === 'high' || finding.severity === 'medium';
+    }
+    // UNPROVEN: queue only if high confidence remains after clamping.
+    if (finding.proven === 'UNPROVEN' && finding.confidence >= 60)
+        return true;
+    return false;
+}
 async function toolAgentScan(ctx, args) {
     const progress = args._progress;
+    const skipFix = !!args._skipFix;
     // 1. Resolve code + language
     let code;
     let language;
@@ -130,25 +225,121 @@ async function toolAgentScan(ctx, args) {
             // best-effort — proceed without context
         }
     }
-    // 2b. Check scan cache — if the file hasn't changed, return cached results
+    // 2a. Diff-aware blast radius scoping — if baseRef is provided, compute
+    // the set of changed files and their blast radius from the project map.
+    // The scope is passed to the agent target so the API prompt can guide
+    // the agent to focus on changed files and their dependents.
+    let scope;
+    const baseRef = args.baseRef;
+    if (baseRef) {
+        try {
+            const diffResult = await (0, gitContext_1.getGitChangedFiles)(ctx.workspaceRoot, baseRef, args.headRef);
+            if (diffResult.ok && diffResult.files.length > 0) {
+                let blastFiles = diffResult.files;
+                try {
+                    const map = await (0, mapContext_1.getMap)(ctx.workspaceRoot);
+                    if (map && map.files) {
+                        const blastResult = (0, blastRadius_1.computeBlastRadius)({
+                            changedFiles: diffResult.files,
+                            map,
+                        });
+                        blastFiles = blastResult.files;
+                    }
+                }
+                catch {
+                    // map not available — use just the changed files
+                }
+                scope = {
+                    changedFiles: diffResult.files,
+                    blastRadius: blastFiles,
+                    baseRef: diffResult.baseRef,
+                    headRef: diffResult.headRef,
+                };
+            }
+        }
+        catch {
+            // best-effort — proceed without scope
+        }
+    }
+    // 2b. Load workspace memory BEFORE the cache check.
+    //
+    // Memory (dismissed false positives + known facts) is part of the cache
+    // key now — a cache hit on an unchanged file must still respect findings
+    // the user has dismissed since the cache was written. We load memory
+    // first, compute its fingerprint, and:
+    //   - On cache hit with a matching fingerprint: return as-is.
+    //   - On cache hit with a different fingerprint (or no fingerprint, for
+    //     pre-v22 entries): filter the cached findings against current
+    //     memory before returning.
+    //   - On cache miss: pass the memory into the agent target as before.
+    let workspaceMemory;
+    let memoryFingerprint = '';
+    let falsePositives = [];
+    try {
+        const memory = (0, agentMemory_1.loadAgentMemory)(ctx.workspaceRoot);
+        workspaceMemory = (0, agentMemory_1.formatMemoryForPrompt)(memory) || undefined;
+        falsePositives = memory.falsePositives.map(fp => ({ findingType: fp.findingType, evidenceHash: fp.evidenceHash }));
+        memoryFingerprint = (0, scanCache_1.computeMemoryFingerprint)(falsePositives);
+        if (filePath) {
+            const fileHash = require('crypto').createHash('sha256').update(code).digest('hex').substring(0, 16);
+            (0, agentMemory_1.invalidateStaleEntries)(ctx.workspaceRoot, new Map([[filePath, fileHash]]));
+        }
+    }
+    catch {
+        // best-effort — proceed without memory
+    }
+    // 2c. Check scan cache — if the file hasn't changed, return cached results
     const skipCacheRead = !!args._noCache;
     const useCache = !!filePath;
     if (useCache && !skipCacheRead) {
         try {
             const cached = (0, scanCache_1.getCachedScan)(ctx.workspaceRoot, filePath, code);
             if (cached) {
+                // Filter against current memory. If the fingerprint matches
+                // what was stored at write time, no findings need to be
+                // dropped — we can return the cached list as-is. If it
+                // differs (or the entry predates memoryHash), filter.
+                let filteredFindings = cached.findings;
+                if (cached.memoryHash !== memoryFingerprint) {
+                    filteredFindings = (0, scanCache_1.filterCachedFindingsAgainstMemory)(cached.findings, falsePositives);
+                }
                 if (progress)
                     progress(1, 1, 'Cached result — file unchanged since last scan.');
+                try {
+                    const fileHash = require('crypto').createHash('sha256').update(code).digest('hex').substring(0, 16);
+                    (0, scanAuditLog_1.recordScanAuditSample)(ctx.workspaceRoot, {
+                        filePath: filePath,
+                        fileHash,
+                        language,
+                        scanStatus: cached.status,
+                        stepsUsed: cached.stepsUsed,
+                        costSpentUsd: 0,
+                        agentFindings: filteredFindings,
+                        transcript: [],
+                        cached: true,
+                    });
+                }
+                catch {
+                    // best-effort
+                }
                 return {
                     status: cached.status,
                     summary: cached.summary || 'Agent completed (cached).',
-                    agentFindings: cached.findings,
+                    agentFindings: filteredFindings,
                     findings: [],
+                    investigationNotes: cached.investigationNotes ?? [],
+                    coverageGaps: cached.coverageGaps ?? [],
                     stepsUsed: cached.stepsUsed,
+                    stepsGranted: cached.stepsGranted ?? 40,
+                    extensionsGranted: cached.extensionsGranted ?? 0,
                     costSpentUsd: 0,
                     transcript: [],
                     cached: true,
-                    provenCount: cached.findings.filter((f) => f.proven === 'PROVEN').length,
+                    provenCount: filteredFindings.filter((f) => f.proven === 'PROVEN').length,
+                    reviewQueue: {
+                        added: [],
+                        pendingCount: filteredFindings.filter((f) => f.reviewStatus === 'pending').length,
+                    },
                 };
             }
         }
@@ -159,14 +350,38 @@ async function toolAgentScan(ctx, args) {
         }
     }
     // 3. Run the agent loop
-    // Load workspace memory (false positives + known facts) to inject into target
-    let workspaceMemory;
-    try {
-        const memory = (0, agentMemory_1.loadAgentMemory)(ctx.workspaceRoot);
-        workspaceMemory = (0, agentMemory_1.formatMemoryForPrompt)(memory) || undefined;
-    }
-    catch {
-        // best-effort — proceed without memory
+    // (workspaceMemory was loaded above)
+    // 3b. Auto-load a cached architecture context (if present and valid)
+    // so the vulnerability investigator starts with project-wide context
+    // instead of having to discover "where is auth?", "what's the data
+    // layer?" from scratch. The architecture context is produced by
+    // `securecode.map action:architecture` and cached in
+    // .securecode/architecture-context.json. If it's stale or absent, the
+    // agent proceeds without it (no extra cost).
+    let architectureContextStr;
+    if (filePath) {
+        try {
+            const map = (0, cache_1.readCache)(ctx.workspaceRoot);
+            if (map) {
+                // Try each depth; 'standard' is the most common. The cache
+                // returns null if the entry is stale or missing.
+                for (const d of ['standard', 'deep', 'quick']) {
+                    const cached = (0, architectureContext_1.getCachedArchitectureContext)(ctx.workspaceRoot, d, map.builtAt, map.version);
+                    if (cached) {
+                        architectureContextStr = (0, architectureContext_1.formatArchitectureContextForPrompt)(cached);
+                        // Append architecture risk tasks specific to this target file
+                        const riskTasks = (0, architectureContext_1.formatArchitectureRiskTasksForTarget)(cached, filePath);
+                        if (riskTasks) {
+                            architectureContextStr = (architectureContextStr || '') + '\n\n' + riskTasks;
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            // best-effort — proceed without architecture context
+        }
     }
     const target = {
         filePath: filePath || 'inline-code',
@@ -174,6 +389,8 @@ async function toolAgentScan(ctx, args) {
         fileContent: code,
         endpointContext,
         workspaceMemory,
+        scope,
+        architectureContext: architectureContextStr,
     };
     const agentResult = await (0, agentScanLoop_1.runAgentScan)(ctx, target, {
         signal: args._signal,
@@ -188,6 +405,19 @@ async function toolAgentScan(ctx, args) {
     // 4. Verify each finding via the verify subagent (replaces sandbox prove + juror)
     const client = new client_1.ApiClient({ baseUrl: ctx.apiUrl, token: ctx.apiToken });
     const provenFindings = [];
+    // Aggregate verify budget — prevents Phase 2 from spawning unbounded
+    // LLM calls (8 rounds × N findings × 2 calls) and unbounded wall-clock.
+    const verifyBudget = (0, agentScanProtocol_1.defaultVerifyBudget)();
+    const verifyTracker = new agentScanProtocol_1.VerifyBudgetTracker(verifyBudget);
+    const abortSignal = args._signal;
+    // Track why findings ended up INCONCLUSIVE so the final result can
+    // surface one actionable hint instead of N identical per-finding
+    // reasons. The most common case on a developer's laptop is
+    // `sandbox-unavailable` (no Docker/Deno installed) — that gets a
+    // top-level `verifyHint` with install URLs so the user sees it once,
+    // at the top of the result, rather than buried in finding.reason.
+    let sandboxUnavailableCount = 0;
+    let budgetExhaustedCount = 0;
     const proveable = agentResult.findings.filter(shouldProve);
     if (proveable.length > 0 && progress) {
         progress(0, proveable.length, `Verifying ${proveable.length} finding(s)...`);
@@ -198,6 +428,20 @@ async function toolAgentScan(ctx, args) {
             provenFindings.push({ ...finding, proven: 'SKIPPED', provenReason: 'Low severity — not verified' });
             continue;
         }
+        // Pre-flight budget check — stop before spending any LLM calls if
+        // the aggregate is already exhausted. This is also enforced inside
+        // runVerifyLoop, but checking here lets us mark the finding SKIPPED
+        // with a clean reason instead of running INCONCLUSIVE.
+        if (!verifyTracker.canAttemptFinding()) {
+            budgetExhaustedCount++;
+            provenFindings.push({
+                ...finding,
+                proven: 'INCONCLUSIVE',
+                provenReason: `Verification budget exhausted (${verifyTracker.findingsAttempted}/${verifyBudget.maxFindings} findings, ${verifyTracker.llmCallsUsed}/${verifyBudget.maxLlmCalls} LLM calls, ${Math.round(verifyTracker.wallClockElapsedMs / 1000)}s/${Math.round(verifyBudget.maxWallClockMs / 1000)}s).`,
+                verifySubVerdict: 'budget-exhausted',
+            });
+            continue;
+        }
         if (progress) {
             proveIdx++;
             progress(proveIdx, proveable.length, `Verifying ${finding.type} at line ${finding.line}...`);
@@ -222,15 +466,77 @@ async function toolAgentScan(ctx, args) {
                 workspaceRoot: ctx.workspaceRoot,
                 language,
                 client,
+                budgetTracker: verifyTracker,
+                signal: abortSignal,
                 onProgress: (round, maxR, msg) => {
                     if (progress)
                         progress(proveIdx, proveable.length, `Verify round ${round}/${maxR}: ${msg}`);
                 },
             });
+            if (result.subVerdict === 'budget-exhausted')
+                budgetExhaustedCount++;
+            // User cancelled mid-verify: stop verifying further findings and
+            // mark the rest as SKIPPED so the report still includes them.
+            if (result.subVerdict === 'cancelled') {
+                provenFindings.push({
+                    ...finding,
+                    proven: result.verdict,
+                    provenReason: result.reason,
+                    verifySubVerdict: result.subVerdict,
+                });
+                for (const remaining of agentResult.findings.slice(agentResult.findings.indexOf(finding) + 1)) {
+                    provenFindings.push({
+                        ...remaining,
+                        proven: 'SKIPPED',
+                        provenReason: 'Scan cancelled by user — not verified.',
+                    });
+                }
+                break;
+            }
+            // No local sandbox (Docker/Deno) on the user's machine. Fall back to
+            // the API-side sandbox on Vultr, which has Docker installed. This
+            // gives every user exploit verification without a local install.
+            if (result.subVerdict === 'sandbox-unavailable') {
+                try {
+                    const proveResp = await client.postJson('/sandbox/prove', {
+                        code,
+                        language,
+                        vulnerabilityType: finding.type,
+                        line: finding.line,
+                        lineEnd: finding.lineEnd,
+                        evidence: finding.evidence,
+                        why: finding.why,
+                    });
+                    provenFindings.push({
+                        ...finding,
+                        proven: proveResp.proven,
+                        provenReason: proveResp.rationale || proveResp.skipReason || proveResp.sandbox?.reason,
+                        verifySubVerdict: result.subVerdict,
+                        verificationLevel: mapVerificationLevel(proveResp.proven, true, finding.verificationLevel),
+                        proofEvidence: proveResp.proofEvidence,
+                        proofGateResult: proveResp.proofGateResult,
+                    });
+                }
+                catch (proveErr) {
+                    sandboxUnavailableCount++;
+                    provenFindings.push({
+                        ...finding,
+                        proven: 'INCONCLUSIVE',
+                        provenReason: result.reason,
+                        verifySubVerdict: result.subVerdict,
+                        verificationLevel: mapVerificationLevel('INCONCLUSIVE', false, finding.verificationLevel),
+                    });
+                }
+                continue;
+            }
             provenFindings.push({
                 ...finding,
                 proven: result.verdict,
                 provenReason: result.reason,
+                verifySubVerdict: result.subVerdict,
+                verificationLevel: mapVerificationLevel(result.verdict, false, finding.verificationLevel),
+                proofEvidence: result.proofEvidence,
+                proofGateResult: result.proofGateResult,
             });
         }
         catch (err) {
@@ -249,6 +555,9 @@ async function toolAgentScan(ctx, args) {
                     ...finding,
                     proven: proveResp.proven,
                     provenReason: proveResp.rationale || proveResp.skipReason || proveResp.sandbox?.reason,
+                    verificationLevel: mapVerificationLevel(proveResp.proven, true, finding.verificationLevel),
+                    proofEvidence: proveResp.proofEvidence,
+                    proofGateResult: proveResp.proofGateResult,
                 });
             }
             catch (err2) {
@@ -256,70 +565,297 @@ async function toolAgentScan(ctx, args) {
                     ...finding,
                     proven: 'INCONCLUSIVE',
                     provenReason: `Verify failed: ${err.message}; Sandbox fallback also failed: ${err2.message}`,
+                    verificationLevel: mapVerificationLevel('INCONCLUSIVE', false, finding.verificationLevel),
                 });
             }
         }
     }
-    // 4b. Generate fixes for proven/suspected findings
-    const fixableFindings = provenFindings.filter(f => f.proven === 'PROVEN' || (f.proven !== 'UNPROVEN' && f.confidence >= 60));
-    if (fixableFindings.length > 0 && progress) {
-        progress(0, fixableFindings.length, `Generating fixes for ${fixableFindings.length} finding(s)...`);
+    // 4a. Capability-based confidence clamping
+    // Confidence must reflect what was actually proven, not what the LLM believes.
+    // A finding with no structural evidence (no taint trace, no guard check, no
+    // verify) cannot be reported at 95% confidence — that's how false positives
+    // erode trust in a security tool. The clamp is deterministic and based on:
+    //   1. What tools the agent actually used (transcript scan)
+    //   2. What tools were available for this language (capability registry)
+    //   3. The verify subagent's verdict (PROVEN/UNPROVEN/INCONCLUSIVE)
+    clampConfidenceByCapability(provenFindings, agentResult.transcript, language);
+    // 4a-ter. Mark findings requiring human review based on proof quality.
+    for (const finding of provenFindings) {
+        if (finding.proven !== 'PROVEN')
+            continue;
+        const needsReview = finding.severity === 'critical' ||
+            (finding.proofEvidence && finding.proofEvidence.assumptions.length > 0) ||
+            !finding.proofEvidence ||
+            !finding.proofGateResult ||
+            !finding.proofGateResult.eligibleForProven;
+        finding.humanReviewRequired = needsReview;
     }
-    let fixIdx = 0;
-    for (const finding of fixableFindings) {
-        if (progress) {
-            fixIdx++;
-            progress(fixIdx, fixableFindings.length, `Fixing ${finding.type} at line ${finding.line}...`);
+    // 4a-bis. Queue INCONCLUSIVE findings for non-blocking human review.
+    //
+    // Findings the verify subagent couldn't prove or disprove are added to a
+    // local review queue (.securecode/finding-review-queue.json). The scan
+    // does NOT block — the user can later adjudicate each item via the
+    // securecode.review-findings and securecode.decide-finding MCP tools.
+    // Only findings with a real file path are queued (inline-code scans have
+    // no persistent location to review).
+    const reviewQueueAdded = [];
+    if (filePath) {
+        for (const finding of provenFindings) {
+            if (!shouldQueueForHumanReview(finding))
+                continue;
+            try {
+                const reviewItem = (0, findingReviewQueue_1.enqueueFindingReview)(ctx.workspaceRoot, {
+                    workspaceRelativePath: filePath,
+                    fileContent: code,
+                    line: finding.line,
+                    lineEnd: finding.lineEnd,
+                    findingType: finding.type,
+                    severity: finding.severity,
+                    confidence: finding.confidence,
+                    proven: finding.proven,
+                    reviewReason: mapToReviewReason(finding),
+                    verificationReason: finding.provenReason,
+                    evidence: finding.evidence || '',
+                });
+                finding.reviewStatus = 'pending';
+                finding.reviewId = reviewItem.id;
+                reviewQueueAdded.push(reviewItem.id);
+            }
+            catch (reviewErr) {
+                // Review queue persistence failure must not block the scan.
+                console.warn(`[Agent Scan] Review queue enqueue failed: ${reviewErr?.message || reviewErr}`);
+            }
         }
+    }
+    // 4b. Generate fixes for proven/suspected findings (requires approval)
+    if (skipFix) {
+        console.log('[Agent Scan] Skipping fix generation (_skipFix=true)');
+    }
+    else {
+        const fixableFindings = provenFindings.filter(f => f.proven === 'PROVEN' || (f.proven !== 'UNPROVEN' && f.confidence >= 60));
+        if (fixableFindings.length > 0 && progress) {
+            progress(0, fixableFindings.length, `Generating fixes for ${fixableFindings.length} finding(s)...`);
+        }
+        let fixIdx = 0;
+        const fixBroker = fixableFindings.length > 0 ? new broker_1.ApprovalBroker() : null;
+        if (fixBroker)
+            await fixBroker.start();
         try {
-            const fixResp = await client.postJson('/fix', {
-                code,
-                language,
-                vulnerability: {
-                    type: finding.type,
-                    line_start: finding.line,
-                    line_end: finding.lineEnd || finding.line,
-                    evidence_snippet: finding.evidence,
-                },
-            });
-            if (fixResp.fixed_code) {
-                finding.fix = {
-                    fixedCode: fixResp.fixed_code,
-                    replaceRange: { start_line: finding.line, end_line: finding.lineEnd || finding.line },
-                    fixSummary: fixResp.fix_summary || '',
-                    importsNeeded: fixResp.imports_needed,
-                    confidence: fixResp.confidence,
-                };
+            for (const finding of fixableFindings) {
+                if (progress) {
+                    fixIdx++;
+                    progress(fixIdx, fixableFindings.length, `Fixing ${finding.type} at line ${finding.line}...`);
+                }
+                const fixSummary = `Generate fix for ${finding.type} at line ${finding.line}${finding.lineEnd ? `-${finding.lineEnd}` : ''}\nSeverity: ${finding.severity} | Confidence: ${finding.confidence}%\nEvidence: ${finding.evidence?.substring(0, 200) || '(none)'}`;
+                try {
+                    const approval = await fixBroker.requestApproval('securecode.agent-scan (fix generation)', fixSummary, [code, language, finding.type, finding.line, finding.lineEnd, finding.evidence, finding.severity, finding.confidence], 60_000, 'paid-generation', ctx.workspaceRoot);
+                    if (!approval.approved) {
+                        finding.fixStatus = 'fix-denied';
+                        finding.fixDeniedReason = approval.reason;
+                        continue;
+                    }
+                    const fixResp = await client.postJson('/fix', {
+                        code,
+                        language,
+                        vulnerability: {
+                            type: finding.type,
+                            line_start: finding.line,
+                            line_end: finding.lineEnd || finding.line,
+                            evidence_snippet: finding.evidence,
+                        },
+                    });
+                    if (fixResp.fixed_code) {
+                        finding.fix = {
+                            fixedCode: fixResp.fixed_code,
+                            replaceRange: { start_line: finding.line, end_line: finding.lineEnd || finding.line },
+                            fixSummary: fixResp.fix_summary || '',
+                            importsNeeded: fixResp.imports_needed,
+                            confidence: fixResp.confidence,
+                        };
+                        finding.fixStatus = 'fix-generated';
+                        finding.fixApprovalId = approval.requestId;
+                        // 4c. Re-verify the fix — re-run the exploit against the
+                        // merged fixed code to prove the fix actually closed the
+                        // vulnerability. Uses a separate, smaller budget so a
+                        // single fix verification cannot consume the entire
+                        // original scan verification budget. No second approval
+                        // needed: the user already approved fix generation, and
+                        // this runs inside the existing sandbox without modifying
+                        // any workspace files.
+                        try {
+                            if (progress) {
+                                progress(fixIdx, fixableFindings.length, `Verifying fix for ${finding.type} at line ${finding.line}...`);
+                            }
+                            const fixVerifyBudget = (0, agentScanProtocol_1.defaultFixVerifyBudget)();
+                            const fixVerifyTracker = new agentScanProtocol_1.VerifyBudgetTracker(fixVerifyBudget);
+                            const fixVerifyResult = await (0, fixVerifyLoop_1.runFixVerifyLoop)({
+                                finding: {
+                                    type: finding.type,
+                                    line: finding.line,
+                                    lineEnd: finding.lineEnd,
+                                    evidence: finding.evidence,
+                                    why: finding.why,
+                                    severity: finding.severity,
+                                },
+                                originalCode: code,
+                                fixedCode: fixResp.fixed_code,
+                                replaceRange: { start_line: finding.line, end_line: finding.lineEnd || finding.line },
+                                filePath: filePath || '',
+                                relatedFiles: relatedFiles.map(rf => ({
+                                    filePath: rf.filePath,
+                                    content: rf.content,
+                                    relationship: rf.relationship,
+                                })),
+                                workspaceRoot: ctx.workspaceRoot,
+                                language,
+                                client,
+                                originalVerdict: finding.proven,
+                                budgetTracker: fixVerifyTracker,
+                                signal: abortSignal,
+                                onProgress: (round, maxR, msg) => {
+                                    if (progress)
+                                        progress(fixIdx, fixableFindings.length, `Fix verify round ${round}/${maxR}: ${msg}`);
+                                },
+                            });
+                            finding.fixVerification = fixVerifyResult;
+                            // Map the fix verification status to the fixStatus field.
+                            switch (fixVerifyResult.status) {
+                                case 'closed':
+                                    finding.fixStatus = 'fix-verified-closed';
+                                    break;
+                                case 'still-vulnerable':
+                                    finding.fixStatus = 'fix-still-vulnerable';
+                                    break;
+                                case 'inconclusive':
+                                    finding.fixStatus = 'fix-verification-inconclusive';
+                                    break;
+                                case 'syntax-invalid':
+                                    finding.fixStatus = 'fix-syntax-invalid';
+                                    break;
+                                // sandbox-unavailable and cancelled leave fixStatus as 'fix-generated'
+                            }
+                        }
+                        catch (fixVerifyErr) {
+                            // Fix verification failure must not block the scan — the
+                            // fix is still generated, just not re-verified.
+                            console.warn(`[Agent Scan] Fix verification failed for ${finding.type} at L${finding.line}: ${fixVerifyErr?.message || fixVerifyErr}`);
+                        }
+                    }
+                }
+                catch (err) {
+                    finding.fixStatus = 'fix-error';
+                    finding.fixDeniedReason = err.message;
+                    console.warn(`[Agent Scan] Fix generation failed for ${finding.type} at L${finding.line}: ${err.message}`);
+                }
             }
         }
-        catch (err) {
-            // Best-effort — finding stays without fix
-            console.warn(`[Agent Scan] Fix generation failed for ${finding.type} at L${finding.line}: ${err.message}`);
+        finally {
+            if (fixBroker)
+                await fixBroker.stop();
         }
-    }
+    } // end else (skipFix)
     // 5. Write to cache before returning
     if (useCache) {
         try {
             (0, scanCache_1.writeCachedScan)(ctx.workspaceRoot, filePath, code, {
                 findings: provenFindings,
+                investigationNotes: agentResult.investigationNotes,
+                coverageGaps: agentResult.coverageGaps,
                 status: agentResult.status,
                 summary: agentResult.summary,
                 stepsUsed: agentResult.stepsUsed,
+                stepsGranted: agentResult.stepsGranted,
+                extensionsGranted: agentResult.extensionsGranted,
                 costSpentUsd: agentResult.costSpentUsd,
-            });
+            }, memoryFingerprint);
         }
         catch (err) {
             console.warn(`[Agent Scan] Cache write skipped: ${err?.message || err}`);
         }
     }
     // 6. Return result — the verify subagent IS the verifier (no separate Juror call)
+    //
+    // verifyHint: surfaced once at the top level when one or more findings
+    // couldn't be exploit-verified. The local sandbox (Docker/Deno) was
+    // unavailable AND the API-side sandbox fallback failed — so the finding
+    // got INCONCLUSIVE. The hint tells the user what to install for local
+    // verification (faster, no round-trip) and reminds them the API sandbox
+    // is the automatic fallback.
+    let verifyHint;
+    if (sandboxUnavailableCount > 0) {
+        verifyHint = `Exploit verification was skipped for ${sandboxUnavailableCount} finding(s). No local sandbox (Docker or Deno) was detected and the API-side sandbox was unavailable. Findings are reported as INCONCLUSIVE with confidence capped at 75%.\n${localTestRunner_1.SANDBOX_UNAVAILABLE_MESSAGE}`;
+    }
+    else if (budgetExhaustedCount > 0) {
+        verifyHint = `Exploit verification was skipped for ${budgetExhaustedCount} finding(s) because the per-scan verification budget (${verifyBudget.maxFindings} findings, ${verifyBudget.maxLlmCalls} LLM calls, ${Math.round(verifyBudget.maxWallClockMs / 1000)}s) was exhausted. Re-run the scan to verify the remaining findings, or raise the budget via the VerifyBudget config.`;
+    }
+    // 6a. Record metadata-only audit sample (no source code, no evidence strings)
+    try {
+        const fileHash = require('crypto').createHash('sha256').update(code).digest('hex').substring(0, 16);
+        (0, scanAuditLog_1.recordScanAuditSample)(ctx.workspaceRoot, {
+            filePath: filePath || 'inline-code',
+            fileHash,
+            language,
+            scanStatus: agentResult.status,
+            stepsUsed: agentResult.stepsUsed,
+            costSpentUsd: agentResult.costSpentUsd,
+            agentFindings: provenFindings,
+            transcript: agentResult.transcript,
+            cached: false,
+            verifyUsage: {
+                findingsAttempted: verifyTracker.findingsAttempted,
+                roundsUsed: verifyTracker.roundsUsed,
+                llmCallsUsed: verifyTracker.llmCallsUsed,
+                costSpentUsd: verifyTracker.costSpentUsd,
+                wallClockMs: verifyTracker.wallClockElapsedMs,
+            },
+            scope,
+            investigationNotes: agentResult.investigationNotes,
+            coverageGaps: agentResult.coverageGaps,
+            hasArchitectureContext: !!architectureContextStr,
+            stepsGranted: agentResult.stepsGranted,
+            extensionsGranted: agentResult.extensionsGranted,
+            terminationReason: agentResult.terminationReason,
+        });
+    }
+    catch {
+        // best-effort — audit failure must not block scan results
+    }
+    // 6b. Persist investigation notes and coverage gaps to workspace memory
+    // so future scans can use them as context. These are NOT findings —
+    // they guide future investigation without suppressing new discoveries.
+    try {
+        const fileHashes = new Map();
+        if (filePath) {
+            fileHashes.set(filePath, require('crypto').createHash('sha256').update(code).digest('hex').substring(0, 16));
+        }
+        if (agentResult.investigationNotes && agentResult.investigationNotes.length > 0) {
+            (0, agentMemory_1.saveInvestigationNotes)(ctx.workspaceRoot, {
+                notes: agentResult.investigationNotes,
+                fileHashes,
+            });
+        }
+        if (agentResult.coverageGaps && agentResult.coverageGaps.length > 0) {
+            (0, agentMemory_1.saveCoverageGaps)(ctx.workspaceRoot, {
+                gaps: agentResult.coverageGaps,
+                fileHashes,
+            });
+        }
+    }
+    catch {
+        // best-effort — memory persistence failure must not block results
+    }
     return {
         status: agentResult.status,
         summary: agentResult.summary,
         agentFindings: provenFindings,
         verifiedFindings: provenFindings.filter(f => f.proven === 'PROVEN'),
         allFindings: [],
+        investigationNotes: agentResult.investigationNotes ?? [],
+        coverageGaps: agentResult.coverageGaps ?? [],
         stepsUsed: agentResult.stepsUsed,
+        stepsGranted: agentResult.stepsGranted,
+        extensionsGranted: agentResult.extensionsGranted,
+        terminationReason: agentResult.terminationReason,
         costSpentUsd: agentResult.costSpentUsd,
         transcript: agentResult.transcript,
         provenCount: provenFindings.filter(f => f.proven === 'PROVEN').length,
@@ -327,6 +863,129 @@ async function toolAgentScan(ctx, args) {
         inconclusiveCount: provenFindings.filter(f => f.proven === 'INCONCLUSIVE').length,
         notReproducibleCount: provenFindings.filter(f => f.proven === 'NOT_REPRODUCIBLE').length,
         skippedCount: provenFindings.filter(f => f.proven === 'SKIPPED').length,
+        verifyHint,
+        verifyUsage: {
+            findingsAttempted: verifyTracker.findingsAttempted,
+            roundsUsed: verifyTracker.roundsUsed,
+            llmCallsUsed: verifyTracker.llmCallsUsed,
+            costSpentUsd: verifyTracker.costSpentUsd,
+            wallClockMs: verifyTracker.wallClockElapsedMs,
+            budget: verifyBudget,
+        },
+        reviewQueue: {
+            added: reviewQueueAdded,
+            pendingCount: provenFindings.filter(f => f.reviewStatus === 'pending').length,
+        },
     };
 }
+function clampConfidenceByCapability(findings, transcript, language) {
+    const cap = (0, capabilityRegistry_1.getCapability)(language);
+    let usedTaint = false;
+    let usedGuard = false;
+    let usedPolicy = false;
+    for (const step of transcript) {
+        const t = step.action.type;
+        if (t === 'trace_flow' || t === 'trace_flow_cross_file')
+            usedTaint = true;
+        if (t === 'check_guard')
+            usedGuard = true;
+        if (t === 'check_policy')
+            usedPolicy = true;
+    }
+    let evidenceTools = 0;
+    if (usedTaint)
+        evidenceTools++;
+    if (usedGuard)
+        evidenceTools++;
+    if (usedPolicy)
+        evidenceTools++;
+    for (const f of findings) {
+        const original = f.confidence;
+        const ceiling = confidenceCeilingForFinding(f.proven, cap.tier, evidenceTools);
+        // The ceiling is the maximum allowed confidence for this verdict +
+        // capability combination. PROVEN findings have no ceiling (undefined)
+        // — they're already proven, let the LLM's confidence stand (but still
+        // floor at 80 because PROVEN should look confident).
+        let clamped = original;
+        if (ceiling !== undefined) {
+            clamped = Math.min(clamped, ceiling);
+        }
+        // PROVEN floor — a finding verified by exploit test should not
+        // display with a wishy-washy 40% confidence; if the agent is unsure
+        // about a PROVEN finding, the proof overrules the agent's doubt.
+        if (f.proven === 'PROVEN') {
+            clamped = Math.max(clamped, 80);
+        }
+        clamped = Math.round(clamped);
+        f.evidenceLevel = (0, capabilityRegistry_1.evidenceLevelTag)(usedTaint, usedGuard, usedPolicy, f.proven);
+        if (clamped !== original) {
+            f.originalConfidence = original;
+            f.confidence = clamped;
+        }
+    }
+}
+/**
+ * Explicit confidence-ceiling policy for a finding, based on:
+ *   - the verify verdict (PROVEN / UNPROVEN / INCONCLUSIVE /
+ *     NOT_REPRODUCIBLE / SKIPPED)
+ *   - the language capability tier (deep / standard / fallback)
+ *   - how many structural evidence tools the agent actually used
+ *     (trace_flow, check_guard, check_policy)
+ *
+ * Returns `undefined` for PROVEN (no ceiling — the proof overrules the
+ * LLM's belief). For everything else, returns the maximum allowed
+ * confidence. The caller takes `Math.min(confidence, ceiling)` so multiple
+ * applicable bounds compose correctly — last-write-wins is impossible.
+ *
+ * Verdict semantics:
+ *   - PROVEN: exploit test ran and reproduced the vulnerability. Strong
+ *     evidence. No ceiling; floor at 80.
+ *   - UNPROVEN: exploit test ran and did NOT reproduce. The finding is
+ *     likely a false positive. Hard cap at 25.
+ *   - NOT_REPRODUCIBLE: exploit test ran, but the test setup couldn't
+ *     trigger the vulnerability (e.g. the path requires a live DB). This
+ *     is NOT the same as UNPROVEN (which actively disproved) and NOT the
+ *     same as INCONCLUSIVE (which couldn't even run a test). Treat it as
+ *     "we tried and couldn't confirm" — cap at 35, tighter than
+ *     INCONCLUSIVE but looser than UNPROVEN.
+ *   - INCONCLUSIVE: no test could be generated or the sandbox was
+ *     unavailable. The finding is unverified — keep the LLM's confidence
+ *     but cap it based on structural evidence (no tools → ≤40, ≥2 tools
+ *     → ≤75). Fallback-tier languages get ≤55 across the board.
+ *   - SKIPPED: low severity, we didn't even try. Same as INCONCLUSIVE.
+ */
+function confidenceCeilingForFinding(verdict, capabilityTier, evidenceTools) {
+    switch (verdict) {
+        case 'PROVEN':
+            return undefined;
+        case 'UNPROVEN':
+            return 25;
+        case 'NOT_REPRODUCIBLE':
+            return 35;
+        case 'INCONCLUSIVE':
+        case 'SKIPPED':
+            if (capabilityTier === 'fallback')
+                return 55;
+            if (evidenceTools === 0)
+                return 40;
+            if (evidenceTools === 1)
+                return 60;
+            return 75;
+        default:
+            return 40;
+    }
+}
+/**
+ * Apply the confidence clamp to a single finding. Exported for testing
+ * so the test imports the real policy, not a copy that can drift.
+ */
+function applyConfidenceClamp(original, verdict, capabilityTier, evidenceTools) {
+    const ceiling = confidenceCeilingForFinding(verdict, capabilityTier, evidenceTools);
+    let clamped = original;
+    if (ceiling !== undefined)
+        clamped = Math.min(clamped, ceiling);
+    if (verdict === 'PROVEN')
+        clamped = Math.max(clamped, 80);
+    return Math.round(clamped);
+}
 //# sourceMappingURL=agentScan.js.map