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

package/src/posture/scan-checkpoint.js

@@ -0,0 +1,277 @@
+// Scan checkpointing / resume (roadmap R8).
+//
+// Long scans currently restart from zero if interrupted, which is what caps the
+// repository size this engine can usefully handle. This module lets the per-file
+// loop in `engine.js#runFullScan` durably record what it has already analysed so
+// a second invocation replays that work instead of redoing it.
+//
+// THE PROPERTY THAT MATTERS: a resumed scan must produce the same finding set as
+// an uninterrupted one. A checkpoint that silently drops findings converts a slow
+// scan into a quietly incomplete one, which is strictly worse than no checkpoint
+// at all. Three design decisions follow from that and should not be relaxed:
+//
+//   1. We persist the *complete* per-file contribution, not just findings —
+//      routes, taint sources/sinks/sanitizers, logic vulns, secrets, ciphers,
+//      the per-file result the cross-file taint pass reads, and the suppression
+//      log delta. Anything the per-file loop appends to must round-trip, or the
+//      post-loop cross-file passes would see a different world on resume.
+//   2. Only the per-file loop is checkpointed. Every cross-file pass and the
+//      whole annotation pipeline re-runs from scratch on resume, so nothing that
+//      depends on the global picture can be stale by construction.
+//   3. Invalidation is conservative to the point of being blunt. The run key
+//      covers the engine version, the ruleset version, the bundle SHA, a content
+//      hash of every file in the scan (which subsumes mtime), and the scanner's
+//      own environment switches. If any of it moved, the checkpoint is discarded
+//      and the scan starts clean. Redoing work is merely slow; resuming stale
+//      work is a correctness bug.
+//
+// CRASH SAFETY: append-and-fsync. The file is a JSONL log — one header line
+// pinning the run key, then one self-describing record per completed file,
+// each carrying a SHA-256 of its own payload. Every record is written with a
+// single `writeSync` and immediately `fsyncSync`'d before the next file is
+// analysed, so a process killed at any instant leaves either a complete record
+// or a torn tail. On recovery we read forward while records verify and truncate
+// the file at the last byte offset that did, so a torn tail is discarded rather
+// than resumed into. Nothing is ever rewritten in place, so there is no window
+// in which the file is neither the old state nor the new one.
+//
+// Everything here follows the posture convention of never throwing: a failure to
+// open, read or append degrades to "no checkpoint", which just means a full scan.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const STATE_DIR = '.agentic-security';
+const FILE_NAME = 'scan-checkpoint.jsonl';
+const FORMAT = 'agentic-security-scan-checkpoint/1';
+
+// Env switches that change what the engine emits are part of the run identity.
+// These three are deliberately excluded: they change how the run is driven, not
+// what it would find.
+const RUN_KEY_ENV_EXCLUDE = new Set([
+  'AGENTIC_SECURITY_RESUME',
+  'AGENTIC_SECURITY_CHECKPOINT_ABORT_AFTER',
+  'AGENTIC_SECURITY_HMAC_KEY',
+]);
+
+export function checkpointPath(scanRoot) {
+  return path.join(scanRoot || '.', STATE_DIR, FILE_NAME);
+}
+
+function _sha(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// SHA-256 of the running bundle, taken from the sidecar next to it. Returns
+// 'unavailable' when running from source — same convention as the attestation
+// path, and deliberately not a guess at some other bundle's hash.
+export function bundleShaForRunKey() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // src/posture/ -> src/ -> scanner/
+    const sidecar = path.resolve(here, '..', '..', 'dist', 'agentic-security.mjs.sha256');
+    const raw = fs.readFileSync(sidecar, 'utf8').trim();
+    const m = /^([0-9a-f]{64})\b/.exec(raw);
+    if (m) return m[1];
+  } catch { /* not running from a built tree */ }
+  return 'unavailable';
+}
+
+/**
+ * Everything that would invalidate previously-completed per-file work, reduced
+ * to one hex digest. Content hashes rather than mtimes: strictly stronger, and
+ * immune to filesystems with coarse or non-monotonic timestamps.
+ */
+export function computeRunKey({
+  engineVersion, rulesetVersion, bundleSha,
+  fileContents = {}, depFileContents = {}, env = process.env,
+} = {}) {
+  const h = crypto.createHash('sha256');
+  h.update(FORMAT); h.update('\n');
+  h.update(String(engineVersion ?? '')); h.update('\n');
+  h.update(String(rulesetVersion ?? '')); h.update('\n');
+  h.update(String(bundleSha ?? 'unavailable')); h.update('\n');
+  for (const [label, map] of [['f', fileContents], ['d', depFileContents]]) {
+    const names = Object.keys(map || {}).sort();
+    h.update(label); h.update(String(names.length)); h.update('\n');
+    for (const n of names) {
+      h.update(n); h.update('\0');
+      h.update(_sha(String(map[n] ?? '')));
+      h.update('\n');
+    }
+  }
+  const envKeys = Object.keys(env || {})
+    .filter(k => k.startsWith('AGENTIC_SECURITY_') && !RUN_KEY_ENV_EXCLUDE.has(k))
+    .sort();
+  h.update('e'); h.update(String(envKeys.length)); h.update('\n');
+  for (const k of envKeys) { h.update(k); h.update('='); h.update(String(env[k])); h.update('\n'); }
+  return h.digest('hex');
+}
+
+// A value is safe to checkpoint only if JSON can carry it back unchanged. Dates,
+// regexes, Maps, Sets, functions and BigInts all survive `JSON.stringify` in a
+// lossy or throwing way; recording one would mean the resumed run sees different
+// data than the uninterrupted run did. We refuse the record instead, and the
+// file just gets rescanned.
+function _jsonSafe(v, depth = 0, seen = new Set()) {
+  if (depth > 24) return false;
+  if (v === null || v === undefined) return true;
+  const t = typeof v;
+  if (t === 'string' || t === 'boolean') return true;
+  if (t === 'number') return Number.isFinite(v);
+  if (t === 'function' || t === 'symbol' || t === 'bigint') return false;
+  if (t !== 'object') return false;
+  if (seen.has(v)) return false;
+  seen.add(v);
+  try {
+    if (Array.isArray(v)) {
+      for (const x of v) if (!_jsonSafe(x, depth + 1, seen)) return false;
+      return true;
+    }
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) return false;
+    for (const k of Object.keys(v)) if (!_jsonSafe(v[k], depth + 1, seen)) return false;
+    return true;
+  } finally {
+    seen.delete(v);
+  }
+}
+
+function _emptyHandle(reason) {
+  return {
+    enabled: false, file: null, fd: null, runKey: null,
+    recovered: new Map(), order: [], written: new Set(),
+    discarded: false, reason,
+  };
+}
+
+function _headerLine(runKey) {
+  return JSON.stringify({ v: FORMAT, runKey }) + '\n';
+}
+
+// Read forward from a byte offset, keeping records while they verify. Returns
+// the offset of the first byte that did NOT verify, so the caller can truncate.
+function _recover(handle, file, runKey) {
+  let buf;
+  try { buf = fs.readFileSync(file); }
+  catch { return -1; } // no file yet
+  const text = buf.toString('utf8');
+  const nl = text.indexOf('\n');
+  if (nl < 0) return 0;
+  let header = null;
+  try { header = JSON.parse(text.slice(0, nl)); } catch { return 0; }
+  if (!header || header.v !== FORMAT || header.runKey !== runKey) return 0;
+
+  let offset = Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
+  let cursor = nl + 1;
+  for (;;) {
+    const end = text.indexOf('\n', cursor);
+    if (end < 0) break;                       // torn tail: no terminating newline
+    const line = text.slice(cursor, end);
+    cursor = end + 1;
+    if (!line) { offset = Buffer.byteLength(text.slice(0, cursor), 'utf8'); continue; }
+    let rec;
+    try { rec = JSON.parse(line); } catch { break; }
+    if (!rec || typeof rec.f !== 'string' || typeof rec.d !== 'string') break;
+    if (rec.c !== _sha(rec.d)) break;         // tampered or torn-then-patched
+    let payload;
+    try { payload = JSON.parse(rec.d); } catch { break; }
+    if (!handle.recovered.has(rec.f)) handle.order.push(rec.f);
+    handle.recovered.set(rec.f, payload);
+    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
+  }
+  return offset;
+}
+
+/**
+ * Open (or start) the checkpoint for `scanRoot` under `runKey`. Never throws.
+ * A handle whose `enabled` is false silently no-ops through the rest of the API.
+ */
+export function openCheckpoint(scanRoot, { runKey } = {}) {
+  if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+  const handle = _emptyHandle(null);
+  try {
+    const dir = path.join(scanRoot, STATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = checkpointPath(scanRoot);
+    handle.file = file;
+    handle.runKey = runKey;
+
+    const keepBytes = _recover(handle, file, runKey);
+    if (keepBytes <= 0) {
+      // Absent, foreign, or unreadable — start clean. Conservative by design.
+      handle.recovered.clear();
+      handle.order.length = 0;
+      handle.discarded = keepBytes === 0;
+      fs.writeFileSync(file, _headerLine(runKey));
+    } else {
+      // Drop any torn tail so appends land after the last verified record.
+      try {
+        const size = fs.statSync(file).size;
+        if (size !== keepBytes) fs.truncateSync(file, keepBytes);
+      } catch { /* best-effort */ }
+    }
+
+    handle.fd = fs.openSync(file, 'a');
+    handle.enabled = true;
+  } catch (e) {
+    try { if (handle.fd !== null) fs.closeSync(handle.fd); } catch { /* ignore */ }
+    return _emptyHandle(String((e && e.message) || e));
+  }
+  return handle;
+}
+
+/**
+ * Durably record that `relPath` is fully analysed, along with everything that
+ * analysis produced. `findings` is the per-file payload object (see the engine
+ * call site); it must be plain JSON data. Returns true only if the record is on
+ * disk and fsync'd.
+ */
+export function recordFileDone(handle, relPath, findings) {
+  if (!handle || !handle.enabled || handle.fd === null || typeof relPath !== 'string') return false;
+  try {
+    if (!_jsonSafe(findings)) return false;
+    const d = JSON.stringify(findings === undefined ? null : findings);
+    if (typeof d !== 'string') return false;
+    const line = JSON.stringify({ f: relPath, c: _sha(d), d }) + '\n';
+    fs.writeSync(handle.fd, line);
+    fs.fsyncSync(handle.fd);
+    handle.written.add(relPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Files already analysed — recovered from a prior run plus written by this one. */
+export function completedFiles(handle) {
+  const out = new Set();
+  if (!handle) return out;
+  for (const f of handle.recovered ? handle.recovered.keys() : []) out.add(f);
+  for (const f of handle.written || []) out.add(f);
+  return out;
+}
+
+/** Recovered per-file payloads, in the order they were originally recorded. */
+export function resumeFindings(handle) {
+  if (!handle || !handle.recovered) return [];
+  return (handle.order || []).map(file => ({ file, findings: handle.recovered.get(file) }));
+}
+
+/**
+ * Close the handle. `complete: true` means the scan finished — the checkpoint is
+ * removed so the next run cannot resume state that has already been consumed.
+ */
+export function closeCheckpoint(handle, { complete = false } = {}) {
+  if (!handle || !handle.enabled) return false;
+  let ok = true;
+  try { if (handle.fd !== null) fs.closeSync(handle.fd); } catch { ok = false; }
+  handle.fd = null;
+  handle.enabled = false;
+  if (complete && handle.file) {
+    try { fs.rmSync(handle.file, { force: true }); } catch { ok = false; }
+  }
+  return ok;
+}

package/src/posture/suppressions.js

@@ -7,7 +7,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState } from './state-dir.js';
 
 const MS_PER_DAY = 86400000;

package/src/posture/test-runner.js

@@ -0,0 +1,147 @@
+// R5 (partial, roadmap) — the project's own test suite as a verification
+// stage for `verifyFix()` (see `fix-verify.js`). Closes the gap where a
+// "verified" fix only proved a finding's stableId stopped firing — a patch
+// that deletes the feature entirely would satisfy that just as well as a
+// real fix. Running the project's own tests is the cheapest available check
+// that the application still works.
+//
+// Execution-safety note: this spawns the TARGET PROJECT's own test command
+// in the target project's own directory. That is deliberately NOT routed
+// through the R1 confinement sandbox (`../sandbox/`). That sandbox exists to
+// contain untrusted proof-of-concept exploit code the scanner itself
+// synthesizes — code nobody has vetted, being run for the first time. A
+// project's pre-existing test suite is the opposite case: it is the
+// project's own trusted source, already sitting on disk, and running it is
+// exactly what a human developer does by hand before trusting a fix.
+// Wrapping "npm test" / "pytest" / "go test" in the PoC sandbox's
+// syscall/network/filesystem restrictions would break the large majority of
+// real test suites (they bind local ports, spawn child processes, write temp
+// fixtures, etc.) for no corresponding security benefit.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const NPM_PLACEHOLDER = /Error: no test specified/i;
+
+function _exists(scanRoot, rel) {
+  try { return fs.existsSync(path.join(scanRoot, rel)); } catch { return false; }
+}
+
+function _isDir(scanRoot, rel) {
+  try { return fs.statSync(path.join(scanRoot, rel)).isDirectory(); } catch { return false; }
+}
+
+function _binaryAvailable(cmd) {
+  try {
+    const r = spawnSync(cmd, ['--version'], { timeout: 5_000, stdio: 'ignore' });
+    return !(r.error && r.error.code === 'ENOENT');
+  } catch {
+    return false;
+  }
+}
+
+// Detect the project's test command. Read-only — never spawns the actual
+// test run, only (optionally) a cheap `--version` probe to confirm a tool
+// like `pytest` is actually installed before committing to it. Returns
+// `null` when nothing detectable is found — most scanned repos will hit
+// this path, and that must not be treated as a failure by callers.
+export function detectTestCommand(scanRoot) {
+  if (!scanRoot) return null;
+
+  // JS/TS — package.json with a real (non-placeholder) `scripts.test`.
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(scanRoot, 'package.json'), 'utf8')); } catch { pkg = null; }
+  const testScript = pkg && pkg.scripts && pkg.scripts.test;
+  if (testScript && !NPM_PLACEHOLDER.test(String(testScript))) {
+    if (_exists(scanRoot, 'pnpm-lock.yaml')) return { cmd: 'pnpm', args: ['test'], kind: 'pnpm' };
+    if (_exists(scanRoot, 'yarn.lock')) return { cmd: 'yarn', args: ['test'], kind: 'yarn' };
+    if (_exists(scanRoot, 'bun.lockb') || _exists(scanRoot, 'bun.lock')) return { cmd: 'bun', args: ['test'], kind: 'bun' };
+    return { cmd: 'npm', args: ['test', '--silent'], kind: 'npm' };
+  }
+
+  // Python — pytest.ini / pyproject.toml / tox.ini / a tests/ dir, and the
+  // `pytest` binary actually available. If pytest isn't installed we do NOT
+  // report a python test command — falling through lets a later language
+  // marker (e.g. go.mod in a polyglot repo) still be detected.
+  const pyMarker = _exists(scanRoot, 'pytest.ini') || _exists(scanRoot, 'pyproject.toml') ||
+    _exists(scanRoot, 'tox.ini') || _isDir(scanRoot, 'tests');
+  if (pyMarker && _binaryAvailable('pytest')) {
+    return { cmd: 'pytest', args: ['-q'], kind: 'pytest' };
+  }
+
+  // Go
+  if (_exists(scanRoot, 'go.mod')) {
+    return { cmd: 'go', args: ['test', './...'], kind: 'go' };
+  }
+
+  return null;
+}
+
+// Run the detected test command with a walltime budget. Always returns a
+// result object — never throws. Distinguishes four outcomes:
+//   - no detectable/runnable command  -> status: 'skipped'  (does NOT fail)
+//   - ran and exited 0                -> status: 'passed'
+//   - ran and exited non-zero         -> status: 'failed'
+//   - ran past the timeout budget     -> status: 'failed', timedOut: true
+export function runProjectTests(scanRoot, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const startedAt = Date.now();
+  const command = detectTestCommand(scanRoot);
+  if (!command) {
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: 'no-test-command-detected', exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  let r;
+  try {
+    r = spawnSync(command.cmd, command.args, {
+      cwd: scanRoot,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      env: { ...process.env, CI: '1' },
+    });
+  } catch (e) {
+    // The spawn call itself threw (rare — e.g. cwd vanished). Treat as
+    // "could not run", not "ran and failed".
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `spawn-error: ${e.message}`, exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  const durationMs = Date.now() - startedAt;
+
+  if (r.error && r.error.code === 'ENOENT') {
+    // The detected tool isn't actually installed on this machine. Not a
+    // test failure — the suite never ran.
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `${command.kind}-not-installed`, exitCode: null, timedOut: false, durationMs,
+    };
+  }
+
+  if (r.status === null) {
+    // spawnSync sets status:null both on timeout-kill and on being killed by
+    // another signal; either way the run did not complete, which is a
+    // verification failure, never a skip — we asked for a result and the
+    // process was terminated before producing one.
+    return {
+      status: 'failed', passed: false, skipped: false,
+      reason: 'timed-out', exitCode: null, timedOut: true, durationMs,
+    };
+  }
+
+  return {
+    status: r.status === 0 ? 'passed' : 'failed',
+    passed: r.status === 0,
+    skipped: false,
+    reason: r.status === 0 ? null : 'test-failures',
+    exitCode: r.status,
+    timedOut: false,
+    durationMs,
+  };
+}

package/src/posture/verification-separation.js

@@ -0,0 +1,131 @@
+// R7 — adversarial verification with ENFORCED SEPARATION.
+//
+// The falsification pass (`falsification.js`) already tries to DISPROVE a
+// finding. What it could not previously do is *prove* that whoever checked the
+// finding was not whoever produced it. That guarantee is what this module adds,
+// plus a recorded multi-perspective verdict for contested findings.
+//
+// The property that matters: a verifier is structurally unable to rubber-stamp
+// its own finding.
+//   - `recordProducer` stamps who produced the finding, WRITE-ONCE. A later
+//     party cannot re-stamp itself as the producer to manufacture separation.
+//   - `assertSeparation` refuses when the verifier id equals the recorded
+//     producer id, and FAILS CLOSED when no producer was recorded at all
+//     (separation that cannot be established is not separation).
+//   - `recordVerdict` runs that check itself, so there is no code path that
+//     records a verdict without it. One verifier gets one vote per lens: a
+//     re-vote replaces the previous one rather than stuffing the ballot.
+//
+// RECALL-PRESERVING, same precedent as `falsification.js` and
+// `dataflow/proof-gate.js`: nothing here ever removes a finding and nothing
+// here ever touches `severity`. A `refuted` consensus is a triage signal, not
+// a deletion — absence of proof is not proof of absence.
+//
+// NO THROWING (posture/CLAUDE.md convention): every entry point returns a
+// refusal object `{ ok:false, refused:true, reason }` instead of throwing, so
+// an annotator can call it inside the engine's pipeline without a guard.
+
+export const VERIFICATION_VERDICTS = ['upheld', 'refuted', 'undecided'];
+
+// Verifier ids are namespaced so they can never collide with a producer id.
+export const VERIFIER_FALSIFICATION = 'verifier:falsification';
+export const VERIFIER_LLM_REVIEW = 'verifier:llm-review';
+
+function _refuse(reason) { return { ok: false, refused: true, reason }; }
+
+/** Namespaced id for whoever produced a finding — derived from its detector. */
+export function producerIdOf(finding) {
+  const p = finding && finding.parser ? String(finding.parser) : 'unknown';
+  return `detector:${p}`;
+}
+
+/**
+ * Stamp who produced this finding. Write-once: a second call with a different
+ * id is REFUSED (this is what stops a verifier reassigning provenance to
+ * itself). A repeat call with the same id is a no-op success.
+ */
+export function recordProducer(finding, producerId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const id = producerId ? String(producerId) : '';
+  if (!id) return _refuse('no producer id');
+  if (!finding.verification || typeof finding.verification !== 'object') {
+    finding.verification = { producer: id, verdicts: [] };
+    return { ok: true, producer: id };
+  }
+  if (!finding.verification.producer) {
+    finding.verification.producer = id;
+    if (!Array.isArray(finding.verification.verdicts)) finding.verification.verdicts = [];
+    return { ok: true, producer: id };
+  }
+  if (finding.verification.producer === id) return { ok: true, producer: id };
+  return _refuse(`producer already recorded as "${finding.verification.producer}" — write-once`);
+}
+
+/**
+ * The separation check. `{ ok:true, producer }` when the verifier is a party
+ * other than the producer; a refusal otherwise. Fails closed when no producer
+ * has been recorded.
+ */
+export function assertSeparation(finding, verifierId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const vid = verifierId ? String(verifierId) : '';
+  if (!vid) return _refuse('no verifier id');
+  const producer = finding.verification && finding.verification.producer;
+  if (!producer) {
+    return _refuse('no producer recorded — separation cannot be established');
+  }
+  if (producer === vid) {
+    return _refuse(`verifier "${vid}" is the producer of this finding — separation violated`);
+  }
+  return { ok: true, producer };
+}
+
+/**
+ * Record one verifier's verdict from one perspective (`lens`, e.g.
+ * 'reachability' | 'control-flow' | 'data-shape'). Refuses — recording
+ * nothing — when separation fails or the verdict is not one of
+ * VERIFICATION_VERDICTS. Never touches severity, never removes anything.
+ */
+export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {}) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  if (!lens) return _refuse('no lens');
+  if (!VERIFICATION_VERDICTS.includes(verdict)) {
+    return _refuse(`unknown verdict "${verdict}" — expected one of ${VERIFICATION_VERDICTS.join('|')}`);
+  }
+  const sep = assertSeparation(finding, verifierId);
+  if (!sep.ok) return sep;
+
+  const entry = {
+    verifierId: String(verifierId),
+    lens: String(lens),
+    verdict,
+    ...(reason ? { reason: String(reason) } : {}),
+  };
+  const list = finding.verification.verdicts;
+  const i = list.findIndex(v => v.verifierId === entry.verifierId && v.lens === entry.lens);
+  if (i >= 0) list[i] = entry; else list.push(entry);
+  return { ok: true, recorded: entry };
+}
+
+/**
+ * Majority across every recorded verdict. Ties — including "no verdicts at
+ * all" — are 'undecided'. `lenses` is the sorted set of perspectives that
+ * actually voted, so a caller can see whether a verdict is one-eyed or a panel.
+ */
+export function consensusOf(finding) {
+  const list = (finding && finding.verification && Array.isArray(finding.verification.verdicts))
+    ? finding.verification.verdicts : [];
+  let upheld = 0, refuted = 0, undecided = 0;
+  const lenses = new Set();
+  for (const v of list) {
+    if (!v) continue;
+    if (v.lens) lenses.add(String(v.lens));
+    if (v.verdict === 'upheld') upheld++;
+    else if (v.verdict === 'refuted') refuted++;
+    else if (v.verdict === 'undecided') undecided++;
+  }
+  let verdict = 'undecided';
+  if (upheld > refuted) verdict = 'upheld';
+  else if (refuted > upheld) verdict = 'refuted';
+  return { verdict, upheld, refuted, undecided, lenses: [...lenses].sort() };
+}

