@clear-capabilities/agentic-security-scanner 0.130.0 → 0.133.0

package/src/posture/attestation.js

@@ -60,10 +60,13 @@ const PROVES =
   '(same rule id, severity, file, line, cwe, vuln, and multiplicity) produced by the same ' +
   'engine version, ruleset version, and bundle — regardless of emission order.';
 const DOES_NOT_PROVE =
-  'It does not prove cross-machine reproducibility: no run on a second machine, OS, or Node ' +
-  'version is compared here, and some detectors are environment-sensitive. A signature, when ' +
-  'present, is a symmetric per-install HMAC — tamper-evidence for this install, not ' +
-  'third-party non-repudiation.';
+  'It does not prove cross-machine reproducibility: this attestation is one run on one machine, ' +
+  'nothing here compares a second machine, OS, or Node version, and some detectors are ' +
+  'environment-sensitive. That property is tested separately by the determinism-attest / ' +
+  'determinism-compare CI jobs, which run the same commit on two operating systems and fail ' +
+  'unless the digests match — evidence about the ENGINE, not about this attestation. ' +
+  'A signature, when present, is a symmetric per-install HMAC — tamper-evidence for this ' +
+  'install, not third-party non-repudiation.';
 
 function _str(v) { return v === undefined || v === null ? '' : String(v); }
 

package/src/posture/corpus-enroll.js

