@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/fix-history.js

@@ -0,0 +1,411 @@
+// Fix history — preview, apply, undo for auto-fixes.
+//
+// Every applied fix:
+//   1. Saves the original file contents to .agentic-security/fix-history/<id>.bak
+//   2. Records {findingId, file, originalSha256, appliedAt, ruleId} in
+//      .agentic-security/fix-history/log.json
+//
+// `agentic-security undo` reverts the most recent applied fix (or `--all`
+// to revert every fix in the log, in reverse order).
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+
+function historyDir(scanRoot) {
+  return path.join(scanRoot, '.agentic-security', 'fix-history');
+}
+function logPath(scanRoot) { return path.join(historyDir(scanRoot), 'log.json'); }
+
+function ensure(scanRoot) { fs.mkdirSync(historyDir(scanRoot), { recursive: true }); }
+
+export function readLog(scanRoot) {
+  const fp = logPath(scanRoot);
+  if (!fs.existsSync(fp)) return [];
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return []; }
+}
+function writeLog(scanRoot, log) {
+  ensure(scanRoot);
+  fs.writeFileSync(logPath(scanRoot), JSON.stringify(log, null, 2));
+}
+function sha(s) { return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16); }
+
+// Premortem 3R-12: cross-check helpers for last-scan.json. We look up
+// findings by `id` (the finding's canonical key from the engine) so we can
+// stash the corresponding stableId on the fix entry and verify in recover().
+function _lastScanPath(scanRoot) {
+  return path.join(scanRoot, '.agentic-security', 'last-scan.json');
+}
+function _readLastScan(scanRoot) {
+  const fp = _lastScanPath(scanRoot);
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+function _allFindings(scan) {
+  if (!scan || typeof scan !== 'object') return [];
+  return [
+    ...(scan.findings || []),
+    ...(scan.logicVulns || []),
+    ...(scan.secrets || []),
+    ...(scan.sca || []),
+    ...(scan.iac || []),
+  ];
+}
+function _lookupStableId(scanRoot, findingId) {
+  const scan = _readLastScan(scanRoot);
+  if (!scan) return null;
+  for (const f of _allFindings(scan)) {
+    if (f && f.id === findingId) return f.stableId || null;
+  }
+  return null;
+}
+function _findingStillPresent(scanRoot, entry) {
+  const scan = _readLastScan(scanRoot);
+  if (!scan) return null;  // unknown — caller treats as "skip cross-check"
+  for (const f of _allFindings(scan)) {
+    if (!f) continue;
+    if (entry.stableId && f.stableId && f.stableId === entry.stableId) return true;
+    if (entry.findingId && f.id === entry.findingId) return true;
+  }
+  return false;
+}
+
+// Premortem 3R-13: writing fix-history/log.json from concurrent
+// applyFix / recover() invocations can interleave and corrupt the JSON. We
+// use an exclusive (wx) lockfile under the history dir; whoever creates it
+// wins, others spin briefly. The lock is released in finally{}. Stale
+// locks > 30s are reaped on contention.
+async function _withLogLock(scanRoot, fn) {
+  ensure(scanRoot);
+  const lockPath = path.join(historyDir(scanRoot), 'log.lock');
+  const startedAt = Date.now();
+  const TIMEOUT_MS = 5000;
+  while (true) {
+    try {
+      const handle = await fsp.open(lockPath, 'wx');
+      await handle.writeFile(String(process.pid));
+      try { await handle.close(); } catch {}
+      try {
+        return await fn();
+      } finally {
+        try { await fsp.unlink(lockPath); } catch {}
+      }
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        // Premortem 4R-9: stale-lock reap is now PID-aware. We read the PID
+        // from the lock file and check whether the process still exists. If
+        // the PID is dead OR the lock is older than 30s AND the PID isn't
+        // alive, only THEN do we unlink. This prevents racing the unlink
+        // against a fresh lock from another process on flaky filesystems.
+        try {
+          const [st, pidStr] = await Promise.all([
+            fsp.stat(lockPath),
+            fsp.readFile(lockPath, 'utf8').catch(() => ''),
+          ]);
+          const pid = parseInt(pidStr.trim(), 10);
+          const pidAlive = Number.isFinite(pid) && _isProcessAlive(pid);
+          const old = Date.now() - st.mtimeMs > 30000;
+          if (!pidAlive || old) {
+            try {
+              // Atomic-ish reap: only unlink if the lockfile still contains
+              // the same PID we just read (i.e. nobody else replaced it).
+              const recheck = (await fsp.readFile(lockPath, 'utf8').catch(() => '')).trim();
+              if (recheck === pidStr.trim()) {
+                await fsp.unlink(lockPath);
+              }
+            } catch {}
+            continue;
+          }
+        } catch {}
+        if (Date.now() - startedAt > TIMEOUT_MS) {
+          throw new Error('fix-history: log lock timed out');
+        }
+        await new Promise(r => setTimeout(r, 25));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+function _isProcessAlive(pid) {
+  // POSIX: process.kill(pid, 0) probes existence without sending a signal.
+  // EPERM also means the process exists; only ESRCH means dead.
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}
+
+// Build a unified-diff-ish preview between two strings, with line numbers.
+// Not a real `diff -u`, but readable enough for the vibecoder use case.
+export function preview(originalContent, newContent, file) {
+  const a = originalContent.split('\n');
+  const b = newContent.split('\n');
+  const max = Math.max(a.length, b.length);
+  const out = [`--- ${file} (before)`, `+++ ${file} (after)`];
+  let firstDiff = -1, lastDiff = -1;
+  for (let i = 0; i < max; i++) {
+    if ((a[i] || '') !== (b[i] || '')) {
+      if (firstDiff < 0) firstDiff = i;
+      lastDiff = i;
+    }
+  }
+  if (firstDiff < 0) { out.push('(no changes)'); return out.join('\n'); }
+  const ctx = 3;
+  const start = Math.max(0, firstDiff - ctx);
+  const end = Math.min(max, lastDiff + ctx + 1);
+  for (let i = start; i < end; i++) {
+    const sa = a[i], sb = b[i];
+    if (sa === sb) out.push(`  ${String(i + 1).padStart(4)}  ${sa ?? ''}`);
+    else {
+      if (sa !== undefined) out.push(`- ${String(i + 1).padStart(4)}  ${sa}`);
+      if (sb !== undefined) out.push(`+ ${String(i + 1).padStart(4)}  ${sb}`);
+    }
+  }
+  return out.join('\n');
+}
+
+// Apply a fix and record it in history. Two-phase commit (premortem P2-9):
+//
+//   1. Write the backup file + fsync.
+//   2. Write the log with the entry marked status='pending' + fsync.
+//   3. Write the new file content + fsync.
+//   4. Update the log entry to status='applied' + fsync.
+//
+// If we crash between (1) and (3) — backup exists, log entry says 'pending',
+// file is untouched. `recover()` rolls forward by deleting the pending entry.
+// If we crash between (3) and (4) — backup exists, log entry says 'pending',
+// file IS the new content. `recover()` checks file hash; if it matches newSha
+// the entry is promoted to 'applied'; if it matches originalSha it's dropped.
+//
+// This guarantees the file is never modified without a corresponding
+// recoverable log entry.
+// Harness-engineering note (post-derived): hard step budget. The same
+// stableId / findingId can be attempted at most MAX_ATTEMPTS times before
+// the deterministic layer refuses. This prevents a misbehaving agent (or a
+// rule whose canonical fix is wrong for this codebase) from chewing through
+// turns retrying the same broken patch. Override via env var only — there
+// is no per-call override.
+const MAX_ATTEMPTS_PER_KEY = (() => {
+  const v = parseInt(process.env.AGENTIC_SECURITY_FIX_MAX_ATTEMPTS || '2', 10);
+  return Number.isFinite(v) && v >= 1 ? v : 2;
+})();
+
+export class FixAttemptBudgetExceededError extends Error {
+  constructor(key, attempts, max) {
+    super(`fix attempts for ${key} exceeded budget (${attempts} >= ${max}). The canonical fix is wrong for this codebase; surface to a human.`);
+    this.name = 'FixAttemptBudgetExceededError';
+    this.key = key; this.attempts = attempts; this.max = max;
+  }
+}
+
+function _countPriorAttempts(log, stableId, findingId) {
+  let n = 0;
+  for (const e of log) {
+    if (e.reverted) continue;   // a clean revert resets the count
+    if (stableId && e.stableId === stableId) { n++; continue; }
+    if (findingId && e.findingId === findingId) { n++; }
+  }
+  return n;
+}
+
+export async function applyFix({ scanRoot, file, originalContent, newContent, findingId, ruleId, vuln, stableId }) {
+  return _withLogLock(scanRoot, async () => {
+    ensure(scanRoot);
+    const absFile = path.resolve(scanRoot, file);
+    const id = `fix-${Date.now().toString(36)}-${sha(file + findingId).slice(0, 6)}`;
+    const bakPath = path.join(historyDir(scanRoot), `${id}.bak`);
+    const resolvedStableId = stableId || _lookupStableId(scanRoot, findingId);
+    // Budget check BEFORE backup, so we don't accumulate dead .bak files
+    // for refused attempts.
+    const priorLog = readLog(scanRoot);
+    const priorAttempts = _countPriorAttempts(priorLog, resolvedStableId, findingId);
+    if (priorAttempts >= MAX_ATTEMPTS_PER_KEY) {
+      throw new FixAttemptBudgetExceededError(
+        resolvedStableId || findingId || '(unknown-key)',
+        priorAttempts,
+        MAX_ATTEMPTS_PER_KEY,
+      );
+    }
+    // Phase 1: backup + fsync.
+    await _writeAndSync(bakPath, originalContent);
+    const entry = {
+      id,
+      findingId,
+      stableId: resolvedStableId || null,
+      ruleId: ruleId || null,
+      vuln: vuln || null,
+      file,
+      backupPath: path.relative(scanRoot, bakPath),
+      originalSha: sha(originalContent),
+      newSha: sha(newContent),
+      appliedAt: new Date().toISOString(),
+      status: 'pending',
+      reverted: false,
+      attemptOrdinal: priorAttempts + 1,
+    };
+    // Phase 2: log entry marked pending + fsync.
+    const log = priorLog;
+    log.push(entry);
+    await _writeLogAndSync(scanRoot, log);
+    // Phase 3: write the new content to the target file + fsync.
+    try {
+      await _writeAndSync(absFile, newContent);
+    } catch (e) {
+      entry.status = 'failed';
+      entry.error = e.message;
+      await _writeLogAndSync(scanRoot, log);
+      throw e;
+    }
+    // Phase 4: promote to applied.
+    entry.status = 'applied';
+    await _writeLogAndSync(scanRoot, log);
+    return entry;
+  });
+}
+
+async function _writeAndSync(fp, content) {
+  await fsp.mkdir(path.dirname(fp), { recursive: true });
+  const handle = await fsp.open(fp, 'w');
+  try {
+    await handle.writeFile(content);
+    if (typeof handle.sync === 'function') await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function _writeLogAndSync(scanRoot, log) {
+  ensure(scanRoot);
+  const fp = logPath(scanRoot);
+  const handle = await fsp.open(fp, 'w');
+  try {
+    await handle.writeFile(JSON.stringify(log, null, 2));
+    if (typeof handle.sync === 'function') await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+// Recover from a crash mid-applyFix. Reads the log, examines any 'pending'
+// entries, compares the file's current sha against entry.newSha / .originalSha,
+// and either promotes to 'applied' or drops the entry. Returns the recovered
+// entries.
+export async function recover(scanRoot) {
+  return _withLogLock(scanRoot, () => _recoverInner(scanRoot));
+}
+
+async function _recoverInner(scanRoot) {
+  const log = readLog(scanRoot);
+  const recovered = [];
+  for (const e of log) {
+    if (e.status !== 'pending') continue;
+    const absFile = path.resolve(scanRoot, e.file);
+    let curr;
+    try { curr = await fsp.readFile(absFile, 'utf8'); }
+    catch { e.status = 'failed'; e.error = 'file-missing'; recovered.push(e); continue; }
+    const currSha = sha(curr);
+    if (currSha === e.newSha) {
+      // Premortem 3R-12: before blindly promoting a pending fix to applied,
+      // cross-check that the finding is still recognized by last-scan.json.
+      // If last-scan was re-run during the crash and the issue has vanished
+      // (fixed externally, file refactored away), we record that ambiguity
+      // rather than tagging this as a successful auto-fix.
+      const stillPresent = _findingStillPresent(scanRoot, e);
+      if (stillPresent === false) {
+        e.status = 'applied-stale';
+        e.error = 'finding-not-in-last-scan';
+      } else {
+        e.status = 'applied';
+      }
+      e.recoveredAt = new Date().toISOString();
+      recovered.push(e);
+    } else if (currSha === e.originalSha) {
+      e.status = 'failed';
+      e.error = 'file-untouched-during-crash';
+      e.recoveredAt = new Date().toISOString();
+      recovered.push(e);
+    } else {
+      e.status = 'failed';
+      e.error = `file-content-mismatch-curr-sha=${currSha}`;
+      e.recoveredAt = new Date().toISOString();
+      recovered.push(e);
+    }
+  }
+  if (recovered.length) await _writeLogAndSync(scanRoot, log);
+  return recovered;
+}
+
+// Revert the most recent un-reverted fix. Returns the entry or null.
+export async function undoLast(scanRoot) {
+  return _withLogLock(scanRoot, async () => {
+    const log = readLog(scanRoot);
+    for (let i = log.length - 1; i >= 0; i--) {
+      if (!log[i].reverted) {
+        const entry = log[i];
+        const bak = path.resolve(scanRoot, entry.backupPath);
+        const absFile = path.resolve(scanRoot, entry.file);
+        if (!fs.existsSync(bak)) return { error: `backup missing: ${bak}` };
+        const original = await fsp.readFile(bak, 'utf8');
+        await fsp.writeFile(absFile, original);
+        entry.reverted = true;
+        entry.revertedAt = new Date().toISOString();
+        writeLog(scanRoot, log);
+        return entry;
+      }
+    }
+    return null;
+  });
+}
+
+// Revert everything that hasn't been reverted, in reverse order.
+export async function undoAll(scanRoot) {
+  const reverted = [];
+  let r;
+  while ((r = await undoLast(scanRoot)) && !r.error) reverted.push(r);
+  return reverted;
+}
+
+export function listHistory(scanRoot) { return readLog(scanRoot); }
+
+// Premortem 3R-17: fix-history/log.json grows monotonically. A long-running
+// project will accumulate thousands of entries over years. We compact by
+// archiving entries older than the retention window and reverted entries
+// to log-archive-<YYYY-MM>.json, leaving only "fresh" (active or recent)
+// entries in the active log. .bak files referenced by archived entries
+// can be optionally pruned (only when `--prune-backups` flag is set,
+// since their absence would break undo).
+export async function compactLog(scanRoot, opts = {}) {
+  return _withLogLock(scanRoot, async () => {
+    const retainDays = typeof opts.retainDays === 'number' ? opts.retainDays : 90;
+    const pruneBackups = !!opts.pruneBackups;
+    const cutoff = Date.now() - retainDays * 24 * 60 * 60 * 1000;
+    const log = readLog(scanRoot);
+    const keep = [];
+    const archive = [];
+    for (const e of log) {
+      const tsStr = e.recoveredAt || e.revertedAt || e.appliedAt;
+      const ts = tsStr ? Date.parse(tsStr) : Date.now();
+      const old = isFinite(ts) && ts < cutoff;
+      const terminal = e.reverted === true || e.status === 'failed' || e.status === 'applied-stale';
+      if (old && terminal) archive.push(e);
+      else keep.push(e);
+    }
+    if (archive.length) {
+      const month = new Date().toISOString().slice(0, 7);
+      const archivePath = path.join(historyDir(scanRoot), `log-archive-${month}.json`);
+      let prior = [];
+      try { prior = JSON.parse(await fsp.readFile(archivePath, 'utf8')); } catch { prior = []; }
+      await _writeAndSync(archivePath, JSON.stringify(prior.concat(archive), null, 2));
+      if (pruneBackups) {
+        for (const e of archive) {
+          if (!e.backupPath) continue;
+          const bak = path.resolve(scanRoot, e.backupPath);
+          try { await fsp.unlink(bak); } catch {}
+        }
+      }
+      await _writeLogAndSync(scanRoot, keep);
+    }
+    return { archived: archive.length, kept: keep.length };
+  });
+}

package/src/posture/fix-plan.js

@@ -0,0 +1,121 @@
+// Fix-plan emission for patches that exceed the safe-auto-apply bounds.
+//
+// PRD FR-FIX-1: a generated patch must touch ≤ 3 files and change ≤ 100 LoC.
+// FR-FIX-3: when those bounds are exceeded, emit a "fix plan" — a numbered
+// set of steps with file/line anchors — instead of an applyable patch.
+//
+// This module:
+//   - countPatchBounds(patch) → { files, loc, exceedsBounds }
+//   - renderFixPlan(finding, opts) → markdown string
+//   - emitFixPlanFile(scanRoot, finding, opts) → path to .agentic-security/fix-plans/<stableId>.md
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const MAX_FILES = 3;
+const MAX_LOC   = 100;
+
+// `patch` is a map { [file]: newContent } OR a unified-diff style string.
+// We accept the map form (what fix-verify uses) and the {file, replacement}
+// form (what apply_fix uses).
+export function countPatchBounds(patch, originalContents = {}) {
+  if (!patch) return { files: 0, loc: 0, exceedsBounds: false };
+  // Case 1: { [file]: newContent } map.
+  if (typeof patch === 'object' && !patch.replacement && !patch.code) {
+    const files = Object.keys(patch);
+    let loc = 0;
+    for (const f of files) {
+      const orig = originalContents[f] || '';
+      const nv = patch[f] || '';
+      loc += Math.abs(nv.split('\n').length - orig.split('\n').length);
+    }
+    return { files: files.length, loc, exceedsBounds: files.length > MAX_FILES || loc > MAX_LOC };
+  }
+  // Case 2: { file, replacement } single-file shape.
+  if (patch.replacement && patch.file) {
+    const orig = originalContents[patch.file] || '';
+    const loc = Math.abs(patch.replacement.split('\n').length - orig.split('\n').length);
+    return { files: 1, loc, exceedsBounds: loc > MAX_LOC };
+  }
+  return { files: 0, loc: 0, exceedsBounds: false };
+}
+
+// Render a markdown fix plan for a finding. The plan emits anchored steps
+// the engineer (or another Claude Code turn) can follow to implement the
+// architectural change manually.
+export function renderFixPlan(finding, opts = {}) {
+  const { reason = 'patch-exceeds-bounds', bounds = null } = opts;
+  const head = `# Fix plan: ${finding.vuln || 'finding'}\n\n`;
+  const meta = [
+    `**Stable ID:**  \`${finding.stableId || '(none)'}\``,
+    `**Severity:**   ${finding.severity || '?'}`,
+    `**CWE:**        ${finding.cwe || '(unmapped)'}`,
+    `**File:**       \`${finding.file || '?'}:${finding.line || '?'}\``,
+    `**Confidence:** ${finding.confidence ?? '?'}`,
+    `**Reason:**     ${reason}${bounds ? ` (touches ${bounds.files} files, Δ ${bounds.loc} LoC)` : ''}`,
+  ].join('  \n') + '\n\n';
+
+  const why = `## What this finding is\n\n${finding.description || finding.snippet || '(no description)'}\n\n`;
+
+  const remediation = typeof finding.remediation === 'string'
+    ? finding.remediation
+    : (finding.fix?.description || '(no remediation text on the finding)');
+
+  // Anchored steps — for non-architectural findings, this is a 3-step skeleton.
+  // The caller can elaborate by passing opts.steps[].
+  const steps = Array.isArray(opts.steps) && opts.steps.length ? opts.steps : [
+    {
+      title: `Locate the affected code`,
+      anchor: `${finding.file || '?'}:${finding.line || '?'}`,
+      detail: 'Open the file at the cited line and read ±10 lines of surrounding code so you understand the data flow.',
+    },
+    {
+      title: `Apply the per-rule remediation`,
+      anchor: null,
+      detail: remediation,
+    },
+    {
+      title: `Re-scan to confirm the finding is gone`,
+      anchor: null,
+      detail: 'Run `/scan` then check that the finding with the stable ID above is no longer present. If it persists, the patch did not address the root cause.',
+    },
+    {
+      title: `Run the project linter on the touched files`,
+      anchor: null,
+      detail: 'eslint / ruff / golangci-lint / checkstyle as appropriate. The auto-fixer also runs this gate before applying.',
+    },
+  ];
+
+  let body = '## Steps\n\n';
+  for (let i = 0; i < steps.length; i++) {
+    const s = steps[i];
+    body += `${i + 1}. **${s.title}**`;
+    if (s.anchor) body += `  \n   _Anchor:_ \`${s.anchor}\``;
+    if (s.detail) body += `  \n   ${s.detail.split('\n').join('\n   ')}`;
+    body += '\n\n';
+  }
+
+  const footer = `---\n_Generated by agentic-security. After implementing the steps, run \`/scan\` and (when clean) commit. To clear this plan, delete this file._\n`;
+  return head + meta + why + body + footer;
+}
+
+// Write a fix-plan markdown file to .agentic-security/fix-plans/.
+// Returns the absolute path of the written file, or null on error.
+export function emitFixPlanFile(scanRoot, finding, opts = {}) {
+  if (!scanRoot || !finding) return null;
+  const dir = path.join(scanRoot, '.agentic-security', 'fix-plans');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { return null; }
+  const id = finding.stableId || finding.id || `unknown-${Date.now().toString(36)}`;
+  const fp = path.join(dir, `${id}.md`);
+  try {
+    fs.writeFileSync(fp, renderFixPlan(finding, opts));
+    return fp;
+  } catch { return null; }
+}
+
+// Decide whether a finding warrants a fix-plan instead of an applyable patch.
+// Used by /fix-style flows. Returns the bounds so the caller can decide.
+export function shouldEmitFixPlan(finding, patch, originalContents) {
+  const bounds = countPatchBounds(patch, originalContents);
+  return { ...bounds, recommendsFixPlan: bounds.exceedsBounds };
+}

package/src/posture/fix-verify-loop.js

@@ -0,0 +1,157 @@
+// Closed-loop fix verification (v0.68).
+//
+// Existing `fix-verify.js` does scan + lint. This module adds the third
+// leg: run the project's test suite against the patched file set. A fix
+// is `verified-clean` only when:
+//
+//   1. Re-scan no longer fires the original finding's stableId
+//   2. No new ≥medium findings introduced
+//   3. Project linter (when present) passes on the patched files
+//   4. Project test runner (when present) exits 0 within budget
+//
+// If the project has no detected test runner, we emit `untested-but-passes`
+// rather than fail-closed — many small repos have no test suite and we
+// don't want to refuse all fixes there. The verdict is honest.
+//
+// Design note: we run the tests against the WRITTEN patch, not an in-
+// memory overlay — most real test runners can't be given an alternate
+// filesystem cheaply. Callers are expected to apply the patch first
+// (typically via fix-history.applyFix which creates a recovery backup),
+// then call this. If verification fails, undoLast() rolls back.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { verifyFix } from './fix-verify.js';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+// Test-runner discovery. Each entry: a sentinel-file check + a command +
+// args. Order matters — JS first (most common), then Python, Go, Rust,
+// Java/Maven, Java/Gradle, Ruby.
+function _detectRunner(scanRoot) {
+  const has = (p) => { try { return fs.existsSync(path.join(scanRoot, p)); } catch { return false; } };
+  const pkg = (() => {
+    try {
+      const raw = fs.readFileSync(path.join(scanRoot, 'package.json'), 'utf8');
+      return JSON.parse(raw);
+    } catch { return null; }
+  })();
+  if (pkg && pkg.scripts && pkg.scripts.test && !/no test specified/.test(String(pkg.scripts.test))) {
+    return { runner: 'npm', cmd: 'npm', args: ['test', '--silent', '--', '--passWithNoTests'] };
+  }
+  if (has('pytest.ini') || has('pyproject.toml') || has('setup.cfg')) {
+    return { runner: 'pytest', cmd: 'pytest', args: ['-q', '--no-header', '-x'] };
+  }
+  if (has('go.mod')) {
+    return { runner: 'go-test', cmd: 'go', args: ['test', './...'] };
+  }
+  if (has('Cargo.toml')) {
+    return { runner: 'cargo-test', cmd: 'cargo', args: ['test', '--quiet'] };
+  }
+  if (has('Gemfile')) {
+    return { runner: 'rspec', cmd: 'bundle', args: ['exec', 'rspec', '--fail-fast'] };
+  }
+  if (has('pom.xml')) {
+    return { runner: 'maven', cmd: 'mvn', args: ['-q', 'test', '-DfailIfNoTests=false'] };
+  }
+  if (has('build.gradle') || has('build.gradle.kts')) {
+    return { runner: 'gradle', cmd: './gradlew', args: ['test', '--quiet', '--no-daemon'] };
+  }
+  return null;
+}
+
+// Run the detected test runner. Honors a walltime budget. Caller may pass
+// `runnerOverride` to force a specific command (rare; mostly for tests).
+export function runProjectTests(scanRoot, opts = {}) {
+  if (!scanRoot) return { ok: true, runner: 'none', skipped: true };
+  const choice = opts.runnerOverride
+    ? { runner: opts.runnerOverride.cmd, cmd: opts.runnerOverride.cmd, args: opts.runnerOverride.args || [] }
+    : _detectRunner(scanRoot);
+  if (!choice) return { ok: true, runner: 'none', skipped: true, reason: 'no-test-runner-detected' };
+  const timeout = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+  let r;
+  try {
+    r = spawnSync(choice.cmd, choice.args, {
+      cwd: scanRoot,
+      encoding: 'utf8',
+      timeout,
+      env: { ...process.env, CI: '1' },
+    });
+  } catch (e) {
+    return { ok: false, runner: choice.runner, reason: 'spawn-failed', error: e.message };
+  }
+  if (r.error && r.error.code === 'ENOENT') {
+    // Runner not installed — different from "tests failed". Don't fail-closed.
+    return { ok: true, runner: choice.runner, skipped: true, reason: 'binary-missing' };
+  }
+  if (r.status === null) {
+    return {
+      ok: false, runner: choice.runner, reason: 'timed-out',
+      output: ((r.stderr || '') + (r.stdout || '')).slice(-2000),
+    };
+  }
+  return {
+    ok: r.status === 0,
+    runner: choice.runner,
+    exitCode: r.status,
+    output: ((r.stderr || '') + (r.stdout || '')).slice(-2000),
+  };
+}
+
+// Closed-loop verification: scan + lint + tests. Returns a single verdict
+// with per-leg detail so the caller can render a precise summary.
+//
+// Returns:
+//   {
+//     ok: bool,
+//     verdict: 'verified-clean' | 'verification-failed' | 'untested-but-passes',
+//     legs: { scan: …, lint: …, tests: … },
+//     summary: '<human-readable line>',
+//   }
+//
+// The `untested-but-passes` verdict is real and intentional: scan+lint
+// passed, but no test runner was found. This is honest signal — callers
+// (the security-fixer agent, downstream MCP tools) can decide whether to
+// require a stronger verdict.
+export async function verifyFixWithTests({
+  scanRoot,
+  originalFindingStableId,
+  files,
+  depFileContents,
+  runTests = true,
+  testRunnerOverride,
+  testTimeoutMs,
+} = {}) {
+  const scanLint = await verifyFix({ scanRoot, originalFindingStableId, files, depFileContents });
+  const legs = {
+    scan: { ok: scanLint.rescan?.ok ?? scanLint.ok, detail: scanLint.rescan ?? scanLint },
+    lint: { ok: scanLint.lint?.ok ?? true, detail: scanLint.lint ?? null },
+    tests: { ok: true, detail: null, skipped: true, reason: 'not-run' },
+  };
+  if (!legs.scan.ok || !legs.lint.ok) {
+    return {
+      ok: false,
+      verdict: 'verification-failed',
+      legs,
+      summary: _summarize(legs, 'verification-failed'),
+    };
+  }
+  if (runTests) {
+    const tests = runProjectTests(scanRoot, { runnerOverride: testRunnerOverride, timeoutMs: testTimeoutMs });
+    legs.tests = { ok: tests.ok, detail: tests, skipped: !!tests.skipped, reason: tests.reason };
+  }
+  const allOk = legs.scan.ok && legs.lint.ok && legs.tests.ok;
+  const verdict = !allOk
+    ? 'verification-failed'
+    : (legs.tests.skipped ? 'untested-but-passes' : 'verified-clean');
+  return { ok: allOk, verdict, legs, summary: _summarize(legs, verdict) };
+}
+
+function _summarize(legs, verdict) {
+  const bits = [];
+  bits.push(`scan: ${legs.scan.ok ? 'pass' : 'fail'}`);
+  bits.push(`lint: ${legs.lint.skipped ? 'skip' : legs.lint.ok ? 'pass' : 'fail'}`);
+  bits.push(`tests: ${legs.tests.skipped ? 'skip' : legs.tests.ok ? 'pass' : 'fail'}`);
+  return `${verdict} (${bits.join(' · ')})`;
+}