atris 3.79.0 → 3.80.0

package/lib/security-audit.js

@@ -0,0 +1,1519 @@
+'use strict';
+
+// atris security audit: the sentinel's coverage-led, cross-model audit.
+//
+// The deterministic scan (lib/security-scan.js) answers "did a secret get
+// committed". This answers "can someone with less trust make this code do
+// something it should not", with the method from
+// cloudflare/security-audit-skill (MIT), rebuilt on Atris engines:
+//
+//   1. map      free, deterministic: every source file x attack class that has
+//               a reason to be looked at becomes a coverage unit in a ledger.
+//   2. hunt     read-only engine hunters each own a few units and return one
+//               JSON result per unit: covered, candidate, or blocked.
+//   3. critic   a fresh engine reads the ledger and names missed areas.
+//   4. verify   every candidate goes to a different model that tries to
+//               disprove it. Cited file:line must resolve before any spend.
+//   5. recheck  confirmed records get one more fresh read of the final words.
+//   6. report   REPORT.md, FINDINGS-DETAIL.md, NEEDS-VALIDATION.md, built only
+//               from records that passed both validators.
+//
+// Runs are additive. Each run reads the last ledger, skips units whose source
+// has not changed, re-checks old findings, and spends its budget on what is
+// left, so the nightly loop covers the repo slice by slice.
+//
+// Nothing is written inside the target. Output defaults to
+// ~/.atris/security-audit/<repo>/run-<N>. Engines run read-only and never
+// execute target code, so every confirmed record says it was source-traced.
+//
+// Zero external deps (Node built-ins only).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const {
+  CLASSES, CLASS_BY_ID, HUNT_METHOD, CANDIDATE_GATE, SEVERITY_ANCHORS,
+} = require('./security-audit-classes');
+
+const PROFILES = ['quick', 'standard', 'deep'];
+const DEFAULT_BUDGET = { quick: 8, standard: 20, deep: 48 };
+const MAX_WAVES = { quick: 1, standard: 2, deep: 3 };
+const UNITS_PER_HUNTER = { quick: 1, standard: 4, deep: 2 };
+const MAX_UNITS = 10000;
+const MAX_HOT_LINES = 6;
+const MAX_QUICK_PATHS = 8;
+const MAX_FILE_BYTES = 512 * 1024;
+const AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/;
+const FINGERPRINT_RE = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$/;
+const SCORES = ['informational', 'low', 'medium', 'high', 'critical'];
+const SCORE_RANK = Object.fromEntries(SCORES.map((s, i) => [s, i]));
+const STATUSES = ['planned', 'not_applicable', 'out_of_scope', 'deferred', 'in_progress', 'blocked', 'covered', 'candidate'];
+const CONDITION_KINDS = ['authentication_level', 'authorization_role', 'user_interaction', 'system_configuration', 'network_routing', 'environmental_dependency', 'data_state', 'timing_dependency', 'third_party_dependency'];
+const SKIP_PARTS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', 'out', 'vendor', '.cache', '__pycache__', '_archive', '.agent-worktrees']);
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__|spec|specs|fixtures?|testdata|__mocks__|e2e)(?:\/|$)|\.(?:test|spec)\.[a-z]+$|_test\.(?:go|py)$/i;
+const SEVERE = new Set(['critical', 'high']);
+
+// ---------------------------------------------------------------- identity
+
+// RFC 3986 percent encoding of the UTF-8 bytes: lossless, so two different
+// references can never collapse into one coverage id.
+function encodeRef(value) {
+  const text = String(value);
+  if (!text || text !== text.trim() || text.normalize('NFC') !== text || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(text)) {
+    throw new Error(`bad canonical reference: ${JSON.stringify(text)}`);
+  }
+  let out = '';
+  for (const byte of Buffer.from(text, 'utf8')) {
+    const ch = String.fromCharCode(byte);
+    out += /[A-Za-z0-9\-._~]/.test(ch) ? ch : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+  }
+  return out;
+}
+
+function coverageId(refs) {
+  const parts = [refs.surface, refs.boundary, refs.subsystem, refs.attack_class].map(encodeRef);
+  if (refs.lifecycle) parts.push(encodeRef(refs.lifecycle));
+  return parts.join('::');
+}
+
+function validAgentId(id) {
+  return typeof id === 'string' && AGENT_ID_RE.test(id) && !WINDOWS_DEVICE.test(id);
+}
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+// ---------------------------------------------------------------- files
+
+function relPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+// A path an engine wrote, made repo-relative. Absolute paths inside the root
+// are accepted (models cite them); anything that escapes is refused.
+function normalizeRepoPath(root, raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  let value = raw.trim().replace(/^\.\/+/, '').replace(/:\d+(?::\d+)?$/, '');
+  if (path.isAbsolute(value)) {
+    const rel = path.relative(root, value);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    value = rel;
+  }
+  value = relPosix(path.normalize(value));
+  if (!value || value === '.' || value.startsWith('../') || value === '..' || path.isAbsolute(value)) return null;
+  return value;
+}
+
+function listFiles(root) {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
+    return out.split('\0').filter(Boolean);
+  } catch {
+    const files = [];
+    const walk = (dir) => {
+      let entries = [];
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (SKIP_PARTS.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.isFile()) files.push(relPosix(path.relative(root, full)));
+      }
+    };
+    walk(root);
+    return files.sort();
+  }
+}
+
+function skippedPath(rel) {
+  return rel.split('/').some((part) => SKIP_PARTS.has(part));
+}
+
+function inScope(rel, scope) {
+  if (!scope.length) return true;
+  return scope.some((s) => rel === s || rel.startsWith(s.endsWith('/') ? s : `${s}/`));
+}
+
+// Inside the real root, after every symlink is resolved.
+function containedIn(rootReal, real) {
+  const rel = path.relative(rootReal, real);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+
+const realRoots = new Map();
+function realRoot(root) {
+  if (!realRoots.has(root)) {
+    let real = root;
+    try { real = fs.realpathSync(root); } catch {}
+    realRoots.set(root, real);
+  }
+  return realRoots.get(root);
+}
+
+function readText(root, rel) {
+  try {
+    const full = path.join(root, rel);
+    const stat = fs.lstatSync(full);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return null;
+    if (!containedIn(realRoot(root), fs.realpathSync(full))) return null;
+    const text = fs.readFileSync(full, 'utf8');
+    return text.includes('\u0000') ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+function subsystemOf(rel) {
+  const parts = rel.split('/');
+  if (parts.length === 1) return '.';
+  if (parts.length > 2 && ['packages', 'apps', 'services', 'src'].includes(parts[0])) return `${parts[0]}/${parts[1]}`;
+  return parts[0];
+}
+
+function sourceDigest(root, paths) {
+  const h = crypto.createHash('sha256');
+  for (const rel of [...paths].sort()) {
+    const text = readText(root, rel);
+    h.update(`${rel}\0${text === null ? 'missing' : sha256(text)}\0`);
+  }
+  return h.digest('hex');
+}
+
+function gitSourceRef(root) {
+  try {
+    const commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const dirty = execFileSync('git', ['status', '--porcelain', '--untracked-files=no'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().length > 0;
+    return { commit, dirty };
+  } catch {
+    return { commit: null, dirty: null };
+  }
+}
+
+function repoName(root) {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const m = url.match(/([^/:]+?)(?:\.git)?$/);
+    if (m && m[1]) return m[1].replace(/[^A-Za-z0-9._-]/g, '-');
+  } catch {}
+  return path.basename(path.resolve(root)).replace(/[^A-Za-z0-9._-]/g, '-') || 'repo';
+}
+
+function writeJson(file, value) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// ---------------------------------------------------------------- map (phase 1)
+
+function classesForFile(rel) {
+  const ext = path.extname(rel).toLowerCase();
+  return CLASSES.filter((c) => (c.files ? c.files(rel) : c.exts && c.exts.has(ext)));
+}
+
+function detectHits(text, cls) {
+  const hits = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length && hits.length < 200; i++) {
+    const line = lines[i];
+    if (line.length > 2000) continue;
+    if (cls.detect.some((re) => re.test(line))) hits.push({ line: i + 1, text: line.trim().slice(0, 160) });
+  }
+  return hits;
+}
+
+function classPriority(cls, rel, hits) {
+  let p = cls.weight * 10 + Math.min(hits, 10);
+  if (/^(?:bin|commands|lib|src|server|api|app|routes|utils)\//.test(rel) || !rel.includes('/')) p += 5;
+  if (/^(?:scripts|examples|docs|benchmarks?)\//.test(rel)) p -= 20;
+  return p;
+}
+
+function newUnit({ refs, surface, boundary, subsystem, attackClass, paths, hot, priority, digest }) {
+  return {
+    coverage_id: coverageId(refs),
+    canonical_refs: refs,
+    surface,
+    boundary,
+    subsystem,
+    attack_class: attackClass,
+    starting_paths: paths,
+    hot_lines: hot,
+    source_digest: digest,
+    priority,
+    prior_status: 'none',
+    attempts: [],
+    wave: 1,
+    status: 'planned',
+    agent_id: null,
+    reviewed_paths: [],
+    local_checks: [],
+    result_fingerprints: [],
+    unresolved: [],
+    hardening: [],
+  };
+}
+
+// Deterministic recon. The same source gives the same ledger every time, and
+// costs nothing, so the whole budget goes to hunters and verifiers.
+function mapTarget(root, { profile = 'standard', scope = [] } = {}) {
+  const all = listFiles(root).filter((rel) => !skippedPath(rel));
+  const perFileClass = [];
+  const stats = { files: all.length, source_files: 0, test_files_skipped: 0, out_of_scope_files: 0, languages: {} };
+  const outOfScope = new Map();
+  for (const rel of all) {
+    const classes = classesForFile(rel);
+    if (!classes.length) continue;
+    if (TEST_PATH.test(rel)) { stats.test_files_skipped += 1; continue; }
+    const text = readText(root, rel);
+    if (text === null) continue;
+    stats.source_files += 1;
+    const ext = path.extname(rel).toLowerCase() || path.basename(rel);
+    stats.languages[ext] = (stats.languages[ext] || 0) + 1;
+    for (const cls of classes) {
+      const hits = detectHits(text, cls);
+      if (!hits.length) continue;
+      if (!inScope(rel, scope)) {
+        stats.out_of_scope_files += 1;
+        const key = `${subsystemOf(rel)}\0${cls.id}`;
+        if (!outOfScope.has(key)) outOfScope.set(key, { subsystem: subsystemOf(rel), cls, paths: [] });
+        outOfScope.get(key).paths.push(rel);
+        continue;
+      }
+      perFileClass.push({ rel, cls, hits });
+    }
+  }
+
+  const units = [];
+  if (profile === 'quick') {
+    const groups = new Map();
+    for (const item of perFileClass) {
+      const key = `${subsystemOf(item.rel)}\0${item.cls.id}`;
+      if (!groups.has(key)) groups.set(key, { subsystem: subsystemOf(item.rel), cls: item.cls, items: [] });
+      groups.get(key).items.push(item);
+    }
+    for (const g of groups.values()) {
+      g.items.sort((a, b) => b.hits.length - a.hits.length || a.rel.localeCompare(b.rel));
+      const top = g.items.slice(0, MAX_QUICK_PATHS);
+      const paths = top.map((i) => i.rel);
+      const surface = `${g.subsystem}/*`;
+      const refs = { surface, boundary: `classes#${g.cls.id}/boundary`, subsystem: 'profile/quick/all-in-scope-subsystems', attack_class: `classes#${g.cls.id}` };
+      const hot = top.flatMap((i) => i.hits.slice(0, 2).map((h) => ({ file: i.rel, ...h }))).slice(0, MAX_HOT_LINES);
+      const totalHits = g.items.reduce((n, i) => n + i.hits.length, 0);
+      const unit = newUnit({ refs, surface, boundary: g.cls.boundary, subsystem: g.subsystem, attackClass: g.cls.id, paths, hot, priority: classPriority(g.cls, paths[0], totalHits) + Math.min(g.items.length, 10), digest: sourceDigest(root, paths) });
+      unit.files_in_group = g.items.length;
+      units.push(unit);
+    }
+  } else {
+    for (const { rel, cls, hits } of perFileClass) {
+      const refs = { surface: rel, boundary: `classes#${cls.id}/boundary`, subsystem: subsystemOf(rel), attack_class: `classes#${cls.id}` };
+      units.push(newUnit({
+        refs, surface: rel, boundary: cls.boundary, subsystem: subsystemOf(rel), attackClass: cls.id,
+        paths: [rel], hot: hits.slice(0, MAX_HOT_LINES).map((h) => ({ file: rel, ...h })),
+        priority: classPriority(cls, rel, hits.length), digest: sourceDigest(root, [rel]),
+      }));
+    }
+  }
+  for (const g of outOfScope.values()) {
+    const surface = `${g.subsystem}/*`;
+    const refs = { surface, boundary: `classes#${g.cls.id}/boundary`, subsystem: g.subsystem, attack_class: `classes#${g.cls.id}`, lifecycle: 'scope/out-of-scope' };
+    const unit = newUnit({ refs, surface, boundary: g.cls.boundary, subsystem: g.subsystem, attackClass: g.cls.id, paths: g.paths.slice(0, MAX_QUICK_PATHS), hot: [], priority: 0, digest: '' });
+    unit.status = 'out_of_scope';
+    unit.unresolved = ['outside the paths this run was asked to audit'];
+    units.push(unit);
+  }
+  units.sort((a, b) => (a.coverage_id < b.coverage_id ? -1 : a.coverage_id > b.coverage_id ? 1 : 0));
+  const truncated = units.length > MAX_UNITS;
+  return { units: truncated ? topByPriority(units, MAX_UNITS) : units, stats, truncated };
+}
+
+function topByPriority(units, n) {
+  return [...units].sort((a, b) => b.priority - a.priority || cmpId(a, b)).slice(0, n).sort(cmpId);
+}
+
+function cmpId(a, b) {
+  return a.coverage_id < b.coverage_id ? -1 : a.coverage_id > b.coverage_id ? 1 : 0;
+}
+
+function architectureText({ repo, root, stats, units, scope, profile, prior, scanSeeds }) {
+  const byClass = {};
+  const bySub = {};
+  for (const u of units) {
+    if (u.status === 'out_of_scope') continue;
+    byClass[u.attack_class] = (byClass[u.attack_class] || 0) + 1;
+    bySub[u.subsystem] = (bySub[u.subsystem] || 0) + 1;
+  }
+  const langs = Object.entries(stats.languages).sort((a, b) => b[1] - a[1]).slice(0, 6).map(([k, v]) => `${k} ${v}`).join(', ');
+  const subs = Object.entries(bySub).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([k, v]) => `${k} (${v})`).join(', ');
+  const classes = Object.entries(byClass).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join(', ');
+  const lines = [
+    `# Architecture: ${repo}`,
+    '',
+    `Target: ${root}`,
+    `Profile: ${profile}${scope.length ? `, scoped to ${scope.join(', ')}` : ''}`,
+    `Tracked files: ${stats.files}. Source files read: ${stats.source_files}. Test files left out: ${stats.test_files_skipped}.`,
+    `Languages: ${langs || 'none detected'}.`,
+    `Subsystems with review surface: ${subs || 'none'}.`,
+    `Coverage units by attack class: ${classes || 'none'}.`,
+    prior ? `Prior run: ${prior.dir} (${prior.units} units, ${prior.findings} records).` : 'Prior run: none. This is the first ledger for this repo, so coverage starts from zero.',
+  ];
+  if (scanSeeds.length) {
+    lines.push('', 'Deterministic scan evidence (lib/security-scan.js) at high or critical:');
+    for (const f of scanSeeds.slice(0, 12)) lines.push(`- ${f.file}${f.line ? `:${f.line}` : ''} ${f.rule}: ${f.why}`);
+  }
+  lines.push('', 'Detection lines only seed coverage. A hit is a place to look, never a finding.');
+  return `${lines.join('\n')}\n`;
+}
+
+// ---------------------------------------------------------------- prior runs
+
+function auditHome() {
+  return process.env.ATRIS_SECURITY_AUDIT_HOME || path.join(os.homedir(), '.atris', 'security-audit');
+}
+
+function runDirs(outRoot) {
+  let names = [];
+  try { names = fs.readdirSync(outRoot); } catch { return []; }
+  return names
+    .map((n) => ({ n, m: n.match(/^run-(\d+)$/) }))
+    .filter((x) => x.m)
+    .map((x) => ({ dir: path.join(outRoot, x.n), num: Number(x.m[1]) }))
+    .sort((a, b) => a.num - b.num);
+}
+
+function loadPrior(outRoot, exclude) {
+  const runs = runDirs(outRoot).filter((r) => r.dir !== exclude).reverse();
+  for (const r of runs) {
+    const ledger = readJson(path.join(r.dir, 'coverage-ledger.json'));
+    if (!Array.isArray(ledger)) continue;
+    const meta = readJson(path.join(r.dir, 'run-metadata.json'));
+    if (meta && meta.incomplete_reason === 'plan_only') continue;
+    // Records a run could not re-check wait in carried-pending.json so a
+    // cheap or cut-short run never makes an old finding disappear.
+    const findings = readJson(path.join(r.dir, 'findings.json'));
+    const pending = readJson(path.join(r.dir, 'carried-pending.json'));
+    const all = [...(Array.isArray(findings) ? findings : []), ...(Array.isArray(pending) ? pending : [])];
+    return { dir: r.dir, ledger, findings: all, units: ledger.length, findingsCount: all.length };
+  }
+  return null;
+}
+
+// Fold the last ledger in. Unchanged covered units stay covered (with their
+// old evidence, marked carried) so the budget goes somewhere new; changed or
+// unfinished units come back as planned and jump the queue.
+function mergePrior(units, prior) {
+  const carried = [];
+  const exclusions = [];
+  if (!prior) return { carried, exclusions };
+  const priorById = new Map(prior.ledger.map((u) => [u.coverage_id, u]));
+  const unitById = new Map(units.map((u) => [u.coverage_id, u]));
+  for (const u of units) {
+    u.prior_status = 'new';
+    if (u.status === 'out_of_scope') continue;
+    const p = priorById.get(u.coverage_id);
+    if (!p) { u.priority += 15; continue; }
+    const same = p.source_digest && p.source_digest === u.source_digest;
+    if (p.status === 'covered') {
+      if (same) {
+        u.prior_status = 'prior_covered_same_source';
+        u.status = 'covered';
+        u.carried_from = prior.dir;
+        u.agent_id = p.agent_id;
+        u.reviewed_paths = p.reviewed_paths || [];
+        u.local_checks = p.local_checks || [];
+        u.wave = p.wave || 1;
+      } else {
+        u.prior_status = 'prior_covered_changed_source';
+        u.priority += 30;
+      }
+    } else if (p.status === 'candidate') {
+      u.prior_status = same ? 'prior_confirmed_same_source' : 'prior_confirmed_changed_source';
+      u.priority += 30;
+    } else if (['deferred', 'blocked', 'planned', 'in_progress'].includes(p.status)) {
+      u.prior_status = p.status === 'blocked' ? 'prior_blocked' : 'prior_deferred';
+      u.priority += 20;
+    } else if (p.status === 'out_of_scope') {
+      u.prior_status = 'prior_out_of_scope';
+      u.priority += 20;
+    }
+  }
+  for (const rec of prior.findings) {
+    if (!rec || !rec.fingerprint) continue;
+    const ids = Array.isArray(rec.coverage_ids) ? rec.coverage_ids : [];
+    const linked = ids.map((id) => unitById.get(id)).filter(Boolean);
+    // Every linked area must still exist, be in scope, and be unchanged.
+    const unchanged = linked.length > 0 && linked.length === ids.length && linked.every((u) => {
+      if (u.status === 'out_of_scope') return false;
+      const p = priorById.get(u.coverage_id);
+      return p && p.source_digest === u.source_digest;
+    });
+    if (rec.verdict === 'rejected') {
+      if (unchanged) exclusions.push({ fingerprint: rec.fingerprint, title: rec.title || '', why: 'disproved last run' });
+      continue;
+    }
+    if (unchanged) {
+      carried.push({ ...rec, carried_from: prior.dir });
+      exclusions.push({ fingerprint: rec.fingerprint, title: rec.title || '', why: 'already on record, being re-checked' });
+      // The verifier that re-checks this record owns these units; hunters
+      // skip them so the same root cause is not paid for twice.
+      for (const u of linked) {
+        if (u.status === 'covered') continue;
+        resetUnit(u, 'planned');
+        u.reserved_for = [...new Set([...(u.reserved_for || []), rec.fingerprint])];
+      }
+    }
+  }
+  return { carried, exclusions };
+}
+
+// ---------------------------------------------------------------- validators
+
+function isRepoRel(p) {
+  return typeof p === 'string' && p.length > 0 && !path.isAbsolute(p) && !p.split('/').includes('..') && !p.includes('\\');
+}
+
+function validateLedger(units) {
+  const errors = [];
+  const push = (msg) => { if (errors.length < 100) errors.push(msg); };
+  if (!Array.isArray(units)) return ['ledger must be an array'];
+  const seen = new Map();
+  const tuples = new Map();
+  let prev = null;
+  units.forEach((u, i) => {
+    const at = `unit ${i} (${u && u.coverage_id})`;
+    if (!u || typeof u !== 'object') return push(`${at}: not an object`);
+    let expected = null;
+    try { expected = coverageId(u.canonical_refs || {}); } catch (e) { push(`${at}: ${e.message}`); }
+    if (expected && expected !== u.coverage_id) push(`${at}: coverage_id does not match canonical_refs`);
+    if (seen.has(u.coverage_id)) push(`${at}: duplicate coverage_id`);
+    seen.set(u.coverage_id, true);
+    const tuple = [u.surface, u.boundary, u.subsystem, u.attack_class, (u.canonical_refs || {}).lifecycle || ''].join('\0');
+    if (tuples.has(tuple) && tuples.get(tuple) !== u.coverage_id) push(`${at}: same unit under two canonical ids`);
+    tuples.set(tuple, u.coverage_id);
+    if (prev !== null && !(prev < u.coverage_id)) push(`${at}: ledger not sorted by coverage_id`);
+    prev = u.coverage_id;
+    if (!CLASS_BY_ID.has(u.attack_class)) push(`${at}: unknown attack_class`);
+    if (!STATUSES.includes(u.status)) return push(`${at}: unknown status ${u.status}`);
+    for (const p of [...(u.starting_paths || []), ...(u.reviewed_paths || [])]) if (!isRepoRel(p)) push(`${at}: path not repo-relative: ${p}`);
+    const reviewed = u.reviewed_paths || [];
+    const checks = u.local_checks || [];
+    const fps = u.result_fingerprints || [];
+    const unresolved = u.unresolved || [];
+    const empty = !reviewed.length && !checks.length && !fps.length;
+    const owner = u.agent_id;
+    switch (u.status) {
+      case 'planned':
+        if (owner !== null || !empty || unresolved.length) push(`${at}: planned must have no owner, evidence, or unresolved`);
+        break;
+      case 'not_applicable': case 'out_of_scope': case 'deferred':
+        if (owner !== null || !empty) push(`${at}: ${u.status} must have no owner or evidence`);
+        if (!unresolved.length) push(`${at}: ${u.status} needs a reason in unresolved`);
+        break;
+      case 'in_progress':
+        if (!validAgentId(owner) || !empty || unresolved.length) push(`${at}: in_progress needs an owner and no evidence`);
+        break;
+      case 'blocked':
+        if (!validAgentId(owner) || !reviewed.length || !checks.length || fps.length || !unresolved.length) push(`${at}: blocked needs owner, paths, checks, a blocker, and no fingerprints`);
+        break;
+      case 'covered':
+        if (!validAgentId(owner) || !reviewed.length || !checks.length || fps.length || unresolved.length) push(`${at}: covered needs owner, paths, checks, and nothing unresolved`);
+        break;
+      case 'candidate':
+        if (!validAgentId(owner) || !reviewed.length || !checks.length || !fps.length) push(`${at}: candidate needs owner, paths, checks, and fingerprints`);
+        break;
+      default: break;
+    }
+    if (checks.length) {
+      const union = new Set();
+      for (const c of checks) {
+        if (!validAgentId(c.agent_id)) push(`${at}: check has bad agent_id`);
+        if (!Array.isArray(c.reviewed_paths) || !c.reviewed_paths.length) push(`${at}: check has no reviewed_paths`);
+        for (const p of c.reviewed_paths || []) union.add(p);
+        if (c.method !== 'source' && c.method !== 'local') push(`${at}: check method must be source or local`);
+        if (c.method === 'source' && c.artifact !== null) push(`${at}: source check must have artifact null`);
+      }
+      const unitSet = new Set(reviewed);
+      if (union.size !== unitSet.size || [...union].some((p) => !unitSet.has(p))) push(`${at}: reviewed_paths must equal the union of check paths`);
+    }
+    for (const fp of fps) if (!FINGERPRINT_RE.test(fp)) push(`${at}: bad fingerprint ${fp}`);
+  });
+  return errors;
+}
+
+function nonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function validateTrace(trace, at, push, root) {
+  if (!Array.isArray(trace) || !trace.length) return push(`${at}: trace must be a nonempty array`);
+  trace.forEach((t, i) => {
+    if (!t || !['entrypoint', 'propagation', 'sink'].includes(t.kind)) push(`${at}: trace ${i} bad kind`);
+    if (!isRepoRel(t && t.file)) push(`${at}: trace ${i} file not repo-relative`);
+    if (!Number.isInteger(t && t.line) || t.line < 1) push(`${at}: trace ${i} line must be a positive integer`);
+    if (!nonEmptyString(t && t.description)) push(`${at}: trace ${i} needs a description`);
+    if (root && t && isRepoRel(t.file)) {
+      const text = readText(root, t.file);
+      if (text === null) push(`${at}: trace ${i} cites a file that does not exist: ${t.file}`);
+      else if (t.line > text.split('\n').length) push(`${at}: trace ${i} cites line ${t.line} past the end of ${t.file}`);
+    }
+  });
+  if (trace.length > 1) {
+    if (trace[0].kind !== 'entrypoint') push(`${at}: trace must start at entrypoint`);
+    if (trace[trace.length - 1].kind !== 'sink') push(`${at}: trace must end at sink`);
+    for (let i = 1; i < trace.length - 1; i++) if (trace[i].kind !== 'propagation') push(`${at}: middle trace steps must be propagation`);
+  }
+}
+
+// The findings contract. With root set, every cited file:line must resolve
+// in the current source, so a hallucinated citation cannot reach a report.
+function validateFindings(records, { root = null } = {}) {
+  const errors = [];
+  const push = (msg) => { if (errors.length < 100) errors.push(msg); };
+  if (!Array.isArray(records)) return ['findings must be an array'];
+  const seen = new Set();
+  records.forEach((r, i) => {
+    const at = `record ${i} (${r && r.fingerprint})`;
+    if (!r || typeof r !== 'object') return push(`${at}: not an object`);
+    if (!FINGERPRINT_RE.test(String(r.fingerprint || ''))) push(`${at}: bad fingerprint`);
+    if (seen.has(r.fingerprint)) push(`${at}: duplicate fingerprint`);
+    seen.add(r.fingerprint);
+    if (!nonEmptyString(r.title)) push(`${at}: needs a title`);
+    if (!CLASS_BY_ID.has(r.attack_class)) push(`${at}: unknown attack_class`);
+    if (!Array.isArray(r.coverage_ids)) push(`${at}: coverage_ids must be an array`);
+    if (r.verdict === 'confirmed') {
+      for (const k of ['description', 'root_cause', 'intended_behavior', 'attacker', 'impact']) if (!nonEmptyString(r[k])) push(`${at}: confirmed needs ${k}`);
+      validateTrace(r.trace, at, push, root);
+      const s = r.severity;
+      if (!s || !s.likelihood || !s.impact || !SCORES.includes(s.likelihood.score) || !SCORES.includes(s.impact.score) || !SCORES.includes(s.overall)) {
+        push(`${at}: confirmed needs severity with likelihood, impact, and overall scores`);
+      } else {
+        if (!nonEmptyString(s.likelihood.reason) || !nonEmptyString(s.impact.reason)) push(`${at}: severity scores need reasons`);
+        if (SCORE_RANK[s.overall] > SCORE_RANK[s.impact.score]) push(`${at}: overall severity cannot exceed impact`);
+      }
+      if (!r.remediation || !nonEmptyString(r.remediation.strategy)) push(`${at}: confirmed needs a remediation strategy`);
+      for (const c of r.conditions || []) if (!CONDITION_KINDS.includes(c && c.kind) || !nonEmptyString(c && c.description)) push(`${at}: bad condition`);
+      if (!Array.isArray(r.verified_by) || !r.verified_by.length) push(`${at}: confirmed needs an independent verifier`);
+      if (r.found_by && Array.isArray(r.verified_by) && r.verified_by.some((v) => v.agent_id === r.found_by.agent_id)) push(`${at}: the finder cannot verify its own finding`);
+    } else if (r.verdict === 'needs_validation') {
+      if (r.severity !== undefined) push(`${at}: needs_validation must not carry severity`);
+      if (!nonEmptyString(r.claimed_root_cause)) push(`${at}: needs_validation needs claimed_root_cause`);
+      validateTrace(r.trace, at, push, root);
+      if (!Array.isArray(r.blockers) || !r.blockers.length || !r.blockers.every(nonEmptyString)) push(`${at}: needs_validation needs exact blockers`);
+      if (!Array.isArray(r.validation_plan) || !r.validation_plan.length || !r.validation_plan.every((s) => s && ['local', 'deployment'].includes(s.context) && nonEmptyString(s.step))) push(`${at}: needs_validation needs a validation_plan of local or deployment steps`);
+    } else if (r.verdict === 'rejected') {
+      if (r.severity !== undefined) push(`${at}: rejected must not carry severity`);
+      if (!nonEmptyString(r.reason)) push(`${at}: rejected needs a reason`);
+    } else {
+      push(`${at}: verdict must be confirmed, needs_validation, or rejected`);
+    }
+  });
+  return errors;
+}
+
+// ---------------------------------------------------------------- engines
+
+function extractJson(text, accept = () => true) {
+  const src = String(text || '');
+  const found = [];
+  const fence = /```(?:json)?\s*\n([\s\S]*?)```/g;
+  let m;
+  while ((m = fence.exec(src))) {
+    try { const v = JSON.parse(m[1]); if (v && typeof v === 'object' && accept(v)) found.push(v); } catch {}
+  }
+  if (found.length) return found[found.length - 1];
+  const spans = [];
+  for (let start = src.indexOf('{'); start !== -1; start = src.indexOf('{', start + 1)) {
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < src.length; i++) {
+      const ch = src[i];
+      if (inStr) {
+        if (esc) esc = false;
+        else if (ch === '\\') esc = true;
+        else if (ch === '"') inStr = false;
+        continue;
+      }
+      if (ch === '"') inStr = true;
+      else if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          try {
+            const v = JSON.parse(src.slice(start, i + 1));
+            if (v && typeof v === 'object' && accept(v)) spans.push({ v, start, end: i });
+          } catch {}
+          break;
+        }
+      }
+    }
+  }
+  // The outermost accepted object wins; a nested match is part of it.
+  const outer = spans.filter((a) => !spans.some((b) => b !== a && b.start <= a.start && b.end >= a.end));
+  return outer.length ? outer[outer.length - 1].v : null;
+}
+
+async function defaultRunJobs(jobs, { root, concurrency, timeoutMs }) {
+  const { runEngineAskJobs, askRosterPin } = require('./engine-ask');
+  const pinned = jobs.map((job) => {
+    if (job.model) return job;
+    const pin = askRosterPin ? askRosterPin(job.engine, root) : {};
+    return { ...job, model: pin.roster_model || '', ...(pin.roster_effort ? { effort: pin.roster_effort } : {}) };
+  });
+  return runEngineAskJobs(pinned, { root, concurrency, timeoutMs });
+}
+
+function bullet(lines) {
+  return lines.map((l) => `- ${l}`).join('\n');
+}
+
+function unitBlock(u) {
+  const hot = (u.hot_lines || []).map((h) => `    ${h.file}:${h.line}  ${h.text}`).join('\n');
+  return [
+    `- coverage_id: ${u.coverage_id}`,
+    `  attack class: ${u.attack_class} (${CLASS_BY_ID.get(u.attack_class).title})`,
+    `  boundary: ${u.boundary}`,
+    `  subsystem: ${u.subsystem}`,
+    `  starting paths: ${u.starting_paths.join(', ')}`,
+    hot ? `  lines that seeded this unit (places to start, not findings):\n${hot}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+function hunterPrompt({ architecture, units, exclusions, peerIds }) {
+  const classes = [...new Set(units.map((u) => u.attack_class))].map((id) => CLASS_BY_ID.get(id));
+  const contract = {
+    units: [{ coverage_id: 'one assigned id', disposition: 'covered|candidate|blocked', reviewed_paths: ['repo/relative/path'], checks: [{ invariant: 'the control you checked', method: 'source', result: 'what the source established', reviewed_paths: ['repo/relative/path'] }], candidate_fingerprints: [], unresolved: [] }],
+    candidates: [{
+      proposed_verdict: 'confirmed|needs_validation', fingerprint: 'path:scope/root-cause-name', title: '', description: '', attack_class: classes[0].id,
+      coverage_ids: [], attacker: 'the lower-trust principal and what they start with', root_cause: '(confirmed) the source defect', claimed_root_cause: '(needs_validation) the suspected defect',
+      intended_behavior: '', impact: 'the concrete result across the boundary',
+      trace: [{ kind: 'entrypoint|propagation|sink', file: 'repo/relative/path', line: 1, description: '' }],
+      conditions: [{ kind: CONDITION_KINDS.join('|'), description: '' }],
+      severity: { likelihood: { score: SCORES.join('|'), reason: '' }, impact: { score: SCORES.join('|'), reason: '' }, overall: SCORES.join('|') },
+      remediation: { strategy: 'the smallest source change at the last trusted decision point', regression_test: 'the test that would fail today' },
+      blockers: ['(needs_validation) the exact missing fact'], validation_plan: [{ context: 'local|deployment', step: '' }],
+    }],
+    hardening: ['a concrete note that is not a finding'],
+    uncovered: [{ surface: 'repo/relative/path', attack_class: CLASSES.map((c) => c.id).join('|'), starting_paths: ['repo/relative/path'], reason: 'a different boundary you saw but do not own' }],
+  };
+  return [
+    'You are a security hunter on the Atris sentinel team. Find source-grounded security invariant failures in your assigned units, then return exactly one JSON object matching the contract at the end.',
+    '',
+    '## Architecture',
+    architecture.trim(),
+    '',
+    '## Your assigned units',
+    units.map(unitBlock).join('\n'),
+    '',
+    ...classes.flatMap((c) => [`## Attack class: ${c.title}`, bullet(c.guide), '']),
+    '## Method',
+    bullet(HUNT_METHOD),
+    '',
+    '## Candidate gate',
+    bullet(CANDIDATE_GATE),
+    '',
+    '## Severity anchors (confirmed only)',
+    bullet(SEVERITY_ANCHORS),
+    '',
+    exclusions.length ? `## Already on record, do not report again\n${bullet(exclusions.slice(0, 20).map((e) => `${e.fingerprint}: ${e.title} (${e.why})`))}\n` : '',
+    peerIds ? `Other hunters own ${peerIds} other units this wave. Stay inside your assigned paths; put anything else in "uncovered".\n` : '',
+    '## Result contract',
+    'Every assigned coverage_id appears exactly once in "units". "covered" means you read the paths and the invariant holds. "candidate" lists the fingerprints of the candidates you return. "blocked" means you read the code but one fact you cannot see decides it; say which in "unresolved". Every check lists the paths it read.',
+    'Return only this JSON object, no prose before or after it:',
+    JSON.stringify(contract, null, 2),
+  ].join('\n');
+}
+
+function withCode(root, trace) {
+  return (trace || []).map((t) => {
+    const text = t && isRepoRel(t.file) ? readText(root, t.file) : null;
+    const line = text && Number.isInteger(t.line) ? text.split('\n')[t.line - 1] : undefined;
+    return line === undefined ? t : { ...t, code: line.trim().slice(0, 200) };
+  });
+}
+
+function verifierPrompt({ candidate, cls }) {
+  const shown = { ...candidate };
+  delete shown.found_by;
+  const contract = {
+    verdict: 'confirmed|needs_validation|rejected',
+    reason: 'what you read and why it holds or fails',
+    preventing_layer: 'file:line of the control that stops it, or null',
+    corrected: { title: '', root_cause: '', attacker: '', impact: '', trace: [{ kind: 'entrypoint|propagation|sink', file: '', line: 1, description: '' }], conditions: [], severity: { likelihood: { score: '', reason: '' }, impact: { score: '', reason: '' }, overall: '' }, remediation: { strategy: '', regression_test: '' } },
+    blockers: ['(needs_validation) the exact missing fact'],
+    validation_plan: [{ context: 'local|deployment', step: '' }],
+  };
+  return [
+    'You are an independent security verifier on the Atris sentinel team. A different model proposed the candidate below. Your job is to try to disprove it, then return exactly one JSON object.',
+    '',
+    '## How to verify',
+    bullet([
+      'Open every cited file and line yourself. The "code" field shows what that line holds now; check the claim against the code, not against the description.',
+      'Look for the control that would stop it: an earlier check, a caller that never passes lower-trust input, a type or schema that rejects the value, a wrapper that escapes it.',
+      'Ask who controls the input. If it is the same person who runs the tool, it is self-impact, so reject it.',
+      '"confirmed": the full trace holds, the impact crosses the stated boundary, and nothing in source prevents it. Fix the severity if it is overstated; overall can never exceed impact.',
+      '"needs_validation": the trace holds in source, but a decisive fact is outside it. Name that fact exactly and give a safe check the owner can run.',
+      '"rejected": the source disproves it. Name the line that does.',
+      'Use "corrected" only for fields you would change. Read-only: do not run the target or touch the network.',
+    ]),
+    '',
+    `## Attack class: ${cls.title}`,
+    bullet(cls.guide),
+    '',
+    '## Severity anchors',
+    bullet(SEVERITY_ANCHORS),
+    '',
+    '## Candidate',
+    JSON.stringify(shown, null, 2),
+    '',
+    '## Result contract',
+    'Return only this JSON object:',
+    JSON.stringify(contract, null, 2),
+  ].join('\n');
+}
+
+function recheckPrompt({ record }) {
+  const shown = { ...record };
+  delete shown.found_by;
+  delete shown.verified_by;
+  return [
+    'You are the final record checker on the Atris sentinel team. Two other models already agreed this is a real security problem. Read the record against the source one last time and return exactly one JSON object.',
+    '',
+    bullet([
+      'Open each cited file:line. Every sentence in the record must match what the code does now.',
+      'Check the severity against the anchors. Overall can never exceed impact.',
+      'If the record is right, return {"ok": true}.',
+      'If a detail is wrong but the problem is real, return {"ok": false, "verdict": "confirmed", "corrected": {...only the fields to change}}.',
+      'If the problem is not real after all, return {"ok": false, "verdict": "rejected", "reason": "..."} or {"ok": false, "verdict": "needs_validation", "blockers": [...], "validation_plan": [{"context": "local|deployment", "step": "..."}]}.',
+    ]),
+    '',
+    '## Severity anchors',
+    bullet(SEVERITY_ANCHORS),
+    '',
+    '## Record',
+    JSON.stringify(shown, null, 2),
+  ].join('\n');
+}
+
+function criticPrompt({ architecture, units, final }) {
+  const rows = units.filter((u) => u.status !== 'out_of_scope').slice(0, 160).map((u) => `${u.status.padEnd(11)} ${u.attack_class.padEnd(22)} ${u.starting_paths.slice(0, 3).join(', ')}${u.unresolved.length ? `  (unresolved: ${u.unresolved[0].slice(0, 80)})` : ''}`);
+  return [
+    `You are the ${final ? 'final' : ''} coverage critic on the Atris sentinel team. You propose coverage, not findings. Read the architecture and ledger, look at the source, and name real gaps.`,
+    '',
+    '## Architecture',
+    architecture.trim(),
+    '',
+    `## Ledger (${units.length} units, first 160 shown)`,
+    rows.join('\n'),
+    '',
+    '## What to look for',
+    bullet([
+      'Entry points that take outside input and have no unit (servers, webhooks, cli args read from files, model output used as input).',
+      'Sibling paths that reach the same sink as a covered unit but were never assigned.',
+      'Units marked covered or blocked whose result looks thin for the class.',
+      'Do not propose test files or docs.',
+    ]),
+    '',
+    `Attack classes: ${CLASSES.map((c) => c.id).join(', ')}`,
+    '',
+    'Return only this JSON object:',
+    JSON.stringify({ missing_units: [{ surface: 'repo/relative/path', attack_class: 'one class id', starting_paths: ['repo/relative/path'], reason: 'the source fact that makes this a gap' }], reassign_ids: ['coverage_id of a unit whose result did not close it'], stop: false }, null, 2),
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------- hunters
+
+function cleanPaths(root, list) {
+  const out = [];
+  for (const raw of Array.isArray(list) ? list : []) {
+    const rel = normalizeRepoPath(root, raw);
+    if (rel && !out.includes(rel)) out.push(rel);
+  }
+  return out;
+}
+
+function archiveAttempt(u, reason) {
+  u.attempts.push({ wave: u.wave, status: u.status, agent_id: u.agent_id, reviewed_paths: u.reviewed_paths, local_checks: u.local_checks, result_fingerprints: u.result_fingerprints, unresolved: u.unresolved, reassignment_reason: reason });
+  u.wave += 1;
+  resetUnit(u, 'planned');
+}
+
+function resetUnit(u, status, reason = null) {
+  u.status = status;
+  u.agent_id = null;
+  u.reviewed_paths = [];
+  u.local_checks = [];
+  u.result_fingerprints = [];
+  u.unresolved = reason ? [reason] : [];
+}
+
+// Map one hunter answer onto its units. A malformed unit result leaves the
+// unit planned; the run defers it with the reason instead of pretending.
+function applyHunterResult(root, units, answer, agentId, engine) {
+  const parsed = answer && answer.ok !== false ? extractJson(answer.stdout, (v) => Array.isArray(v.units)) : null;
+  const failures = [];
+  const candidates = [];
+  const uncovered = [];
+  if (!parsed) {
+    const why = answer && answer.ok === false ? `hunter ${engine} failed: ${String(answer.reason || answer.stderr || 'no answer').slice(0, 120)}` : 'hunter returned no parseable result';
+    for (const u of units) { resetUnit(u, 'planned'); u.last_failure = why; }
+    return { candidates, uncovered, failures: units.map((u) => u.coverage_id), why };
+  }
+  const byId = new Map((parsed.units || []).filter((r) => r && r.coverage_id).map((r) => [r.coverage_id, r]));
+  const rawCandidates = (Array.isArray(parsed.candidates) ? parsed.candidates : []).filter((c) => c && FINGERPRINT_RE.test(String(c.fingerprint || '')));
+  const fpSet = new Set(rawCandidates.map((c) => c.fingerprint));
+  for (const u of units) {
+    const r = byId.get(u.coverage_id);
+    if (!r) { resetUnit(u, 'planned'); u.last_failure = 'hunter skipped this unit'; failures.push(u.coverage_id); continue; }
+    const checks = (Array.isArray(r.checks) ? r.checks : []).filter((c) => c && nonEmptyString(c.invariant) && nonEmptyString(c.result));
+    let reviewed = cleanPaths(root, r.reviewed_paths);
+    const normChecks = checks.map((c) => {
+      const paths = cleanPaths(root, c.reviewed_paths);
+      return { agent_id: agentId, reviewed_paths: paths.length ? paths : reviewed, invariant: String(c.invariant).slice(0, 400), method: 'source', result: String(c.result).slice(0, 800), artifact: null, engine };
+    }).filter((c) => c.reviewed_paths.length);
+    reviewed = [...new Set(normChecks.flatMap((c) => c.reviewed_paths))];
+    if (!reviewed.length || !normChecks.length) { resetUnit(u, 'planned'); u.last_failure = 'hunter result had no reviewed paths or checks'; failures.push(u.coverage_id); continue; }
+    const fps = (Array.isArray(r.candidate_fingerprints) ? r.candidate_fingerprints : []).filter((fp) => fpSet.has(fp));
+    const unresolved = (Array.isArray(r.unresolved) ? r.unresolved : []).filter(nonEmptyString).map((s) => s.slice(0, 300));
+    u.agent_id = agentId;
+    u.reviewed_paths = reviewed;
+    u.local_checks = normChecks;
+    if (r.disposition === 'candidate' && fps.length) {
+      u.status = 'candidate'; u.result_fingerprints = fps; u.unresolved = unresolved;
+    } else if (r.disposition === 'blocked' && unresolved.length) {
+      u.status = 'blocked'; u.result_fingerprints = []; u.unresolved = unresolved;
+    } else {
+      u.status = 'covered'; u.result_fingerprints = []; u.unresolved = [];
+    }
+    u.hardening = (Array.isArray(parsed.hardening) ? parsed.hardening : []).filter(nonEmptyString).slice(0, 5).map((s) => s.slice(0, 300));
+    delete u.last_failure;
+  }
+  const owned = new Set(units.map((u) => u.coverage_id));
+  for (const c of rawCandidates) {
+    const ids = (Array.isArray(c.coverage_ids) ? c.coverage_ids : []).filter((id) => owned.has(id));
+    const linked = units.filter((u) => u.result_fingerprints.includes(c.fingerprint)).map((u) => u.coverage_id);
+    candidates.push({ ...c, coverage_ids: [...new Set([...ids, ...linked])], found_by: { engine, agent_id: agentId } });
+  }
+  for (const x of Array.isArray(parsed.uncovered) ? parsed.uncovered : []) if (x) uncovered.push(x);
+  return { candidates, uncovered, failures };
+}
+
+// A proposed unit from a critic or a hunter's "uncovered" list becomes a real
+// ledger unit only if its class exists and its paths are real, in scope files.
+function proposedUnit(root, raw, { profile, scope }) {
+  const cls = CLASS_BY_ID.get(raw && raw.attack_class);
+  if (!cls) return null;
+  const paths = cleanPaths(root, [...(raw.starting_paths || []), raw.surface]).filter((p) => readText(root, p) !== null && !TEST_PATH.test(p) && inScope(p, scope));
+  if (!paths.length) return null;
+  const rel = paths[0];
+  const sub = subsystemOf(rel);
+  const quick = profile === 'quick';
+  const surface = quick ? `${sub}/*` : rel;
+  const refs = { surface, boundary: `classes#${cls.id}/boundary`, subsystem: quick ? 'profile/quick/all-in-scope-subsystems' : sub, attack_class: `classes#${cls.id}` };
+  const text = readText(root, rel) || '';
+  const hits = detectHits(text, cls);
+  const unit = newUnit({ refs, surface, boundary: cls.boundary, subsystem: sub, attackClass: cls.id, paths: quick ? paths.slice(0, MAX_QUICK_PATHS) : [rel], hot: hits.slice(0, MAX_HOT_LINES).map((h) => ({ file: rel, ...h })), priority: classPriority(cls, rel, hits.length) + 25, digest: sourceDigest(root, quick ? paths.slice(0, MAX_QUICK_PATHS) : [rel]) });
+  unit.prior_status = 'new';
+  unit.proposed_because = String(raw.reason || '').slice(0, 300);
+  return unit;
+}
+
+function addUnits(ledger, fresh) {
+  const ids = new Set(ledger.map((u) => u.coverage_id));
+  let added = 0;
+  for (const u of fresh) {
+    if (!u || ids.has(u.coverage_id)) continue;
+    ids.add(u.coverage_id);
+    ledger.push(u);
+    added += 1;
+  }
+  ledger.sort(cmpId);
+  return added;
+}
+
+// ---------------------------------------------------------------- verdicts
+
+function citationErrors(root, candidate) {
+  const errors = [];
+  const trace = Array.isArray(candidate.trace) ? candidate.trace : [];
+  if (!trace.length) errors.push('no trace');
+  for (const t of trace) {
+    const rel = normalizeRepoPath(root, t && t.file);
+    if (!rel) { errors.push(`unusable path ${t && t.file}`); continue; }
+    t.file = rel;
+    const line = Number(t.line);
+    t.line = line;
+    const text = readText(root, rel);
+    if (text === null) errors.push(`${rel} does not exist`);
+    else if (!Number.isInteger(line) || line < 1 || line > text.split('\n').length) errors.push(`${rel}:${t.line} is past the end of the file`);
+  }
+  return errors;
+}
+
+function fixTraceKinds(trace) {
+  if (!Array.isArray(trace) || trace.length < 2) return trace;
+  return trace.map((t, i) => ({ ...t, kind: i === 0 ? 'entrypoint' : i === trace.length - 1 ? 'sink' : 'propagation' }));
+}
+
+function clampSeverity(sev) {
+  if (!sev || !sev.impact || !SCORES.includes(sev.impact.score) || !SCORES.includes(sev.overall)) return sev;
+  if (SCORE_RANK[sev.overall] > SCORE_RANK[sev.impact.score]) return { ...sev, overall: sev.impact.score };
+  return sev;
+}
+
+function str(v, max = 2000) {
+  return typeof v === 'string' ? v.trim().slice(0, max) : '';
+}
+
+function buildRecord(root, cand, verdict, extra) {
+  const base = {
+    fingerprint: cand.fingerprint,
+    title: str(cand.title, 200) || cand.fingerprint,
+    attack_class: CLASS_BY_ID.has(cand.attack_class) ? cand.attack_class : (cand._unit_class || 'command-injection'),
+    coverage_ids: cand.coverage_ids || [],
+    found_by: cand.found_by,
+  };
+  if (verdict === 'rejected') return { verdict, ...base, reason: str(extra.reason) || 'disproved by the verifier', rejected_by: extra.by };
+  const trace = withCode(root, fixTraceKinds(cand.trace));
+  if (verdict === 'needs_validation') {
+    const blockers = (extra.blockers || cand.blockers || []).filter(nonEmptyString).map((b) => str(b, 400));
+    const plan = (extra.validation_plan || cand.validation_plan || []).filter((s) => s && ['local', 'deployment'].includes(s.context) && nonEmptyString(s.step)).map((s) => ({ context: s.context, step: str(s.step, 400) }));
+    return {
+      verdict, ...base,
+      description: str(cand.description),
+      claimed_root_cause: str(cand.claimed_root_cause) || str(cand.root_cause) || str(cand.description),
+      trace,
+      blockers: blockers.length ? blockers : [str(extra.reason, 400) || 'a fact outside source decides this'],
+      validation_plan: plan.length ? plan : [{ context: 'deployment', step: 'confirm the missing fact named in the blocker with the owner of that system' }],
+      verified_by: extra.by ? [extra.by] : [],
+    };
+  }
+  return {
+    verdict, ...base,
+    description: str(cand.description),
+    root_cause: str(cand.root_cause) || str(cand.claimed_root_cause),
+    intended_behavior: str(cand.intended_behavior),
+    attacker: str(cand.attacker),
+    impact: str(cand.impact),
+    trace,
+    conditions: (cand.conditions || []).filter((c) => c && CONDITION_KINDS.includes(c.kind) && nonEmptyString(c.description)).map((c) => ({ kind: c.kind, description: str(c.description, 400) })),
+    severity: clampSeverity(cand.severity),
+    remediation: { strategy: str(cand.remediation && cand.remediation.strategy), regression_test: str(cand.remediation && cand.remediation.regression_test) },
+    evidence_level: 'source-traced, not executed',
+    verified_by: extra.by ? [extra.by] : [],
+  };
+}
+
+function mergeCorrected(cand, corrected) {
+  if (!corrected || typeof corrected !== 'object') return cand;
+  const out = { ...cand };
+  for (const k of ['title', 'root_cause', 'attacker', 'impact', 'description', 'intended_behavior']) if (nonEmptyString(corrected[k])) out[k] = corrected[k];
+  if (Array.isArray(corrected.trace) && corrected.trace.length && corrected.trace.every((t) => t && t.file && t.line)) out.trace = corrected.trace;
+  if (Array.isArray(corrected.conditions) && corrected.conditions.length) out.conditions = corrected.conditions;
+  const s = corrected.severity;
+  if (s && s.impact && SCORES.includes(s.impact.score) && SCORES.includes(s.overall) && s.likelihood && SCORES.includes(s.likelihood.score)) out.severity = s;
+  if (corrected.remediation && nonEmptyString(corrected.remediation.strategy)) out.remediation = corrected.remediation;
+  return out;
+}
+
+// Turn a verifier answer into a final record. Anything unparseable keeps the
+// candidate out of findings; a confirmed verdict with a broken record falls
+// back to needs_validation rather than shipping a record that fails the
+// contract.
+function decide(root, cand, answer, by) {
+  const parsed = answer && answer.ok !== false ? extractJson(answer.stdout, (v) => typeof v.verdict === 'string') : null;
+  if (!parsed || !['confirmed', 'needs_validation', 'rejected'].includes(parsed.verdict)) return null;
+  const merged = mergeCorrected(cand, parsed.corrected);
+  if (parsed.verdict === 'rejected') return buildRecord(root, merged, 'rejected', { reason: parsed.preventing_layer ? `${str(parsed.reason, 600)} (stopped at ${str(parsed.preventing_layer, 200)})` : parsed.reason, by });
+  if (citationErrors(root, merged).length) return buildRecord(root, cand, 'rejected', { reason: `verifier cited source that does not resolve: ${citationErrors(root, merged).join('; ')}`, by });
+  if (parsed.verdict === 'needs_validation') return buildRecord(root, merged, 'needs_validation', { blockers: parsed.blockers, validation_plan: parsed.validation_plan, reason: parsed.reason, by });
+  const rec = buildRecord(root, merged, 'confirmed', { by: { ...by, reason: str(parsed.reason, 600) } });
+  const errs = validateFindings([rec], { root });
+  if (errs.length) {
+    return buildRecord(root, merged, 'needs_validation', { blockers: [`the confirmed record was incomplete: ${errs.slice(0, 3).join('; ')}`], validation_plan: [{ context: 'local', step: str(merged.remediation && merged.remediation.regression_test, 400) || 'write the regression test the record describes and see it fail' }], by });
+  }
+  return rec;
+}
+
+// ---------------------------------------------------------------- reports
+
+function sevCounts(records) {
+  const c = { critical: 0, high: 0, medium: 0, low: 0, informational: 0 };
+  for (const r of records) if (r.verdict === 'confirmed' && r.severity) c[r.severity.overall] = (c[r.severity.overall] || 0) + 1;
+  return c;
+}
+
+function coverageCounts(ledger) {
+  const c = {};
+  for (const u of ledger) c[u.status] = (c[u.status] || 0) + 1;
+  const inScope = ledger.filter((u) => u.status !== 'out_of_scope').length;
+  const done = (c.covered || 0) + (c.candidate || 0);
+  const carried = ledger.filter((u) => u.carried_from).length;
+  return { ...c, in_scope: inScope, done, carried, fresh: done - carried };
+}
+
+function plural(n, one, many = `${one}s`) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+function renderReports(dir, { meta, ledger, records, carriedPending }) {
+  const confirmed = records.filter((r) => r.verdict === 'confirmed').sort((a, b) => SCORE_RANK[b.severity.overall] - SCORE_RANK[a.severity.overall] || a.fingerprint.localeCompare(b.fingerprint));
+  const needs = records.filter((r) => r.verdict === 'needs_validation');
+  const rejected = records.filter((r) => r.verdict === 'rejected');
+  const cov = coverageCounts(ledger);
+  const sev = sevCounts(records);
+  const hardening = [...new Set(ledger.flatMap((u) => u.hardening || []))].slice(0, 20);
+  const report = [
+    `# Security audit: ${meta.repo}`,
+    '',
+    meta.run_status === 'incomplete' ? `This run is incomplete: ${meta.incomplete_reason.replace(/_/g, ' ')}.${carriedPending.length ? ` These records were not re-checked: ${carriedPending.join(', ')}.` : ''}` : '',
+    '',
+    `${plural(confirmed.length, 'confirmed problem')}${confirmed.length ? ` (${SCORES.slice().reverse().filter((s) => sev[s]).map((s) => `${sev[s]} ${s}`).join(', ')})` : ''}. ${plural(needs.length, 'lead needs', 'leads need')} a fact only the owner can check. ${rejected.length} disproved.`,
+    '',
+    `Covered ${cov.done} of ${cov.in_scope} areas (${cov.fresh} read this run, ${cov.carried} carried from an unchanged earlier run). ${cov.deferred || 0} wait for the next run.${meta.coverage_clean ? ' The final coverage critic found no gaps.' : ''}`,
+    '',
+    `Found by ${meta.engines.hunter}, checked by ${meta.engines.verifier}${meta.engines.hunter === meta.engines.verifier ? ' (same engine, fresh process; pick a different verifier for full independence)' : ', a different model'}. Every record was read from source, not executed.`,
+    '',
+    '## Confirmed',
+    '',
+    confirmed.length ? confirmed.map((r) => `- ${r.severity.overall}: ${r.title} (${r.trace[r.trace.length - 1].file}:${r.trace[r.trace.length - 1].line}). Fix: ${r.remediation.strategy}`).join('\n') : 'none',
+    '',
+    '## Needs validation',
+    '',
+    needs.length ? needs.map((r) => `- ${r.title}. Blocked on: ${r.blockers[0]}`).join('\n') : 'none',
+    '',
+    '## Could not settle',
+    '',
+    ledger.filter((u) => u.status === 'blocked').length ? ledger.filter((u) => u.status === 'blocked').map((u) => `- ${u.attack_class} in ${u.starting_paths.join(', ')}: ${u.unresolved[0]}`).join('\n') : 'none',
+    '',
+    '## Hardening notes (not findings)',
+    '',
+    hardening.length ? hardening.map((h) => `- ${h}`).join('\n') : 'none',
+    '',
+    '## Coverage',
+    '',
+    `- profile: ${meta.profile}${meta.scope_paths.length ? `, scoped to ${meta.scope_paths.join(', ')}` : ''}`,
+    `- units: ${Object.entries(cov).filter(([k]) => STATUSES.includes(k)).map(([k, v]) => `${k} ${v}`).join(', ')}`,
+    `- engine calls: ${meta.invocations.used} of ${meta.budget}`,
+    `- source: ${meta.source_ref.commit || 'not a git repo'}${meta.source_ref.dirty ? ' (uncommitted changes present)' : ''}`,
+    `- prior run: ${meta.prior_run || 'none'}`,
+    '',
+    'One run never covers everything. Run again to continue: unchanged covered areas are skipped and the budget goes to what is left.',
+    '',
+  ].filter((l, i, arr) => !(l === '' && arr[i - 1] === '')).join('\n');
+
+  const detail = ['# Findings detail', ''];
+  for (const r of confirmed) {
+    detail.push(`## ${r.title}`, '', `- severity: ${r.severity.overall} (likelihood ${r.severity.likelihood.score}: ${r.severity.likelihood.reason}; impact ${r.severity.impact.score}: ${r.severity.impact.reason})`, `- fingerprint: ${r.fingerprint}`, `- class: ${r.attack_class}`, `- who can do it: ${r.attacker}`, `- what happens: ${r.impact}`, `- root cause: ${r.root_cause}`, `- should instead: ${r.intended_behavior}`, `- found by: ${r.found_by ? `${r.found_by.engine} (${r.found_by.agent_id})` : 'carried'}; checked by: ${r.verified_by.map((v) => `${v.engine} (${v.agent_id})`).join(', ')}`, '', 'Trace:', '');
+    for (const t of r.trace) detail.push(`- ${t.kind} ${t.file}:${t.line}: ${t.description}${t.code ? `\n  \`${t.code.replace(/`/g, "'")}\`` : ''}`);
+    if (r.conditions.length) detail.push('', 'Conditions:', '', ...r.conditions.map((c) => `- ${c.kind}: ${c.description}`));
+    detail.push('', `Fix: ${r.remediation.strategy}`, r.remediation.regression_test ? `Regression test: ${r.remediation.regression_test}` : '', '');
+  }
+  if (!confirmed.length) detail.push('No confirmed findings this run.', '');
+
+  const nv = ['# Needs validation', '', 'Each lead below holds in source, but one fact outside the code decides it. None has a severity.', ''];
+  for (const r of needs) {
+    nv.push(`## ${r.title}`, '', `- fingerprint: ${r.fingerprint}`, `- suspected root cause: ${r.claimed_root_cause}`, '', 'Blocked on:', '', ...r.blockers.map((b) => `- ${b}`), '', 'How to check safely:', '', ...r.validation_plan.map((s) => `- ${s.context}: ${s.step}`), '', 'Trace:', '', ...r.trace.map((t) => `- ${t.kind} ${t.file}:${t.line}: ${t.description}`), '');
+  }
+  if (!needs.length) nv.push('Nothing waiting on an outside fact.', '');
+
+  fs.writeFileSync(path.join(dir, 'REPORT.md'), report);
+  fs.writeFileSync(path.join(dir, 'FINDINGS-DETAIL.md'), `${detail.filter((l) => l !== undefined).join('\n')}\n`);
+  fs.writeFileSync(path.join(dir, 'NEEDS-VALIDATION.md'), `${nv.join('\n')}\n`);
+}
+
+// ---------------------------------------------------------------- run
+
+// The nearest existing ancestor, realpath'd, plus the rest: symlinked
+// parents cannot hide that a folder is really inside the target.
+function realish(p) {
+  const rest = [];
+  let cur = path.resolve(p);
+  while (!fs.existsSync(cur) && path.dirname(cur) !== cur) { rest.unshift(path.basename(cur)); cur = path.dirname(cur); }
+  let real = cur;
+  try { real = fs.realpathSync(cur); } catch {}
+  return path.join(real, ...rest);
+}
+
+function resolveOutDir(root, { out, repo }) {
+  const rootReal = realRoot(root);
+  if (out) {
+    const abs = path.resolve(out);
+    const inside = containedIn(rootReal, realish(abs));
+    const rel = relPosix(path.relative(rootReal, realish(abs)));
+    if (inside) {
+      let ignored = false;
+      try { execFileSync('git', ['check-ignore', '-q', rel || '.'], { cwd: root, stdio: 'ignore' }); ignored = true; } catch {}
+      if (!ignored) throw new Error(`--out ${out} is inside the target and not ignored by git; pick a folder outside it`);
+    }
+    if (fs.existsSync(abs) && fs.readdirSync(abs).length) throw new Error(`--out ${out} already has files; pick a new folder`);
+    return { dir: abs, outRoot: path.dirname(abs) };
+  }
+  const outRoot = path.join(auditHome(), repo);
+  if (containedIn(rootReal, realish(outRoot))) throw new Error(`audit home ${outRoot} is inside the target; set ATRIS_SECURITY_AUDIT_HOME outside it`);
+  const next = (runDirs(outRoot).pop() || { num: 0 }).num + 1;
+  return { dir: path.join(outRoot, `run-${next}`), outRoot };
+}
+
+function budgetPlan(profile, total) {
+  const critics = profile === 'quick' ? 1 : 2;
+  const verifyReserve = Math.max(1, Math.ceil(0.3 * (total - critics)));
+  const hunters = total - critics - verifyReserve;
+  return { total, critics, verifyReserve, hunters };
+}
+
+function pickBatches(ledger, profile, allowance) {
+  const planned = ledger.filter((u) => u.status === 'planned' && !u.reserved_for).sort((a, b) => b.priority - a.priority || cmpId(a, b));
+  const size = UNITS_PER_HUNTER[profile];
+  const groups = new Map();
+  const order = [];
+  for (const u of planned) {
+    const key = `${u.attack_class}\0${u.subsystem}`;
+    if (!groups.has(key)) { groups.set(key, []); order.push(key); }
+    groups.get(key).push(u);
+  }
+  const batches = [];
+  // Round-robin across class x subsystem groups in priority order, so one
+  // noisy class cannot eat the whole budget.
+  while (batches.length < allowance) {
+    let took = false;
+    for (const key of order) {
+      if (batches.length >= allowance) break;
+      const g = groups.get(key);
+      if (!g.length) continue;
+      batches.push(g.splice(0, size));
+      took = true;
+    }
+    if (!took) break;
+  }
+  return batches;
+}
+
+async function runAudit(opts = {}) {
+  const root = path.resolve(opts.root || process.cwd());
+  const profile = PROFILES.includes(opts.profile) ? opts.profile : 'standard';
+  const scope = (opts.scope || []).map((s) => normalizeRepoPath(root, s)).filter(Boolean);
+  if ((opts.scope || []).length && !scope.length) throw new Error('scope paths must be inside the target');
+  const hunter = opts.hunter || 'codex';
+  const verifier = opts.verifier || 'claude';
+  const total = Number.isInteger(opts.budget) ? opts.budget : DEFAULT_BUDGET[profile];
+  const runJobs = opts.runJobs || defaultRunJobs;
+  const concurrency = opts.concurrency || 3;
+  const timeoutMs = opts.timeoutMs || 15 * 60 * 1000;
+  const log = opts.log || (() => {});
+  const now = opts.now || (() => new Date());
+  const repo = repoName(root);
+  const { dir, outRoot } = resolveOutDir(root, { out: opts.out, repo });
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Phase 1: map.
+  log(`mapping ${repo}`);
+  const mapped = mapTarget(root, { profile, scope });
+  const ledger = mapped.units;
+  const prior = loadPrior(outRoot, dir);
+  const { carried, exclusions } = mergePrior(ledger, prior);
+  let scanSeeds = [];
+  try {
+    const { runScan } = require('./security-scan');
+    scanSeeds = runScan({ root }).findings.filter((f) => f.sev === 'critical' || f.sev === 'high').filter((f) => inScope(f.file, scope));
+    for (const f of scanSeeds) for (const u of ledger) if (u.starting_paths.includes(f.file) && u.attack_class === 'secrets-handling') u.priority += 20;
+  } catch {}
+  const architecture = architectureText({ repo, root, stats: mapped.stats, units: ledger, scope, profile, prior: prior && { dir: prior.dir, units: prior.units, findings: prior.findingsCount }, scanSeeds });
+  const meta = {
+    run_id: path.basename(dir),
+    repo,
+    target: root,
+    source_ref: gitSourceRef(root),
+    profile,
+    scope_paths: scope,
+    budget: total,
+    execution_policy: 'source-only, read-only engines, no target execution, no network probes',
+    engines: { hunter, verifier, critic: verifier },
+    prior_run: prior ? prior.dir : null,
+    started_at: now().toISOString(),
+    run_status: 'in_progress',
+    invocations: { used: 0, hunters: 0, critics: 0, verifiers: 0, rechecks: 0 },
+    method: 'adapted from cloudflare/security-audit-skill (MIT)',
+  };
+  const ledgerFile = path.join(dir, 'coverage-ledger.json');
+  const saveLedger = () => {
+    ledger.sort(cmpId);
+    const errs = validateLedger(ledger);
+    if (errs.length) throw new Error(`coverage ledger failed validation: ${errs.slice(0, 5).join('; ')}`);
+    writeJson(ledgerFile, ledger);
+  };
+  fs.writeFileSync(path.join(dir, 'architecture.md'), architecture);
+  saveLedger();
+  writeJson(path.join(dir, 'run-metadata.json'), meta);
+
+  const plan = budgetPlan(profile, total);
+  const plannedCount = ledger.filter((u) => u.status === 'planned').length;
+  meta.plan = { ...plan, planned_units: plannedCount, units_per_hunter: UNITS_PER_HUNTER[profile], hunters_needed: Math.ceil(plannedCount / UNITS_PER_HUNTER[profile]) };
+
+  const pendingRecords = [];
+  const finish = (status, reason, records = [], carriedPending = []) => {
+    writeJson(path.join(dir, 'carried-pending.json'), pendingRecords);
+    meta.run_status = status;
+    if (reason) meta.incomplete_reason = reason;
+    meta.finished_at = now().toISOString();
+    meta.coverage = coverageCounts(ledger);
+    meta.counts = { confirmed: records.filter((r) => r.verdict === 'confirmed').length, needs_validation: records.filter((r) => r.verdict === 'needs_validation').length, rejected: records.filter((r) => r.verdict === 'rejected').length, severity: sevCounts(records) };
+    saveLedger();
+    writeJson(path.join(dir, 'findings.json'), records);
+    writeJson(path.join(dir, 'run-metadata.json'), meta);
+    renderReports(dir, { meta, ledger, records, carriedPending });
+    return { dir, meta, ledger, records };
+  };
+
+  const deferAll = (why) => {
+    for (const u of ledger) if (u.status === 'planned') { delete u.reserved_for; u.status = 'deferred'; u.unresolved = [why]; }
+    pendingRecords.push(...carried.map(stripCarried));
+  };
+  if (opts.planOnly) {
+    deferAll('plan only: no engines were called');
+    return finish('incomplete', 'plan_only', [], carried.map((r) => r.fingerprint));
+  }
+  if (plan.hunters < 1) {
+    deferAll('budget_cannot_fund_hunters_and_reserves');
+    return finish('incomplete', 'budget_cannot_fund_hunters_and_reserves', [], carried.map((r) => r.fingerprint));
+  }
+
+  const call = async (kind, jobs) => {
+    if (!jobs.length) return [];
+    meta.invocations.used += jobs.length;
+    meta.invocations[kind] += jobs.length;
+    writeJson(path.join(dir, 'run-metadata.json'), meta);
+    const answers = await runJobs(jobs, { root, concurrency, timeoutMs });
+    return answers;
+  };
+
+  // Phase 2 and 3: hunting waves, each followed by a coverage critic.
+  const candidates = new Map();
+  let huntLeft = plan.hunters;
+  let criticsLeft = plan.critics;
+  let coverageClean = false;
+  const failures = [];
+  const runCritic = async (wave, final) => {
+    criticsLeft -= 1;
+    const [answer] = await call('critics', [{ engine: verifier, prompt: criticPrompt({ architecture, units: ledger, final }), label: `sentinel critic ${final ? 'final' : `w${wave}`}` }]);
+    const parsed = answer && answer.ok !== false ? extractJson(answer.stdout, (v) => Array.isArray(v.missing_units) || Array.isArray(v.reassign_ids)) : null;
+    if (!parsed) return { accepted: 0, failed: true };
+    const fresh = (parsed.missing_units || []).map((raw) => proposedUnit(root, raw, { profile, scope })).filter(Boolean);
+    let accepted = addUnits(ledger, fresh);
+    for (const id of parsed.reassign_ids || []) {
+      const u = ledger.find((x) => x.coverage_id === id);
+      if (u && ['covered', 'blocked'].includes(u.status) && !u.carried_from) { archiveAttempt(u, `critic: result did not close the unit (${final ? 'final' : `wave ${wave}`})`); accepted += 1; }
+    }
+    log(`critic ${final ? 'final' : `wave ${wave}`}: ${accepted} gap${accepted === 1 ? '' : 's'}`);
+    return { accepted, failed: false };
+  };
+
+  for (let wave = 1; wave <= MAX_WAVES[profile]; wave++) {
+    const batches = pickBatches(ledger, profile, huntLeft);
+    if (!batches.length) break;
+    huntLeft -= batches.length;
+    const waveUnits = batches.reduce((n, b) => n + b.length, 0);
+    const jobs = batches.map((units, i) => {
+      const agentId = `h${wave}-${String(i + 1).padStart(2, '0')}`;
+      for (const u of units) { u.status = 'in_progress'; u.agent_id = agentId; u.wave = wave; }
+      return { engine: hunter, prompt: hunterPrompt({ architecture, units, exclusions, peerIds: waveUnits - units.length }), label: `sentinel hunter ${agentId}`, _units: units, _agent: agentId };
+    });
+    saveLedger();
+    log(`wave ${wave}: ${jobs.length} hunter${jobs.length === 1 ? '' : 's'} on ${jobs.reduce((n, j) => n + j._units.length, 0)} areas (${hunter})`);
+    const answers = await call('hunters', jobs.map(({ engine, prompt, label }) => ({ engine, prompt, label })));
+    const uncovered = [];
+    answers.forEach((answer, i) => {
+      const res = applyHunterResult(root, jobs[i]._units, answer, jobs[i]._agent, hunter);
+      for (const c of res.candidates) {
+        if (candidates.has(c.fingerprint)) {
+          const prev = candidates.get(c.fingerprint);
+          prev.coverage_ids = [...new Set([...prev.coverage_ids, ...c.coverage_ids])];
+        } else {
+          c._unit_class = jobs[i]._units[0].attack_class;
+          candidates.set(c.fingerprint, c);
+        }
+      }
+      uncovered.push(...res.uncovered);
+      if (res.failures.length) failures.push(...res.failures.map((id) => ({ id, why: res.why || 'malformed unit result' })));
+    });
+    addUnits(ledger, uncovered.map((raw) => proposedUnit(root, raw, { profile, scope })).filter(Boolean));
+    saveLedger();
+    if (profile === 'quick') {
+      if (criticsLeft > 0) {
+        const before = new Set(ledger.map((u) => u.coverage_id));
+        await runCritic(wave, true);
+        for (const u of ledger) if (u.status === 'planned' && (!before.has(u.coverage_id) || u.attempts.length)) { u.status = 'deferred'; u.unresolved = ['quick_profile_final_critic']; }
+      }
+      break;
+    }
+    const lastWave = wave === MAX_WAVES[profile];
+    if (criticsLeft > 1 && !lastWave) {
+      const res = await runCritic(wave, false);
+      if (!res.failed && res.accepted === 0 && !ledger.some((u) => u.status === 'planned')) break;
+    }
+  }
+  if (profile !== 'quick' && criticsLeft > 0 && !ledger.some((u) => u.status === 'planned')) {
+    const res = await runCritic(MAX_WAVES[profile], true);
+    coverageClean = !res.failed && res.accepted === 0;
+  }
+  for (const u of ledger) {
+    if ((u.status === 'planned' && !u.reserved_for) || u.status === 'in_progress') {
+      const why = u.last_failure || (huntLeft <= 0 ? 'budget_cannot_reserve_critics_and_validation' : 'wave_limit_reached');
+      resetUnit(u, 'deferred', why);
+    }
+  }
+  saveLedger();
+
+  // Phase 4: verify every candidate with a different model, cheapest net first.
+  const queue = [...carried.map((r) => ({ ...r, _carried: true })), ...candidates.values()].sort((a, b) => a.fingerprint.localeCompare(b.fingerprint));
+  const records = [];
+  const pending = [];
+  const toVerify = [];
+  const seenFp = new Set();
+  for (const cand of queue) {
+    if (seenFp.has(cand.fingerprint)) continue;
+    seenFp.add(cand.fingerprint);
+    if (!cand.attack_class || !CLASS_BY_ID.has(cand.attack_class)) cand.attack_class = cand._unit_class || 'command-injection';
+    const errs = citationErrors(root, cand);
+    if (errs.length) {
+      records.push(buildRecord(root, cand, 'rejected', { reason: `cited source does not resolve: ${errs.slice(0, 3).join('; ')}`, by: { engine: 'atris', agent_id: 'citation-check' } }));
+      continue;
+    }
+    toVerify.push(cand);
+  }
+  const verifyBudget = Math.max(0, total - meta.invocations.used);
+  const verifyNow = toVerify.slice(0, verifyBudget);
+  const notVerified = toVerify.slice(verifyBudget);
+  log(`verifying ${verifyNow.length} candidate${verifyNow.length === 1 ? '' : 's'} with ${verifier}`);
+  const vJobs = verifyNow.map((cand, i) => ({ engine: verifier, prompt: verifierPrompt({ candidate: { ...cand, trace: withCode(root, cand.trace), _carried: undefined, _unit_class: undefined, carried_from: undefined, verified_by: undefined }, cls: CLASS_BY_ID.get(cand.attack_class) }), label: `sentinel verifier v-${String(i + 1).padStart(2, '0')}` }));
+  const vAnswers = await call('verifiers', vJobs);
+  vAnswers.forEach((answer, i) => {
+    const cand = verifyNow[i];
+    const by = { engine: verifier, agent_id: `v-${String(i + 1).padStart(2, '0')}` };
+    if (cand._carried && !cand.found_by) cand.found_by = { engine: 'carried', agent_id: 'prior-run' };
+    const rec = decide(root, cand, answer, by);
+    if (rec) records.push(rec);
+    else pending.push(cand.fingerprint);
+  });
+  for (const cand of notVerified) pending.push(cand.fingerprint);
+
+  // Phase 5: one more fresh read of each confirmed record (standard, deep).
+  if (profile !== 'quick') {
+    const confirmed = records.filter((r) => r.verdict === 'confirmed');
+    const room = Math.max(0, total - meta.invocations.used);
+    const checkNow = confirmed.slice(0, room);
+    const rJobs = checkNow.map((rec, i) => ({ engine: verifier, prompt: recheckPrompt({ record: rec }), label: `sentinel recheck r-${String(i + 1).padStart(2, '0')}` }));
+    const rAnswers = await call('rechecks', rJobs);
+    rAnswers.forEach((answer, i) => {
+      const rec = checkNow[i];
+      const by = { engine: verifier, agent_id: `r-${String(i + 1).padStart(2, '0')}` };
+      const parsed = answer && answer.ok !== false ? extractJson(answer.stdout, (v) => typeof v.ok === 'boolean') : null;
+      const idx = records.indexOf(rec);
+      if (!parsed) { rec.record_check = 'no answer'; pending.push(rec.fingerprint); records.splice(idx, 1); return; }
+      if (parsed.ok) { rec.verified_by.push({ ...by, reason: 'final record matches source' }); return; }
+      const back = { ...rec, claimed_root_cause: rec.root_cause };
+      const next = decide(root, back, { ok: true, stdout: JSON.stringify({ verdict: parsed.verdict || 'confirmed', reason: parsed.reason, corrected: parsed.corrected, blockers: parsed.blockers, validation_plan: parsed.validation_plan }) }, by);
+      if (next && next.verdict === 'confirmed') next.verified_by = [...rec.verified_by, by];
+      if (next) records.splice(idx, 1, next);
+    });
+    for (const rec of confirmed.slice(checkNow.length)) {
+      pending.push(rec.fingerprint);
+      records.splice(records.indexOf(rec), 1);
+    }
+  }
+
+  // Units held for a carried record: the verifier that re-checked it owns
+  // them now. Without a verdict they wait for the next run.
+  const verdictOf = new Map(records.map((r) => [r.fingerprint, r]));
+  for (const u of ledger) {
+    if (!u.reserved_for) continue;
+    const fps = u.reserved_for;
+    delete u.reserved_for;
+    const checked = [];
+    const missing = [];
+    for (const fp of fps) {
+      const rec = verdictOf.get(fp);
+      const by = rec && ((rec.verified_by && rec.verified_by[0]) || rec.rejected_by);
+      if (rec && by && validAgentId(by.agent_id)) checked.push({ fp, rec, by });
+      else missing.push(fp);
+    }
+    if (!checked.length) { resetUnit(u, 'deferred', `carried record not re-checked this run: ${missing.join(', ')}`); continue; }
+    const live = checked.filter((c) => c.rec.verdict !== 'rejected');
+    if (!live.length && missing.length) { resetUnit(u, 'deferred', `carried record not re-checked this run: ${missing.join(', ')}`); continue; }
+    const owner = (live[0] || checked[0]).by.agent_id;
+    u.agent_id = owner;
+    u.local_checks = checked.map(({ fp, rec, by }) => {
+      const paths = [...new Set([...(rec.trace || []).map((t) => t.file), ...u.starting_paths])].filter(isRepoRel);
+      return { agent_id: by.agent_id, reviewed_paths: paths, invariant: `re-check of carried record ${fp}`, method: 'source', result: `${rec.verdict}: ${str(by.reason || rec.reason || '', 600) || 'verdict recorded'}`, artifact: null, engine: by.engine };
+    });
+    u.reviewed_paths = [...new Set(u.local_checks.flatMap((c) => c.reviewed_paths))];
+    if (live.length) { u.status = 'candidate'; u.result_fingerprints = live.map((c) => c.fp); u.unresolved = missing.map((fp) => `not re-checked this run: ${fp}`); }
+    else { u.status = 'covered'; u.result_fingerprints = []; u.unresolved = []; }
+  }
+
+  // Ledger units whose candidate never got a verdict keep it as unresolved.
+  for (const u of ledger) {
+    if (u.status !== 'candidate') continue;
+    const open = u.result_fingerprints.filter((fp) => pending.includes(fp));
+    if (open.length) u.unresolved = [...new Set([...u.unresolved, ...open.map((fp) => `not validated this run: ${fp}`)])];
+  }
+  const byFp = new Map(queue.map((c) => [c.fingerprint, c]));
+  for (const fp of pending) if (byFp.has(fp)) pendingRecords.push(stripCarried(byFp.get(fp)));
+  records.sort((a, b) => a.fingerprint.localeCompare(b.fingerprint));
+  // Each record is checked on its own, so an error cap can never let a bad
+  // one through; then the whole set is checked once more.
+  const bad = records.filter((r) => validateFindings([r], { root }).length);
+  if (bad.length) {
+    meta.validator_errors = bad.slice(0, 20).map((r) => `${r.fingerprint}: ${validateFindings([r], { root })[0]}`);
+    const good = records.filter((r) => !bad.includes(r));
+    const setErrs = validateFindings(good, { root });
+    return finish('incomplete', 'findings_failed_validation', setErrs.length ? [] : good, pending);
+  }
+  meta.coverage_clean = coverageClean;
+  meta.failures = failures.slice(0, 50);
+  if (pending.length) return finish('incomplete', 'validation_budget_exhausted', records, pending);
+  return finish('complete', null, records, pending);
+}
+
+function stripCarried(c) {
+  const out = { ...c };
+  delete out._carried;
+  delete out.carried_from;
+  return out;
+}
+
+function latestRun(root) {
+  const outRoot = path.join(auditHome(), repoName(path.resolve(root)));
+  const last = runDirs(outRoot).pop();
+  if (!last) return null;
+  return { dir: last.dir, meta: readJson(path.join(last.dir, 'run-metadata.json')), records: readJson(path.join(last.dir, 'findings.json')) || [] };
+}
+
+function shouldFailAudit(records) {
+  return records.some((r) => r.verdict === 'confirmed' && r.severity && SEVERE.has(r.severity.overall));
+}
+
+module.exports = {
+  PROFILES,
+  DEFAULT_BUDGET,
+  encodeRef,
+  coverageId,
+  mapTarget,
+  mergePrior,
+  validateLedger,
+  validateFindings,
+  extractJson,
+  citationErrors,
+  decide,
+  runAudit,
+  latestRun,
+  shouldFailAudit,
+};