@@ -0,0 +1,303 @@
+// R2's differentiator — auto-enrol an execution-proven finding as a permanent
+// CVE-replay corpus entry.
+//
+// The compounding asset: a finding that was PROVEN by execution becomes a
+// regression test that the baseline gate defends forever. Every exploit the
+// pipeline proves once, it can never silently stop detecting.
+//
+// THE CENTRAL RULE: nothing is written to the corpus that has not been scored.
+// The v0.106.0 failure — fixtures committed without verifying they actually
+// score, which then broke the gate for everyone — is the exact mistake this
+// module must not automate. So enrolment builds the entry in a TEMPORARY
+// directory, scans `pre/` and `post/` with the same matcher the gate uses
+// (`corpus-match.js`), and moves it into the corpus only on `pre:TP post:TN`.
+// A candidate that does not score is discarded and the reason returned. There
+// is no force flag and no "probably fine" path.
+//
+// WHY A FIX IS MANDATORY. An entry needs a `post/` that scores TN, and the
+// only honest source of one is a real fix. Enrolment therefore refuses a
+// finding with no fixed content rather than synthesising a `post/` by deleting
+// the vulnerable line — that would produce an entry that passes for a reason
+// unrelated to the vulnerability, which is worse than no entry.
+//
+// WHY `capability/` AND NOT `regression/`. `regression/` is the CI-gated tier
+// and graduation into it is a human decision with a stated policy (five
+// consecutive passing snapshots — see bench/cve-replay/CONTRIBUTING.md). An
+// automated writer promoting straight into the gated tier would let a machine
+// decide what blocks everyone's build. New entries land in `capability/`,
+// already passing, and graduate on the existing policy.
+//
+// NOTHING THROWS (posture convention): every path returns
+// `{ok:false, refused:true, reason}` instead.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { preHit, postHit, matcherFor } from './corpus-match.js';
+
+const DEFAULT_TIER = 'capability';
+
+// Entry ids must be safe to use as a directory name and stable across runs.
+const ID_SAFE = /^[A-Za-z0-9._-]+$/;
+
+function refuse(reason) { return { ok: false, refused: true, reason }; }
+
+// A finding is enrollable only if the pipeline actually RAN its exploit. This
+// re-checks the evidence rather than trusting `proofTier` alone: the tier is a
+// string on an object that may have crossed a process boundary, and the
+// consequence of trusting a forged one is a permanent corpus entry.
+export function isEnrollable(finding) {
+  if (!finding || typeof finding !== 'object') return refuse('no finding supplied');
+  if (finding.proofTier !== 'execution-proven') {
+    return refuse(
+      `only execution-proven findings may enrol; this one is '${finding.proofTier || 'untiered'}'. `
+      + 'A statically-reasoned finding has not earned a permanent regression entry.',
+    );
+  }
+  const ev = finding.proofEvidence;
+  if (!ev || ev.ran !== true) {
+    return refuse('proofEvidence does not record a run (ran !== true) — the tier is not backed by evidence');
+  }
+  if (ev.tier !== 'execution-proven') {
+    return refuse(`proofEvidence.tier ('${ev.tier}') disagrees with proofTier — refusing rather than picking one`);
+  }
+  if (!ev.observed) {
+    return refuse('proofEvidence records no observed effect — an execution-proven tier with nothing observed is not evidence');
+  }
+  return { ok: true };
+}
+
+function _slug(s, fallback) {
+  const out = String(s || '').trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return out || fallback;
+}
+
+/**
+ * The entry id. Derived from the finding so re-enrolling the same finding is
+ * idempotent (it will be refused as a duplicate) rather than accumulating
+ * near-identical entries.
+ */
+export function entryIdFor(finding) {
+  const fam = _slug(finding?.family || finding?.cwe, 'finding');
+  const sid = _slug(finding?.stableId || finding?.id, 'unknown');
+  return `proven-${fam}-${sid}`.slice(0, 120);
+}
+
+/**
+ * Build the manifest + file map for a candidate entry, without writing it.
+ *
+ * @param {object} finding      an execution-proven finding
+ * @param {object} opts
+ * @param {object} opts.preFiles   rel→content, the VULNERABLE tree
+ * @param {object} opts.postFiles  rel→content, the FIXED tree
+ */
+export function buildCandidate(finding, { preFiles, postFiles, addedAt } = {}) {
+  const gate = isEnrollable(finding);
+  if (!gate.ok) return gate;
+
+  if (!finding.cwe) return refuse('finding has no cwe — the manifest matcher would be meaningless');
+  if (!finding.vuln) return refuse('finding has no vuln — nothing to match on');
+  if (!finding.file) return refuse('finding has no file — cannot name the expected file');
+
+  const pre = preFiles && typeof preFiles === 'object' ? preFiles : null;
+  const post = postFiles && typeof postFiles === 'object' ? postFiles : null;
+  if (!pre || !Object.keys(pre).length) return refuse('no pre/ content supplied — nothing to prove the detector fires on');
+  if (!post || !Object.keys(post).length) {
+    return refuse(
+      'no post/ content supplied. An entry with no fixed tree cannot score post:TN, and '
+      + 'synthesising one by deleting the vulnerable code would pass for the wrong reason.',
+    );
+  }
+
+  // A `post` identical to `pre` cannot be a fix. Catching it here turns a
+  // guaranteed post:FP into a clear refusal.
+  const same = Object.keys(pre).length === Object.keys(post).length
+    && Object.entries(pre).every(([k, v]) => post[k] === v);
+  if (same) return refuse('post/ is byte-identical to pre/ — no fix was applied, so the entry cannot score post:TN');
+
+  for (const [label, files] of [['pre', pre], ['post', post]]) {
+    for (const [rel, content] of Object.entries(files)) {
+      if (typeof content !== 'string') return refuse(`${label}/${rel} content is not a string`);
+      if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+        return refuse(`${label}/${rel} escapes the entry directory`);
+      }
+    }
+  }
+
+  const id = entryIdFor(finding);
+  if (!ID_SAFE.test(id)) return refuse(`derived entry id '${id}' is not a safe directory name`);
+
+  const expectedFile = path.basename(String(finding.file));
+  if (!Object.keys(pre).some(rel => path.basename(rel) === expectedFile)) {
+    return refuse(`the finding's file '${expectedFile}' is not among the pre/ files — the entry would not test the finding`);
+  }
+
+  const manifest = {
+    cve: id,
+    cwe: finding.cwe,
+    family: finding.family || 'unknown',
+    language: finding.language || _languageOf(expectedFile),
+    summary: `execution-proven ${finding.family || finding.cwe}: ${String(finding.vuln).slice(0, 120)}`,
+    expected: {
+      file: expectedFile,
+      // Match on the exact vuln string this finding carried. A broader regex
+      // would let an unrelated detector satisfy the entry.
+      vuln_match: _escapeRegex(String(finding.vuln)),
+    },
+    source: 'execution-proven',
+    added_at: addedAt || new Date().toISOString().slice(0, 10),
+    provenance: {
+      stableId: finding.stableId || null,
+      proofBackend: finding.proofEvidence?.backend || null,
+      observed: finding.proofEvidence?.observed || null,
+      provenAt: finding.proofEvidence?.at || null,
+    },
+  };
+
+  return { ok: true, id, manifest, preFiles: pre, postFiles: post };
+}
+
+function _escapeRegex(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function _languageOf(file) {
+  const ext = path.extname(file).toLowerCase();
+  return {
+    '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.ts': 'typescript', '.tsx': 'typescript', '.jsx': 'javascript',
+    '.py': 'python', '.java': 'java', '.go': 'go', '.rb': 'ruby',
+    '.php': 'php', '.cs': 'csharp', '.rs': 'rust',
+  }[ext] || 'unknown';
+}
+
+function _writeTree(dir, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  }
+}
+
+/**
+ * Materialise a candidate into a staging directory and SCORE it, using the
+ * same matcher the corpus gate uses.
+ *
+ * @param {function} runScan  injected so this module stays free of an engine
+ *   import cycle and so tests can drive it without a full scan.
+ * @returns {{ok:boolean, status:string, preHit:boolean, postHit:boolean, reason?:string}}
+ */
+async function scoreCandidate(candidate, runScan, { stagingDir } = {}) {
+  const dir = stagingDir || fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-cand-'));
+  try {
+    const preDir = path.join(dir, 'pre');
+    const postDir = path.join(dir, 'post');
+    fs.mkdirSync(preDir, { recursive: true });
+    fs.mkdirSync(postDir, { recursive: true });
+    _writeTree(preDir, candidate.preFiles);
+    _writeTree(postDir, candidate.postFiles);
+    fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(candidate.manifest, null, 2) + '\n', 'utf8');
+
+    const matcher = matcherFor(candidate.manifest);
+    let pre, post;
+    try {
+      ({ scan: pre } = await runScan(preDir));
+    } catch (e) {
+      return { ok: false, status: 'scan-error', preHit: false, postHit: false, reason: `pre/ scan failed: ${e.message}` };
+    }
+    try {
+      ({ scan: post } = await runScan(postDir));
+    } catch (e) {
+      return { ok: false, status: 'scan-error', preHit: false, postHit: false, reason: `post/ scan failed: ${e.message}` };
+    }
+
+    const hitPre = preHit(pre, candidate.manifest, matcher);
+    const hitPost = postHit(post, candidate.manifest, matcher);
+    const status = `pre:${hitPre ? 'TP' : 'FN'} post:${hitPost ? 'FP' : 'TN'}`;
+
+    if (!hitPre) {
+      return {
+        ok: false, status, preHit: hitPre, postHit: hitPost, dir,
+        reason: 'the detector does not fire on pre/ — the entry would be committed already failing. '
+              + 'A PoC proved this finding at runtime but the minimised fixture does not reproduce it statically.',
+      };
+    }
+    if (hitPost) {
+      return {
+        ok: false, status, preHit: hitPre, postHit: hitPost, dir,
+        reason: 'the detector still fires on post/ — the fix does not clear the finding, so the entry cannot score TN.',
+      };
+    }
+    return { ok: true, status, preHit: hitPre, postHit: hitPost, dir };
+  } catch (e) {
+    return { ok: false, status: 'error', preHit: false, postHit: false, reason: e.message };
+  }
+}
+
+/**
+ * The full path: gate → build → score → commit.
+ *
+ * Writes into `<corpusRoot>/<tier>/<id>/` ONLY when the candidate scored
+ * `pre:TP post:TN`. Anything else leaves the corpus untouched.
+ */
+export async function enrollProvenFinding(finding, {
+  corpusRoot, preFiles, postFiles, runScan, tier = DEFAULT_TIER, addedAt, dryRun = false,
+} = {}) {
+  if (!corpusRoot) return refuse('no corpusRoot supplied');
+  if (typeof runScan !== 'function') return refuse('no runScan supplied — an entry may not be committed unscored');
+
+  const candidate = buildCandidate(finding, { preFiles, postFiles, addedAt });
+  if (!candidate.ok) return candidate;
+
+  const dest = path.join(corpusRoot, tier, candidate.id);
+  if (fs.existsSync(dest)) {
+    return refuse(`entry '${candidate.id}' already exists in ${tier}/ — refusing to overwrite a corpus entry`);
+  }
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-cand-'));
+  try {
+    const scored = await scoreCandidate(candidate, runScan, { stagingDir: staging });
+    if (!scored.ok) {
+      return {
+        ok: false, refused: true, id: candidate.id, status: scored.status,
+        reason: `not enrolled (${scored.status}): ${scored.reason}`,
+      };
+    }
+    if (dryRun) {
+      return { ok: true, dryRun: true, id: candidate.id, status: scored.status, dir: null, manifest: candidate.manifest };
+    }
+
+    // Scan state accumulated inside the staged trees must not be committed —
+    // it would be scanned as part of the fixture on the next run.
+    _stripState(staging);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(staging, dest);
+    return {
+      ok: true,
+      id: candidate.id,
+      tier,
+      status: scored.status,
+      dir: dest,
+      manifest: candidate.manifest,
+      // Said explicitly because a caller that stops here leaves the repo in a
+      // state where the gate reports a nudge rather than a pass.
+      followUp: 'run `npm run bench:cve-replay:update-baseline` and commit the regenerated corpus-baseline.json',
+    };
+  } catch (e) {
+    return refuse(`enrolment failed: ${e.message}`);
+  } finally {
+    // If the rename happened, staging no longer exists and this is a no-op.
+    try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+function _stripState(dir) {
+  for (const sub of ['pre', 'post']) {
+    const s = path.join(dir, sub, '.agentic-security');
+    try { fs.rmSync(s, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+// `scoreCandidate` is deliberately NOT exported: an external caller could
+// score a candidate and then write it by some other route, which is exactly
+// the unscored-write path this module exists to make unavailable. Enrolment
+// scores and writes as one operation or not at all.
+export const _internals = { DEFAULT_TIER, scoreCandidate, _languageOf, _escapeRegex, _stripState };

package/src/posture/corpus-match.js

@@ -0,0 +1,67 @@
+// How a CVE-replay corpus entry is scored against a scan result.
+//
+// Extracted from `bench/cve-replay/runner.mjs` so the corpus GATE and corpus
+// ENROLLMENT (`corpus-enroll.js`) cannot drift apart. That drift is not
+// hypothetical: enrollment only writes an entry it has verified scores
+// `pre:TP post:TN`, and if it verified that with a different matcher than the
+// gate uses, it would cheerfully commit entries that fail CI. One
+// implementation, two callers.
+//
+// THE PRE/POST MATCHERS ARE NOW SYMMETRIC. They were not: `pre` accepted a hit
+// on `vuln` OR `family` and regex-tested `cwe`, while `post` was strict on
+// `vuln` and required an exact `cwe`. An entry therefore faced a LOOSER bar to
+// score a true positive than a false positive, which flatters the corpus —
+// exactly the direction a measurement must not lean. `CONTRIBUTING.md` recorded
+// it as known imprecision to resolve before the corpus grows toward 500.
+//
+// WHICH DIRECTION, AND WHY. The two sides were unified on the LOOSE predicate,
+// not the strict one. The question a corpus entry asks is "does the scanner
+// still report this vulnerability?", and a scanner that reports it under the
+// family name rather than the exact vuln string is still reporting it. Loose-
+// on-both means an entry must genuinely go quiet to score `post:TN` — a HIGHER
+// bar for a pass. Unifying on the strict predicate would instead have made
+// `pre:TP` harder and `post:TN` easier, i.e. it would have made the corpus
+// easier to satisfy. When a symmetry fix can go either way, take the direction
+// that makes the gate harder to pass.
+//
+// This re-verdicts every committed entry, so it is a corpus migration: the full
+// baseline was re-run against it and any entry whose verdict moved was fixed or
+// recorded, never baselined over.
+//
+// The scanner emits into several arrays — `findings` (SAST), `secrets`,
+// `supplyChain` (SCA) and `logicVulns` (business-logic + behavioural) — and a
+// CVE can land in any of them, so all four are consulted.
+
+const CHANNELS = ['findings', 'secrets', 'supplyChain', 'logicVulns'];
+
+/** The regex an entry's manifest scores with. */
+export function matcherFor(manifest) {
+  return new RegExp(manifest?.expected?.vuln_match || manifest?.family || manifest?.cwe || '(?!)', 'i');
+}
+
+function _any(scan, predicate) {
+  for (const channel of CHANNELS) {
+    const arr = scan?.[channel];
+    if (Array.isArray(arr) && arr.some(predicate)) return true;
+  }
+  return false;
+}
+
+// One predicate, both sides. See the header for why the symmetric form is the
+// LOOSE one.
+function _matches(f, manifest, matcher) {
+  return (matcher.test(f.vuln || '') || matcher.test(f.family || '')) &&
+    (manifest?.cwe ? f.cwe === manifest.cwe || matcher.test(f.cwe || '') : true);
+}
+
+/** Did the vulnerable (`pre/`) tree produce a matching finding? */
+export function preHit(scan, manifest, matcher = matcherFor(manifest)) {
+  return _any(scan, f => _matches(f, manifest, matcher));
+}
+
+/** Did the fixed (`post/`) tree still produce a matching finding? */
+export function postHit(scan, manifest, matcher = matcherFor(manifest)) {
+  return _any(scan, f => _matches(f, manifest, matcher));
+}
+
+export const _internals = { CHANNELS };

package/src/posture/custom-rules.js

@@ -30,7 +30,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
-import fg from 'fast-glob';
+import { globFiles } from '../util/glob.js';
 import { loadTrustedKeys, verifyRulePack } from './rule-pack-signing.js';
 
 const LANG_EXTS = {
@@ -337,7 +337,7 @@ export async function runRuleTests(scanRoot, fixtureGlob) {
     console.log(`No custom rules found in ${rulesDir(scanRoot)}`);
     return { ok: true, rules: 0, fired: 0 };
   }
-  const files = await fg(fixtureGlob, { dot: false, onlyFiles: true });
+  const files = await globFiles(fixtureGlob);
   console.log(`Loaded ${rules.length} rule(s); testing against ${files.length} file(s).\n`);
   let fired = 0;
   for (const fp of files) {

package/src/posture/execution-proof.js

@@ -18,7 +18,40 @@ function _evidence(over = {}) {
   };
 }
 
-export async function proveFinding(finding, { timeoutMs = 10000 } = {}) {
+// A run that never got as far as executing the PoC. `ran:false` for these is
+// the whole point: 'proof-failed' asserts "the PoC ran and the predicted effect
+// did not appear", which is a triage signal about the FINDING. A sandbox that
+// could not start says nothing about the finding at all, and must leave it at
+// its static tier rather than manufacturing a failed exploit attempt.
+const _DID_NOT_EXECUTE = new Set(['disabled', 'error']);
+
+// Materialise caller-supplied files into the sandbox root so a PoC can import
+// the code it is supposed to exploit. Paths are confined to the root: an
+// absolute path or one that climbs out is refused rather than clamped, because
+// silently rewriting a path would put a file somewhere the caller did not ask
+// for and the PoC would then exercise the wrong code.
+function _materialise(root, files) {
+  for (const [rel, content] of Object.entries(files || {})) {
+    if (typeof content !== 'string') continue;
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + path.sep)) {
+      return `refusing to write '${rel}': it resolves outside the sandbox root`;
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  }
+  return null;
+}
+
+/**
+ * @param {object} finding    carries `poc: {lang, code}`
+ * @param {object} [opts]
+ * @param {object} [opts.files]  rel→content written into the sandbox root before
+ *   the PoC runs. This is what lets the SAME PoC be run against a candidate
+ *   patch: pass the patched contents and a still-`execution-proven` verdict
+ *   means the fix did not close the hole.
+ */
+export async function proveFinding(finding, { timeoutMs = 10000, force, files } = {}) {
   const poc = finding?.poc;
   if (!poc?.code) {
     return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: 'no proof-of-concept attached' }));
@@ -32,16 +65,23 @@ export async function proveFinding(finding, { timeoutMs = 10000 } = {}) {
 
   const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'proof-')));
   try {
+    const badPath = _materialise(root, files);
+    if (badPath) {
+      return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: badPath }));
+    }
     fs.writeFileSync(path.join(root, 'poc.mjs'), poc.code, 'utf8');
-    const r = runConfined([process.execPath, 'poc.mjs'], { root, timeoutMs });
+    const r = runConfined([process.execPath, 'poc.mjs'], { root, timeoutMs, force });
     const proven = fs.existsSync(path.join(root, PROOF_MARKER));
+    const ran = !r.timedOut && !_DID_NOT_EXECUTE.has(r.status);
 
     return attachProofTier(finding, _evidence({
-      tier: proven ? 'execution-proven' : 'proof-failed',
+      tier: proven ? 'execution-proven' : ran ? 'proof-failed' : proofTierOf(finding),
       backend: r.backend,
-      ran: !r.timedOut && r.status !== 'disabled',
+      ran,
       observed: proven ? `proof marker '${PROOF_MARKER}' written by the proof-of-concept` : null,
       reason: proven ? null
+        : r.status === 'error' ? `the confinement sandbox could not start, so the proof-of-concept never executed (${r.backend} backend): ${String(r.stderr || '').trim() || 'no detail reported'}`
+        : r.status === 'disabled' ? 'confined execution is disabled; the proof-of-concept was refused and never executed'
         : r.timedOut ? 'proof-of-concept exceeded its time budget'
         : 'proof-of-concept ran but did not demonstrate the predicted effect',
       exitCode: r.exitCode, timedOut: r.timedOut,

package/src/posture/fix-metrics.js

@@ -0,0 +1,197 @@
+// Time-to-validated-fix (R5, the reporting half).
+//
+// `verifyFix` already RUNS the stages and `test-runner.js` already times the
+// slowest one. What did not exist was anything durable to read afterwards, so
+// "how long does a fix actually take to validate" had no answer from real runs
+// — only an estimate (`time-to-fix.js` guesses engineering hours from family
+// and patch shape, before anything runs). This module is the opposite: it
+// records what the pipeline observed and reports the distribution.
+//
+// THE HONESTY RULES, which are most of why this file is longer than a mean:
+//
+//  1. A failed attempt is NOT a data point about how long a fix takes. Fixes
+//     that fail verification fail fast (a re-scan that still sees the finding
+//     never reaches the test suite), so blending them into one average makes
+//     the pipeline look faster the worse it performs. Validated and failed
+//     attempts are summarised separately and never merged.
+//
+//  2. "Tests skipped" is not "tests passed". A project with no detectable
+//     suite can reach `ok:true` having run only the re-scan and the linter.
+//     That is a weaker claim than a fix whose suite executed, and it is also
+//     much faster, so counting the two together would quietly deflate the
+//     headline. They get their own bucket: `validated` means the suite ran and
+//     passed, `validatedWithoutTests` means there was no suite to run.
+//
+//  3. Every figure carries its `n`, and a percentile computed from too few
+//     samples is labelled unreliable rather than omitted or silently reported.
+//     Same precedent as the accuracy scorecard's `{n, d}` rates: a number
+//     without its denominator is not a measurement.
+//
+// Storage is append-only JSONL at `<scanRoot>/.agentic-security/fix-metrics.jsonl`,
+// one record per verification attempt. Nothing here throws (posture
+// convention) — an unwritable or corrupt log degrades to "no metrics", never
+// to a failed verification.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSafeStateDir } from './state-dir.js';
+
+const STATE_DIR = '.agentic-security';
+const LOG_FILE = 'fix-metrics.jsonl';
+
+// Below this many samples a percentile is an artifact of the sample, not a
+// property of the pipeline. Reported anyway (hiding it invites re-deriving it
+// wrong downstream) but flagged, so a caller cannot quote it as settled.
+const RELIABLE_N = 10;
+
+// The stages verifyFix runs, in execution order. Kept here so the recorder and
+// the summariser cannot drift apart on stage naming.
+export const FIX_STAGES = Object.freeze(['rescan', 'lint', 'tests', 'honesty', 'poc']);
+
+function _logPath(scanRoot) {
+  return path.join(scanRoot, STATE_DIR, LOG_FILE);
+}
+
+/**
+ * Append one verification attempt. Best-effort and silent on failure: metrics
+ * must never be able to fail a fix that otherwise verified.
+ *
+ * @returns {boolean} whether the record was written (for tests, not callers).
+ */
+export function recordFixAttempt(scanRoot, record) {
+  if (!scanRoot || !record || typeof record !== 'object') return false;
+  try {
+    const dir = path.join(scanRoot, STATE_DIR);
+    if (!isSafeStateDir(dir)) return false;
+    fs.mkdirSync(dir, { recursive: true });
+    // One writeSync of one newline-terminated line: a concurrent reader sees
+    // whole records or nothing, and a torn tail is dropped on read.
+    fs.appendFileSync(_logPath(scanRoot), JSON.stringify(record) + '\n', 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Read every well-formed attempt. A line that does not parse is skipped, not
+ * fatal — the last line of an interrupted write is the expected case.
+ */
+export function loadFixAttempts(scanRoot) {
+  try {
+    const raw = fs.readFileSync(_logPath(scanRoot), 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const rec = JSON.parse(line);
+        if (rec && typeof rec === 'object' && typeof rec.totalMs === 'number') out.push(rec);
+      } catch { /* torn or hand-edited line — drop it, keep the rest */ }
+    }
+    return out;
+  } catch { return []; }
+}
+
+// Nearest-rank percentile over an ascending array. Nearest-rank rather than
+// interpolated because these are observed durations, and an interpolated p50
+// reports a duration that no run actually took.
+function _pct(sorted, p) {
+  if (!sorted.length) return null;
+  const rank = Math.ceil((p / 100) * sorted.length);
+  return sorted[Math.min(sorted.length - 1, Math.max(0, rank - 1))];
+}
+
+function _dist(values) {
+  const v = values.filter(x => typeof x === 'number' && Number.isFinite(x) && x >= 0).sort((a, b) => a - b);
+  if (!v.length) return { n: 0, minMs: null, p50Ms: null, p90Ms: null, maxMs: null, meanMs: null, reliable: false };
+  const sum = v.reduce((a, b) => a + b, 0);
+  return {
+    n: v.length,
+    minMs: v[0],
+    p50Ms: _pct(v, 50),
+    p90Ms: _pct(v, 90),
+    maxMs: v[v.length - 1],
+    meanMs: Math.round(sum / v.length),
+    // Says whether the percentiles above may be quoted, not whether the count
+    // is real. n and min/max/mean are exact at any sample size.
+    reliable: v.length >= RELIABLE_N,
+  };
+}
+
+// Which bucket an attempt belongs to. Deliberately total: every attempt lands
+// in exactly one, so the bucket counts always sum to the attempt count and a
+// mis-shaped record cannot silently vanish from the denominator.
+export function bucketOf(a) {
+  if (!a?.ok) return 'failed';
+  return a.testsRan ? 'validated' : 'validatedWithoutTests';
+}
+
+/**
+ * Summarise a set of attempts into the reported distribution.
+ *
+ * `validated` is the headline: attempts that verified AND whose test suite
+ * actually ran and passed. The other two buckets exist so that headline cannot
+ * be inflated by counting weaker or faster outcomes inside it.
+ */
+export function summarizeFixDurations(attempts) {
+  const all = Array.isArray(attempts) ? attempts : [];
+  const buckets = { validated: [], validatedWithoutTests: [], failed: [] };
+  for (const a of all) buckets[bucketOf(a)].push(a);
+
+  const byStage = {};
+  for (const stage of FIX_STAGES) {
+    // Per-stage timings come from validated runs only. A stage's duration in a
+    // failed run is truncated by the failure (the pipeline stops), so mixing
+    // them in would understate every stage after the first failure point.
+    byStage[stage] = _dist(buckets.validated.map(a => a?.stages?.[stage]));
+  }
+
+  return {
+    attempts: all.length,
+    counts: {
+      validated: buckets.validated.length,
+      validatedWithoutTests: buckets.validatedWithoutTests.length,
+      failed: buckets.failed.length,
+    },
+    timeToValidatedFix: _dist(buckets.validated.map(a => a.totalMs)),
+    timeToValidatedFixWithoutTests: _dist(buckets.validatedWithoutTests.map(a => a.totalMs)),
+    timeToFailure: _dist(buckets.failed.map(a => a.totalMs)),
+    byStage,
+    reliableAtOrAbove: RELIABLE_N,
+  };
+}
+
+/** Read + summarise in one step. */
+export function fixDurationReport(scanRoot) {
+  return summarizeFixDurations(loadFixAttempts(scanRoot));
+}
+
+function _ms(v) {
+  if (v == null) return '—';
+  return v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${v}ms`;
+}
+
+/**
+ * One-paragraph human summary. Returns null when there is nothing measured —
+ * callers print nothing rather than printing an empty table.
+ */
+export function renderFixDurationSummary(sum) {
+  if (!sum || !sum.attempts) return null;
+  const d = sum.timeToValidatedFix;
+  const parts = [];
+  if (d.n) {
+    parts.push(
+      `time-to-validated-fix: median ${_ms(d.p50Ms)}, p90 ${_ms(d.p90Ms)} `
+      + `(n=${d.n}${d.reliable ? '' : `, below ${sum.reliableAtOrAbove} — percentiles not yet reliable`})`,
+    );
+  } else {
+    parts.push('time-to-validated-fix: no fix has both verified and had its test suite run yet');
+  }
+  if (sum.counts.validatedWithoutTests) {
+    parts.push(`${sum.counts.validatedWithoutTests} verified with no detectable test suite (excluded from the median above)`);
+  }
+  if (sum.counts.failed) {
+    parts.push(`${sum.counts.failed} failed verification, median ${_ms(sum.timeToFailure.p50Ms)} (counted separately)`);
+  }
+  return parts.join('; ') + '.';
+}
+
+export const _internals = { _dist, _pct, RELIABLE_N };