@clear-capabilities/agentic-security-scanner 0.127.0 → 0.128.1

package/src/posture/fix-honesty-gate.js

@@ -0,0 +1,175 @@
+// Deterministic honesty gates on fix / finding output (#7).
+//
+// The project's verification discipline (scanner/CLAUDE.md) exists because
+// several releases shipped broken or false because work was reported as done
+// without confirming the artifact changed. Two of those failure modes are
+// *textual* — they live in the prose an agent emits alongside a fix — and can
+// be caught deterministically, with no LLM and no network:
+//
+//   1. Hand-wave residual-risk prose. "The input is adequately handled",
+//      "future work", "tbd", "later" — vague assurances that claim safety
+//      without naming a concrete remaining vector. A residual you can't name
+//      is a residual you're guessing about; reject the guess.
+//
+//   2. An unbacked "this is a false positive / provably safe" verdict. Marking
+//      a finding safe is a coverage *reduction* — it must cite a `file:line`
+//      that shows why, exactly like the rules-override gate refuses to silently
+//      shrink coverage.
+//
+// Plus a conservative fix-tier classifier so a partial remediation can never be
+// labelled FULL: any workaround-only signal (rate-limit, docs, log-without-
+// reject) is WORKAROUND; anything short of (sink signature changed + all callers
+// routed + a discriminating test) is at most MITIGATION; only the full set with
+// no partial-sanitization caveat earns FULL.
+//
+// Pure functions, no side effects, no throwing — safe to call from a command,
+// a hook, or the MCP verify_fix path.
+
+// Vague-assurance phrases that a real residual must never hide behind. Matched
+// case-insensitively with word boundaries so "later" doesn't trip on
+// "collateral" and "tbd" doesn't trip on a longer token.
+const BANNED_RESIDUAL_PHRASES = Object.freeze([
+  'adequately handled',
+  'adequately handles',
+  'properly validated',
+  'properly handled',
+  'handled properly',
+  'handled safely',
+  'future work',
+  'more work needed',
+  'to be done',
+  'tbd',
+  'later',
+]);
+
+// A citation shaped like `file:line` — one or more non-space, non-colon chars,
+// a colon, then digits. Unanchored: it need only appear somewhere in the item.
+const CITATION_RE = /[^\s:]+:\d+/;
+
+// Verdicts that assert the finding is not real and therefore demand a citation.
+// Compared after normalizing separators (`_`/space → `-`) and lowercasing, so
+// FALSE_POSITIVE, false-positive, and "provably safe" all land here.
+const FP_VERDICTS = Object.freeze(new Set(['false-positive', 'provably-safe', 'safe']));
+
+function _escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Reject vague-assurance / hand-wave residual-risk prose.
+ *
+ * An empty or whitespace-only residual is ok — there is no residual to lie
+ * about. A non-empty residual is rejected when it contains any banned phrase;
+ * each match yields one violation naming the offending phrase.
+ *
+ * @param {string} residualText
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function checkResidualHonesty(residualText) {
+  const text = typeof residualText === 'string' ? residualText : '';
+  if (text.trim() === '') return { ok: true, violations: [] };
+
+  const violations = [];
+  for (const phrase of BANNED_RESIDUAL_PHRASES) {
+    const re = new RegExp(`\\b${_escapeRe(phrase)}\\b`, 'i');
+    if (re.test(text)) {
+      violations.push(`vague-assurance phrase: "${phrase}"`);
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+
+function _isCitation(item) {
+  if (typeof item === 'string') return CITATION_RE.test(item);
+  if (item && typeof item === 'object' && typeof item.location === 'string') {
+    return CITATION_RE.test(item.location);
+  }
+  return false;
+}
+
+function _normalizeVerdict(verdict) {
+  return String(verdict).trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+
+/**
+ * Require a file:line citation behind a "this is not real" verdict.
+ *
+ * For a false-positive / provably-safe / safe verdict (case-insensitive; also
+ * accepts FALSE_POSITIVE), at least one evidence item must be a `file:line`
+ * citation — either a string matching /[^\s:]+:\d+/ or an object
+ * `{ location: "file:line" }`. Any other verdict passes unconditionally.
+ *
+ * @param {string} verdict
+ * @param {Array|string|object} evidence
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function requireCitedEvidence(verdict, evidence) {
+  if (typeof verdict !== 'string' || !FP_VERDICTS.has(_normalizeVerdict(verdict))) {
+    return { ok: true, violations: [] };
+  }
+  const items = Array.isArray(evidence)
+    ? evidence
+    : evidence == null
+      ? []
+      : [evidence];
+  if (items.some(_isCitation)) return { ok: true, violations: [] };
+  return {
+    ok: false,
+    violations: ['false-positive/safe verdict requires a file:line citation'],
+  };
+}
+
+/**
+ * Classify a fix into FULL | MITIGATION | WORKAROUND, conservative-first.
+ *
+ * @param {object} signals
+ * @param {boolean} signals.sinkSignatureChanged
+ * @param {boolean} signals.allCallersRouted
+ * @param {boolean} signals.testDiscriminates - a test that fails pre-fix, passes post-fix
+ * @param {boolean} [signals.rateLimitOnly]
+ * @param {boolean} [signals.docsOnly]
+ * @param {boolean} [signals.logOnlyNoReject]
+ * @param {boolean} [signals.partialSanitization]
+ * @returns {'FULL'|'MITIGATION'|'WORKAROUND'}
+ */
+export function computeFixTier(signals) {
+  const s = signals && typeof signals === 'object' ? signals : {};
+  if (s.rateLimitOnly || s.docsOnly || s.logOnlyNoReject) return 'WORKAROUND';
+  const complete = s.sinkSignatureChanged && s.allCallersRouted && s.testDiscriminates;
+  if (s.partialSanitization || !complete) return 'MITIGATION';
+  return 'FULL';
+}
+
+/**
+ * Compose the three gates for a single fix's output.
+ *
+ * ok = residual-honesty ok AND evidence-citation ok, further constrained by the
+ * tier/residual consistency invariant:
+ *   - a FULL tier must NOT carry a residual (a full fix has nothing left);
+ *   - a non-FULL tier MUST document a residual (say what's still open).
+ *
+ * @param {{ residual?: string, verdict?: string, evidence?: any, signals?: object }} input
+ * @returns {{ ok: boolean, tier: string, violations: string[] }}
+ */
+export function gateFixOutput({ residual, verdict, evidence, signals } = {}) {
+  const tier = computeFixTier(signals);
+  const residualCheck = checkResidualHonesty(residual);
+  const evidenceCheck = requireCitedEvidence(verdict, evidence);
+
+  const violations = [...residualCheck.violations, ...evidenceCheck.violations];
+  let ok = residualCheck.ok && evidenceCheck.ok;
+
+  const residualEmpty = typeof residual !== 'string' || residual.trim() === '';
+  if (tier === 'FULL' && !residualEmpty) {
+    violations.push('FULL tier cannot carry a residual');
+    ok = false;
+  }
+  if (tier !== 'FULL' && residualEmpty) {
+    violations.push('non-FULL tier must document a residual');
+    ok = false;
+  }
+
+  return { ok, tier, violations };
+}
+
+export const _internals = Object.freeze({ BANNED_RESIDUAL_PHRASES, CITATION_RE, FP_VERDICTS });

package/src/posture/fix-verify.js

@@ -15,6 +15,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { runFullScan } from '../engine.js';
+import { gateFixOutput } from './fix-honesty-gate.js';
 
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 
@@ -110,21 +111,35 @@ function runLinter(cwd, cmd, args) {
 
 // Top-level verify: re-scan + lint. Returns the combined verdict + a
 // human-readable summary string suitable for surfacing to the user.
+// Addition #7 — deterministic honesty gates on fix output. When the caller
+// supplies `fixMeta` ({ residual, verdict, evidence, signals }) — e.g. the
+// security-fixer agent's residual-risk text + completeness signals — the fix's
+// claims are checked mechanically (no hand-wave residual prose, a cited
+// file:line for any FP/safe verdict, and a FULL/MITIGATION/WORKAROUND tier). A
+// dishonest or over-claiming fix fails the gate. When `fixMeta` is absent
+// (the deterministic MCP write path, which has no claims to check) the honesty
+// gate is skipped and behavior is unchanged.
 export async function verifyFix({
   scanRoot,
   originalFindingStableId,
   files,
   depFileContents,
+  fixMeta,
 } = {}) {
   const rescan = await verifyPatch({ scanRoot, originalFindingStableId, files, depFileContents });
   const lint = runProjectLinter(scanRoot, Object.keys(files || {}));
-  const ok = rescan.ok && (lint.ok || lint.skipped);
+  let honesty = null;
+  if (fixMeta && typeof fixMeta === 'object') {
+    try { honesty = gateFixOutput(fixMeta); } catch { honesty = null; }
+  }
+  const ok = rescan.ok && (lint.ok || lint.skipped) && (honesty ? honesty.ok : true);
   const summary = [
     `re-scan: ${rescan.ok ? 'PASS' : 'FAIL — ' + rescan.reason}`,
     `linter:  ${lint.runner === 'none' ? 'skipped (no linter config)'
               : lint.skipped ? `${lint.runner} not installed`
               : lint.ok ? `${lint.runner} PASS`
               : `${lint.runner} FAIL (exit ${lint.exitCode})`}`,
-  ].join('\n');
-  return { ok, rescan, lint, summary };
+    honesty ? `honesty: ${honesty.ok ? `PASS (${honesty.tier})` : 'FAIL — ' + honesty.violations.join('; ')}` : null,
+  ].filter(Boolean).join('\n');
+  return { ok, rescan, lint, honesty, summary };
 }

package/src/posture/model-routing.js

@@ -0,0 +1,126 @@
+// Capability-based model routing for cost-sensitive subagent dispatch.
+//
+// A declarative CWE/severity → model policy. When the orchestrator is about to
+// dispatch a delegable, cost-sensitive subagent for a finding (fixer, triager,
+// PoC generator, attack-chain synthesizer), it can ask this module which model
+// tier the work actually warrants — spend Opus reasoning on the hard classes
+// (crypto, auth, deserialization, XXE, cross-file taint) and let Haiku handle
+// the mechanical hardening findings.
+//
+// Mirrors the model IDs + tier vocabulary of hooks/model-cost-advisor.js:
+//   strongest = claude-opus-4-8   (high effort)
+//   mid       = claude-sonnet-4-6 (medium effort)
+//   cheapest  = claude-haiku-4-5  (low effort)
+//
+// This is a *preference*, not a ceiling — a caller may always upgrade when the
+// specific task clearly needs more capability (same spirit as the
+// subagentOverride contract documented in the root CLAUDE.md).
+//
+// Pure + deterministic — no I/O, no network, never throws.
+
+// Model IDs (module-local; the public API is the routing functions below).
+const MODEL_STRONGEST = 'claude-opus-4-8';
+const MODEL_MID = 'claude-sonnet-4-6';
+const MODEL_CHEAPEST = 'claude-haiku-4-5';
+
+const LABEL = {
+  [MODEL_STRONGEST]: 'Opus 4.8',
+  [MODEL_MID]: 'Sonnet 4.6',
+  [MODEL_CHEAPEST]: 'Haiku 4.5',
+};
+
+// Hard classes — subtle, high-blast-radius bugs where a wrong fix is worse than
+// no fix: auth, TLS/cert validation, weak crypto/hashing/randomness, signature
+// verification, unsafe deserialization, XXE. Worth Opus when they land at high
+// or critical severity.
+const HARD_CWES = new Set([
+  'CWE-287', // improper authentication
+  'CWE-295', // improper certificate validation
+  'CWE-327', // broken / risky crypto algorithm
+  'CWE-328', // weak hash
+  'CWE-330', // use of insufficiently random values
+  'CWE-347', // improper verification of cryptographic signature
+  'CWE-502', // deserialization of untrusted data
+  'CWE-611', // XML external entity (XXE)
+]);
+
+// Mid classes — the common injection / traversal / CSRF / SSRF families.
+// Well-understood remediations; Sonnet handles them cost-effectively.
+const MID_CWES = new Set([
+  'CWE-22',  // path traversal
+  'CWE-78',  // OS command injection
+  'CWE-79',  // cross-site scripting
+  'CWE-89',  // SQL injection
+  'CWE-94',  // code injection
+  'CWE-352', // cross-site request forgery
+  'CWE-434', // unrestricted file upload
+  'CWE-601', // open redirect
+  'CWE-918', // server-side request forgery
+]);
+
+// Extract the canonical `CWE-<n>` token from a finding.cwe value that may be a
+// bare id ("CWE-89") or a descriptive string ("CWE-89: SQL Injection").
+// Returns the uppercased id, or null when nothing parseable is present.
+export function parseCwe(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/CWE-\d+/i);
+  return m ? m[0].toUpperCase() : null;
+}
+
+// Route a single finding to a model tier. First match wins.
+// Returns { model, effort, reason }.
+export function routeModelForFinding(finding) {
+  const f = finding || {};
+  const severity = typeof f.severity === 'string' ? f.severity.toLowerCase() : '';
+  const cwe = parseCwe(f.cwe);
+  const multiFile = f.multiFile === true || f.isCrossFile === true;
+  const highOrCritical = severity === 'high' || severity === 'critical';
+
+  // ── Tier 1: strongest (Opus, high effort) ──
+  if (severity === 'critical') {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Critical severity — worth ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (cwe && HARD_CWES.has(cwe) && highOrCritical) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `${cwe} at ${severity} severity is a hard class (crypto / auth / deserialization / XXE) — ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (multiFile) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Cross-file finding — needs ${LABEL[MODEL_STRONGEST]} at high effort to reason across files.` };
+  }
+
+  // ── Tier 2: mid (Sonnet, medium effort) ──
+  if (cwe && MID_CWES.has(cwe)) {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `${cwe} is a common injection / traversal class — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+  if (severity === 'high') {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `High severity — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+
+  // ── Tier 3: cheapest (Haiku, low effort) ──
+  return { model: MODEL_CHEAPEST, effort: 'low',
+    reason: `${cwe ? `${cwe} at ` : ''}${severity || 'low'} severity is a simple / hardening class — ${LABEL[MODEL_CHEAPEST]} at low effort.` };
+}
+
+// Route a list of findings. Returns [{ finding, model, effort, reason }, …].
+export function routeModelForFindings(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  return list.map((finding) => ({ finding, ...routeModelForFinding(finding) }));
+}
+
+// Tally how many findings land on each model tier.
+// Returns { 'claude-opus-4-8': n, 'claude-sonnet-4-6': n, 'claude-haiku-4-5': n }.
+export function summarizeRouting(findings) {
+  const counts = {
+    [MODEL_STRONGEST]: 0,
+    [MODEL_MID]: 0,
+    [MODEL_CHEAPEST]: 0,
+  };
+  for (const { model } of routeModelForFindings(findings)) {
+    if (model in counts) counts[model] += 1;
+  }
+  return counts;
+}

package/src/posture/root-cause-sweep.js

@@ -0,0 +1,262 @@
+// Addition #3 — Root-cause sweep with total-count accounting.
+//
+// A detector fires on the instance it can prove. But the same root cause is
+// usually copy-pasted across the codebase, and most of those siblings never
+// trip a rule (different variable names, an assignment wrapper, a file the
+// scanner didn't reach with taint). This module takes CONFIRMED findings and
+// sweeps every source line for structural siblings of the same sink, then
+// accounts for every match honestly:
+//
+//     found === candidates + mitigated        (per sweep, always)
+//
+// where `found` is every structural match across the repo EXCLUDING the
+// finding's own origin site, `mitigated` is the subset a detector already
+// covered (a finding exists at that file:line), and `candidates` is the
+// remainder — new instances nobody has looked at yet. Nothing is dropped.
+//
+// Matching reuses semantic-clone's normalized token-shape hashing (`shapeHash`)
+// so that `db.query(a)` and `db.query(b)` collapse to one shape. Pure shape is
+// too loose on its own (`db.query(x)` and `console.log(x)` both normalize to
+// `ID.ID(ID)`), so we anchor on the LITERAL callee (`db.query`) and use the
+// shape only to confirm the argument arity/structure. Anchor + shape = precise.
+//
+// Like semantic-clone this is a coarse structural approximation, not a proof of
+// semantic equivalence. It catches the common "same call, cloned around" case.
+
+import { shapeHash } from './semantic-clone.js';
+
+// shapeHash defaults to minTokens:8 (tuned to avoid trivial clone collisions on
+// whole functions). A single call expression is short — `foo(a)` is 4 tokens,
+// `db.query(a)` is 6 — so we lower the floor for call-granular matching.
+const MIN_SHAPE_TOKENS = 3;
+
+// A callee whose final segment is one of these is control flow, not a sink call.
+const CONTROL_KEYWORDS = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'with', 'do', 'await',
+]);
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Accept both a Map and a plain { path: source } object.
+function toMap(fileContents) {
+  if (fileContents instanceof Map) return fileContents;
+  const m = new Map();
+  if (fileContents && typeof fileContents === 'object') {
+    for (const k of Object.keys(fileContents)) m.set(k, fileContents[k]);
+  }
+  return m;
+}
+
+// A finding qualifies for a sweep when it is confirmed. With confirmedOnly
+// disabled we sweep everything (the caller has opted out of the gate).
+function qualifies(finding, confirmedOnly) {
+  if (!confirmedOnly) return true;
+  return finding.confirmed === true || finding.confidenceTier === 'high';
+}
+
+// The origin site is the finding's own location; siblings must exclude it.
+function originSite(finding) {
+  if (finding.sink && finding.sink.file && finding.sink.line != null) {
+    return { file: finding.sink.file, line: finding.sink.line };
+  }
+  return { file: finding.file ?? null, line: finding.line ?? null };
+}
+
+// Every file:line that already carries a finding — used to classify a match as
+// 'mitigated-or-known' vs. a fresh 'candidate'.
+function buildKnownLocations(findings) {
+  const set = new Set();
+  for (const f of Array.isArray(findings) ? findings : []) {
+    if (!f || typeof f !== 'object') continue;
+    if (f.file != null && f.line != null) set.add(`${f.file}:${f.line}`);
+    if (f.sink && f.sink.file != null && f.sink.line != null) set.add(`${f.sink.file}:${f.sink.line}`);
+  }
+  return set;
+}
+
+// Pull the leading callee path out of a call snippet: `db.query(x)` → `db.query`.
+function extractCallee(snippet) {
+  if (!snippet || typeof snippet !== 'string') return null;
+  const m = snippet.match(/([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/);
+  if (!m) return null;
+  const callee = m[1];
+  const last = callee.split('.').pop();
+  if (CONTROL_KEYWORDS.has(last)) return null;
+  return callee;
+}
+
+// Extract the full balanced call expression for `callee` from `text`:
+// `const r = db.query(f(1), g);` → `db.query(f(1), g)`. Null if absent/unbalanced.
+function extractCall(text, callee) {
+  if (!text || typeof text !== 'string') return null;
+  const re = new RegExp('(?:^|[^\\w$.])' + escapeRegex(callee) + '\\s*\\(');
+  const m = re.exec(text);
+  if (!m) return null;
+  const calleeStart = m.index + m[0].indexOf(callee); // callee offset within the match
+
+  const open = text.indexOf('(', calleeStart);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') {
+      depth--;
+      if (depth === 0) return text.slice(calleeStart, i + 1);
+    }
+  }
+  return null; // unbalanced on this line
+}
+
+// Structural shape of a sink snippet: hash of the normalized call expression
+// (callee + args reduced to token kinds), reusing semantic-clone's hasher.
+function sinkShapeOf(snippet) {
+  if (!snippet || typeof snippet !== 'string') return null;
+  const callee = extractCallee(snippet);
+  const call = callee ? (extractCall(snippet, callee) || snippet) : snippet;
+  return shapeHash(call, { minTokens: MIN_SHAPE_TOKENS });
+}
+
+// Build a searchable pattern from a finding's sink (preferred) or fall back to
+// vuln/cwe keywords when no snippet is available.
+function deriveSinkPattern(finding) {
+  const snippet = finding?.sink?.snippet || finding?.snippet || '';
+  const callee = extractCallee(snippet);
+  if (callee) {
+    return {
+      kind: 'call',
+      callee,
+      shape: sinkShapeOf(snippet),
+      regex: new RegExp('(?:^|[^\\w$.])' + escapeRegex(callee) + '\\s*\\('),
+      display: `${callee}(…)`,
+    };
+  }
+  const kw = keywordFor(finding);
+  if (kw) {
+    return { kind: 'keyword', keyword: kw, shape: null, regex: new RegExp(escapeRegex(kw), 'i'), display: kw };
+  }
+  return null;
+}
+
+// Source pattern is reported for context; the sweep itself is sink-driven.
+function deriveSourcePattern(finding) {
+  const s = finding?.source?.snippet;
+  if (s && typeof s === 'string' && s.trim()) return { display: s.trim() };
+  const kw = keywordFor(finding);
+  if (kw) return { display: kw };
+  return null;
+}
+
+function keywordFor(finding) {
+  const v = (finding?.vuln ?? '').toString().trim();
+  if (v) return v;
+  const cwe = (finding?.cwe ?? '').toString().trim();
+  if (cwe) return cwe;
+  return null;
+}
+
+// Does a single source line structurally match the sink pattern?
+function matchLine(pattern, line) {
+  if (!pattern || typeof line !== 'string') return false;
+  if (pattern.kind === 'call') {
+    if (!pattern.regex.test(line)) return false;      // literal callee anchor
+    if (pattern.shape == null) return true;           // anchor-only (snippet too short to shape)
+    const call = extractCall(line, pattern.callee);
+    if (!call) return false;
+    return shapeHash(call, { minTokens: MIN_SHAPE_TOKENS }) === pattern.shape;
+  }
+  if (pattern.kind === 'keyword') {
+    return pattern.regex.test(line);
+  }
+  return false;
+}
+
+/**
+ * Sweep confirmed findings for sibling instances of the same root cause.
+ *
+ * @param {Array<object>} findings   scan findings (confirmed ones drive sweeps)
+ * @param {Map|object}    fileContents  { path: source } — Map or plain object
+ * @param {object}        opts       { confirmedOnly = true }
+ * @returns {{ sweeps: Array<object>, totals: {found,candidates,mitigated} }}
+ */
+export function sweepRootCauses(findings, fileContents, opts = {}) {
+  const confirmedOnly = opts?.confirmedOnly !== false;
+  const list = Array.isArray(findings) ? findings : [];
+  const files = toMap(fileContents);
+  const knownLocations = buildKnownLocations(list);
+
+  const sweeps = [];
+  const totals = { found: 0, candidates: 0, mitigated: 0 };
+
+  for (const finding of list) {
+    if (!finding || typeof finding !== 'object') continue;
+    if (!qualifies(finding, confirmedOnly)) continue;
+
+    const sinkPattern = deriveSinkPattern(finding);
+    if (!sinkPattern) continue; // nothing searchable — skip rather than fabricate
+    const sourcePattern = deriveSourcePattern(finding);
+    const origin = originSite(finding);
+
+    const instances = [];
+    for (const [path, source] of files) {
+      if (source == null) continue;
+      const lines = String(source).split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!matchLine(sinkPattern, line)) continue;
+        const lineNo = i + 1;
+        if (path === origin.file && lineNo === origin.line) continue; // exclude the finding's own site
+        const status = knownLocations.has(`${path}:${lineNo}`) ? 'mitigated-or-known' : 'candidate';
+        instances.push({ file: path, line: lineNo, snippet: line.trim(), status });
+      }
+    }
+
+    const candidates = instances.filter((x) => x.status === 'candidate').length;
+    const mitigated = instances.filter((x) => x.status === 'mitigated-or-known').length;
+    const found = instances.length; // every match is exactly one status → invariant holds by construction
+
+    sweeps.push({
+      fromFindingId: finding.id ?? finding.stableId ?? null,
+      sourcePattern: sourcePattern ? sourcePattern.display : null,
+      sinkPattern: sinkPattern.display,
+      found,
+      candidates,
+      mitigated,
+      remaining: candidates, // unaccounted instances that still need triage
+      instances,
+    });
+
+    totals.found += found;
+    totals.candidates += candidates;
+    totals.mitigated += mitigated;
+  }
+
+  return { sweeps, totals };
+}
+
+/**
+ * One short human line per sweep, e.g.:
+ *   "root-cause sweep: 20 found, 3 candidate, 17 mitigated"
+ */
+export function formatSweepLedger(result) {
+  if (!result || !Array.isArray(result.sweeps)) return '';
+  return result.sweeps
+    .map((s) => `root-cause sweep: ${s.found} found, ${s.candidates} candidate, ${s.mitigated} mitigated`)
+    .join('\n');
+}
+
+export const _internals = {
+  MIN_SHAPE_TOKENS,
+  sinkShapeOf,
+  deriveSinkPattern,
+  deriveSourcePattern,
+  extractCallee,
+  extractCall,
+  matchLine,
+  qualifies,
+  originSite,
+  buildKnownLocations,
+  toMap,
+};

package/src/pr-comment.js

@@ -25,6 +25,8 @@
 // route through an LLM for richer prose when AGENTIC_SECURITY_LLM_ENDPOINT
 // is configured.
 
+import { escapeMarkdown } from './util/untrusted.js';
+
 const SEVERITY_GLYPH = {
   critical: '🟥',
   high:     '🟧',
@@ -136,7 +138,7 @@ export function renderPrComment(delta, { repoName, prNumber, prTitle } = {}) {
     const sev = SEVERITY_GLYPH[f.severity] || '⬜';
     const route = _route(f);
     const where = route ? `\`${route}\` (\`${f.file}:${f.line}\`)` : `\`${f.file}:${f.line}\``;
-    lines.push(`${sev} **${meta?.name || f.vuln}** — ${where}`);
+    lines.push(`${sev} **${meta?.name || escapeMarkdown(f.vuln)}** — ${where}`);
     if (meta) lines.push(`  > ${meta.why}`);
     if (f.remediation) {
       const onelineFix = String(f.remediation).split('\n')[0].slice(0, 240);