package/src/report/index.js

@@ -180,6 +180,11 @@ export function normalizeFindings(scan){
         paramKeyConfidence: f.poc.paramKeyConfidence || null,
         paramKeyInferred: typeof f.poc.paramKeyInferred === 'boolean' ? f.poc.paramKeyInferred : null,
       } : null,
+      // R2: execution-proof tier — copied through only when the annotator
+      // (posture/proof-tier.js) actually attached it. Never synthesised here;
+      // a finding with no proof backing simply omits these fields.
+      ...(f.proofTier !== undefined ? { proofTier: f.proofTier } : {}),
+      ...(f.proofEvidence !== undefined ? { proofEvidence: f.proofEvidence } : {}),
       // Phase-1 next-gen P1.3 (FR-UX-1, FR-UX-2): calibrated probability +
       // 95% Wilson CI + sample size. Null when N < MIN_SAMPLES_FOR_CALIBRATION
       // for this family; `calibration_reason` explains why.
@@ -401,6 +406,12 @@ export function toJSON(scan, meta={}, opts={}){
     // threw and were skipped. The findings still ship; downstream consumers
     // see the gap.
     annotatorErrors: Array.isArray(scan.annotatorErrors) ? scan.annotatorErrors : [],
+    // R4 — run attestation: a stable, order-independent digest over this
+    // finding set bound to the engine/ruleset/bundle that produced it.
+    // Attached by the CLI (posture/attestation.js); null when not computed.
+    // It carries its own `proves` / `doesNotProve` statement — do not quote
+    // the digest as cross-machine reproducibility, which it is not.
+    attestation: scan.attestation || null,
     _scanMeta: scan._scanMeta || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];

package/src/runScan.js

@@ -122,7 +122,9 @@ export async function runScan(rootDir, opts = {}) {
     }
   }
 
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root }, opts.onProgress || (()=>{}));
+  // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
+  // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}