@clear-capabilities/agentic-security-scanner 0.132.0 → 0.134.0

package/src/llm-validator/providers.js

@@ -0,0 +1,227 @@
+// PRD Epic 3 — the model-neutral seam.
+//
+// The deterministic engine has never depended on a model. The only coupling was
+// here, in how an AI call is shaped: one hardcoded pair of request builders and
+// one `endpointConfig` that knew about exactly two presets. This module makes
+// the provider a parameter instead, so an OpenAI or Gemini shop — or a
+// regulated org that cannot send code to any vendor — is a configuration
+// change rather than a fork.
+//
+// WHAT A PROVIDER IS. Endpoint, auth header shape, request body, and how to
+// read text and token usage back out. Nothing else. Prompt construction,
+// redaction, response validation, the challenge/nonce cross-check and the cost
+// ceiling all stay upstream and apply identically to every provider — those are
+// the security properties, and they must not become per-vendor.
+//
+// PER-ROLE PINNING. The strong pipelines route cheap models at triage and
+// frontier models at synthesis. `resolveProvider({ role })` reads a per-role
+// override before the global one, so `AGENTIC_SECURITY_LLM_MODEL_VERIFY` can
+// point at something cheap while `..._FIX` points at something capable. Roles
+// are a closed set: an unknown role would silently fall back to the global
+// model, which is how a "cheap verify" quietly becomes an expensive one.
+//
+// GRACEFUL DEGRADATION IS THE DEFAULT. No provider configured means no AI
+// stages — the engine still returns its deterministic findings. That is the
+// existing behaviour and it is load-bearing: adding providers must not make the
+// scanner require one.
+//
+// THE LOCAL PATH KEEPS ITS GUARANTEE. `local` still routes through
+// `local-endpoint.js`, which enforces loopback on the host literal. A provider
+// abstraction must not become a way to smuggle a remote endpoint into the mode
+// whose entire promise is that nothing leaves the machine.
+
+import { localEndpointConfig } from './local-endpoint.js';
+
+// Roles the pipeline dispatches under. Closed set on purpose — see above.
+export const ROLES = Object.freeze([
+  'validate',   // the FP-suppression validator (the original caller)
+  'verify',     // adversarial verification (Epic 2) — cheap tier by default
+  'explain',    // human-facing explanation
+  'fix',        // patch synthesis
+  'poc',        // proof-of-concept synthesis (Epic 1)
+  'logic',      // cross-file business-logic reasoning (Epic 6)
+]);
+
+const ANTHROPIC_VERSION = '2023-06-01';
+
+// ── Request/response shapes, one per wire protocol ──────────────────────────
+//
+// Kept as data rather than subclasses: each is four small functions, and a flat
+// table makes it obvious what a new provider must supply.
+const SHAPES = {
+  anthropic: {
+    headers: () => ({ 'Content-Type': 'application/json', 'anthropic-version': ANTHROPIC_VERSION }),
+    auth: (h, key) => { if (key) h['x-api-key'] = key; },
+    body: (model, prompt, maxTokens) => ({ model, max_tokens: maxTokens, messages: [{ role: 'user', content: prompt }] }),
+    text: (j) => (Array.isArray(j?.content) ? j.content.filter(b => b?.type === 'text').map(b => b.text || '').join('') : ''),
+    usage: (j) => (j?.usage && Number.isFinite(j.usage.input_tokens)
+      ? { inputTokens: j.usage.input_tokens, outputTokens: j.usage.output_tokens || 0 } : null),
+  },
+  // OpenAI-compatible: also what most local servers speak, which is why the
+  // `local` provider reuses it rather than inventing a third shape.
+  openai: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    auth: (h, key) => { if (key) h.Authorization = `Bearer ${key}`; },
+    body: (model, prompt, maxTokens) => ({ model, max_tokens: maxTokens, messages: [{ role: 'user', content: prompt }] }),
+    text: (j) => j?.choices?.[0]?.message?.content || j?.choices?.[0]?.text || '',
+    usage: (j) => {
+      const u = j?.usage; if (!u) return null;
+      const inputTokens = u.prompt_tokens ?? u.input_tokens;
+      const outputTokens = u.completion_tokens ?? u.output_tokens ?? 0;
+      return Number.isFinite(inputTokens) ? { inputTokens, outputTokens } : null;
+    },
+  },
+  // The LEGACY generic shape: `{prompt, model}` with a permissive extractor.
+  // This is what BYO endpoints and local servers have always been sent, and
+  // existing deployments speak it. Assuming OpenAI-compatibility here would
+  // silently break every one of them, so the OpenAI shape is used ONLY when the
+  // operator explicitly asks for the openai preset.
+  generic: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    auth: (h, key) => { if (key) h.Authorization = `Bearer ${key}`; },
+    body: (model, prompt) => ({ prompt, model }),
+    text: (j) => (j && (j.response || j.text || j.content || j.output
+      || j.choices?.[0]?.message?.content || j.message?.content)) || '',
+    usage: (j) => {
+      const u = j?.usage; if (!u) return null;
+      const inputTokens = u.prompt_tokens ?? u.input_tokens;
+      const outputTokens = u.completion_tokens ?? u.output_tokens ?? 0;
+      return Number.isFinite(inputTokens) ? { inputTokens, outputTokens } : null;
+    },
+  },
+  gemini: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    // Gemini takes the key on the query string; the caller appends it, so the
+    // header set stays empty rather than carrying a bearer token that the API
+    // would ignore.
+    auth: () => {},
+    body: (model, prompt, maxTokens) => ({
+      contents: [{ role: 'user', parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens: maxTokens },
+    }),
+    text: (j) => (j?.candidates?.[0]?.content?.parts || []).map(p => p?.text || '').join(''),
+    usage: (j) => {
+      const u = j?.usageMetadata; if (!u) return null;
+      return Number.isFinite(u.promptTokenCount)
+        ? { inputTokens: u.promptTokenCount, outputTokens: u.candidatesTokenCount || 0 } : null;
+    },
+  },
+};
+
+const DEFAULT_MODEL = {
+  anthropic: 'claude-haiku-4-5',
+  openai: 'gpt-4o-mini',
+  gemini: 'gemini-2.0-flash',
+  local: 'local-model',
+};
+
+function _envKey(role, suffix) {
+  return `AGENTIC_SECURITY_LLM_${suffix}_${String(role).toUpperCase()}`;
+}
+
+/** Per-role override, falling back to the global setting. */
+function _forRole(env, role, suffix) {
+  if (role && ROLES.includes(role)) {
+    const v = env[_envKey(role, suffix)];
+    if (v) return v;
+  }
+  return env[`AGENTIC_SECURITY_LLM_${suffix}`];
+}
+
+/**
+ * Resolve the provider for a role.
+ *
+ * @returns {{ok:true, config:object} | {ok:false, reason:string|null}}
+ *   `ok:false` with `reason:null` means "no AI configured", which is the normal
+ *   default and NOT an error. A non-null reason means a configuration was
+ *   supplied and refused — those must be surfaced, not silently treated the
+ *   same as "off".
+ */
+export function resolveProvider({ role = 'validate', env = process.env } = {}) {
+  const explicit = (_forRole(env, role, 'PRESET') || '').toLowerCase();
+  const model = _forRole(env, role, 'MODEL');
+
+  // 1. Local — checked first because it is the only mode that makes a promise
+  //    about where data goes, and a stray endpoint must not override it.
+  if (explicit === 'local') {
+    const r = localEndpointConfig(env);
+    if (!r.ok) return { ok: false, reason: r.reason };
+    return {
+      ok: true,
+      config: {
+        provider: 'local', shape: SHAPES.generic, endpoint: r.config.endpoint,
+        apiKey: r.config.apiKey, model: model || r.config.model,
+        egress: 'loopback-only', role,
+      },
+    };
+  }
+
+  // 2. Explicit BYO endpoint — checked BEFORE the vendor presets because that
+  //    is the documented precedence: an operator who names an endpoint means
+  //    that endpoint, even with a preset also set. Reversing it would silently
+  //    redirect traffic to a vendor.
+  const byoEndpoint = _forRole(env, role, 'ENDPOINT');
+  if (byoEndpoint) {
+    return {
+      ok: true,
+      config: {
+        provider: 'byo', shape: SHAPES.generic, endpoint: byoEndpoint,
+        apiKey: _forRole(env, role, 'API_KEY') || null,
+        model: model || 'unknown', egress: 'remote', role,
+      },
+    };
+  }
+
+  // 3. Explicit vendor presets.
+  if (explicit === 'anthropic' || explicit === 'openai' || explicit === 'gemini') {
+    const apiKey = _forRole(env, role, 'API_KEY')
+      || (explicit === 'anthropic' ? env.ANTHROPIC_API_KEY
+        : explicit === 'openai' ? env.OPENAI_API_KEY
+          : env.GEMINI_API_KEY || env.GOOGLE_API_KEY);
+    // No key -> the tier is off, not broken. Same offline-degrading rule the
+    // anthropic preset has always had.
+    if (!apiKey) return { ok: false, reason: null };
+    const m = model || DEFAULT_MODEL[explicit];
+    const endpoint = (
+      explicit === 'anthropic' ? 'https://api.anthropic.com/v1/messages'
+        : explicit === 'openai' ? 'https://api.openai.com/v1/chat/completions'
+          : `https://generativelanguage.googleapis.com/v1beta/models/${m}:generateContent?key=${encodeURIComponent(apiKey)}`
+    );
+    return {
+      ok: true,
+      config: {
+        provider: explicit, shape: SHAPES[explicit], endpoint,
+        apiKey: explicit === 'gemini' ? null : apiKey, model: m, egress: 'remote', role,
+      },
+    };
+  }
+
+  // 4. Nothing configured — deterministic engine only.
+  return { ok: false, reason: null };
+}
+
+/** Build the HTTP call for a resolved provider. Pure. */
+export function buildProviderRequest(config, prompt, maxTokens) {
+  const headers = config.shape.headers();
+  config.shape.auth(headers, config.apiKey);
+  return {
+    headers,
+    body: config.shape.body(config.model, prompt, maxTokens),
+    extractText: config.shape.text,
+    extractUsage: config.shape.usage,
+  };
+}
+
+/** Which provider each role would use, for reporting. Never includes keys. */
+export function providerMatrix(env = process.env) {
+  const out = {};
+  for (const role of ROLES) {
+    const r = resolveProvider({ role, env });
+    out[role] = r.ok
+      ? { provider: r.config.provider, model: r.config.model, egress: r.config.egress }
+      : { provider: null, reason: r.reason || 'not configured' };
+  }
+  return out;
+}
+
+export const _internals = { SHAPES, DEFAULT_MODEL, _forRole };

package/src/posture/CLAUDE.md

@@ -98,6 +98,31 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 credibility, orthogonal to `confidence`/`exploitability`: whether the bug was
 *run*, not just reasoned about.
 
+**The five proof classes** (`poc-inprocess.js`), and what each observes:
+
+| Family | Evidence |
+|---|---|
+| `command-injection`, `code-injection` | the injected payload itself writes the marker |
+| `webhook-missing-signature-verification` | the handler is observed *accepting* an unsigned request |
+| `sql-injection` | the payload reaches a stubbed driver inside the **SQL text** rather than as a bound parameter |
+| `path-traversal` | a sentinel planted outside the served directory comes back out of the handler |
+
+The last two need no running application, which is the point: the SQL question
+("text or bound parameter?") is settled where the query crosses into the driver,
+and the traversal question is settled by what the handler hands back. A
+parameterised query and a `basename`-guarded read both reach `proof-failed` by
+**execution**, not by a source pattern.
+
+Classes deliberately absent, with reasons, are listed in the module header —
+IDOR (needs two identities and a populated store; a PoC built on invented state
+proves something about the invention), SSRF (the sandbox denies egress, so a
+failed fetch is confinement talking), XSS (a marker file cannot observe a DOM).
+
+`extraFiles` on a PoC carries support files that are **not** the vulnerable
+source (the SQL driver stub). `mergePocFiles` merges it under `requires`, which
+always wins — otherwise a template could replace the code it is supposed to
+exploit and prove a fact about itself.
+
 **The four tiers** (`PROOF_TIERS`, most-proven first):
 
 - `execution-proven` — a generated PoC ran inside the sandbox and the sandbox
@@ -236,6 +261,57 @@ State lives at `<scanRoot>/.agentic-security/scan-checkpoint.jsonl`; like every
 other module here, nothing throws — a failure to open, read or append degrades to
 "no checkpoint", i.e. a normal full scan.
 
+## The autonomous loop, the fleet, and the two things that judge them
+
+**`autopilot.js`** is the chain — scan → prove → validate → fix → **re-verify** —
+and nothing else. Every stage is injected, so the orchestration is testable
+without an engine or a model; `scripts/autopilot.mjs` is where the real stages
+get wired (a real scan, a real sandboxed exploit, a deterministic-then-model fix,
+and the real gate).
+
+The rule that makes it safe to automate: a fix is applied **only** if the PoC
+that proved the bug no longer fires **and** the test suite still passes. Anything
+else is `NEEDS_REVIEW` and is not written. A re-scan proves the *detector* went
+quiet; only re-running the exploit proves the hole is shut. Gates are ON by
+default — `apply` is an explicit opt-in — and the outcome set (`OUTCOMES`) is
+closed, because the report groups on it and an undeclared value would vanish
+from every count. `maxFindings` is reported as `capped`, never applied silently.
+
+The CLI refuses to start with no confinement backend (the gate's verdict
+requires executing something) and refuses a dirty git tree by default (the test
+leg writes the candidate patch to disk and restores it in a `finally`, so a
+clean tree is what makes a crash recoverable). A VERIFIED_FIXED reached with no
+test runner detected is counted and reported separately — the exploit stopped
+firing, but nothing checked the application still works.
+
+**`fleet.js`** rolls many repositories into one offline page. `renderFleetHtml`
+emits no scripts and no external references, and a repo that FAILED to scan
+always forces a non-zero exit: an unscanned repo is unknown, not clean.
+
+**`logic-claims.js` (PRD Epic 6)** is the business-logic tier's other half. The
+deterministic side already existed (`sast/logic.js`, `posture/business-logic.js`);
+what did not was any way to be *wrong* about a claim from the reviewing agent,
+which is prose and was the only tier nothing could disagree with. Three offline
+lenses can refute one: `citation` (the file exists and the line is inside it),
+`quotation` (the quoted snippet is at the cited line ±3), and `corroboration`
+(for kinds that assert something checkable — "this route has no authentication"
+against a handler that plainly authenticates). Verdicts go through
+`verification-separation.js`, so a lens can never vote on a claim it produced.
+Recall-preserving: a refuted claim is `quarantined`, never deleted, never
+severity-touched. Wired in `engine.js`, which reads
+`.agentic-security/logic-claims.json` from the scan root and lands the results
+on `scan.logicVulns` with a summary at `scan.logicClaims`.
+
+**`comparison.js` (PRD Epic 7.2)** scores this engine head-to-head against
+participants **the operator supplies** — the repository ships the harness and the
+answer key, never a participant, and a test asserts no tool name appears in
+either file. Two properties are the whole module: every rate is computed over the
+**intersection** of entries *all* participants completed (two tools scored over
+different subsets are not comparable, and the difference is invisible in the
+output), and an entry a participant could not run is **unscored**, never counted
+as a miss. Matching is CWE-only so nobody is scored on this engine's vocabulary.
+Driver: `scripts/comparison.mjs`, over the CVE-replay corpus.
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/accuracy-scorecard.js

@@ -263,17 +263,48 @@ export function renderScorecardMarkdown(m) {
   L.push('');
   L.push('## Precision-side signal: self-scan (measured this run)');
   L.push('');
-  L.push('The engine scanned this repository\'s own hand-reviewed source. These are');
-  L.push('absolute finding counts, not a rate — there is no labelled ground truth');
-  L.push('over this code, so no precision figure is derived from it. What it');
-  L.push('supports is a movement claim: any change in these counts between');
-  L.push('releases is a real change in what the engine reports on unchanged code.');
+  L.push('The engine scanned its own repository. These are absolute finding');
+  L.push('counts, not a rate — there is no labelled ground truth over this code,');
+  L.push('so no precision figure is derived from it. What it supports is a');
+  L.push('movement claim: any change in these counts between releases is a real');
+  L.push('change in what the engine reports on unchanged code.');
+  L.push('');
+  L.push('**The two halves are not the same kind of evidence, so they are not');
+  L.push('reported together.** `hooks/` and `scripts/` were reviewed by hand,');
+  L.push('finding by finding. `scanner/src` was not: it is the engine itself, at a');
+  L.push('scale no one has read line by line, and a scanner\'s own source contains');
+  L.push('sink patterns as DATA — rule tables, catalogs, remediation strings — so a');
+  L.push('large share of its findings are self-referential rather than defects.');
+  L.push('Treat it as a tripwire, never as a quality figure.');
+  L.push('');
+  // Split deliberately. Both halves used to sit under a single "hand-reviewed"
+  // sentence; when `scanner/src` was added to the gate its 594 findings
+  // inherited a review claim that was true of 48 findings and false of these.
+  // Widening a gate must not silently upgrade what its numbers assert.
+  const REVIEWED = new Set(['hooks', 'scripts']);
+  const entries = Object.entries(m.selfScan.targets);
+  const reviewed = entries.filter(([k]) => REVIEWED.has(k));
+  const unreviewed = entries.filter(([k]) => !REVIEWED.has(k));
+
+  L.push('### Hand-reviewed targets');
   L.push('');
   L.push('| Target | Findings |');
   L.push('| --- | --- |');
-  for (const [k, v] of Object.entries(m.selfScan.targets)) L.push(`| \`${k}\` | ${v.total} |`);
+  for (const [k, v] of reviewed) L.push(`| \`${k}\` | ${v.total} |`);
   L.push(`| \`polyglot\` fixture (expected 0) | ${m.selfScan.polyglot.total} |`);
   L.push('');
+  if (unreviewed.length) {
+    L.push('### Drift tripwire — NOT hand-reviewed, NOT a precision signal');
+    L.push('');
+    L.push('| Target | Findings |');
+    L.push('| --- | --- |');
+    for (const [k, v] of unreviewed) L.push(`| \`${k}\` | ${v.total} |`);
+    L.push('');
+    L.push('These counts exist so that a rule which starts firing somewhere new is');
+    L.push('visible per file. Nobody has adjudicated them, and quoting the total as');
+    L.push('a false-positive count would be wrong in both directions.');
+    L.push('');
+  }
   L.push('Per-file counts are in `docs/scorecard.json`.');
   L.push('');
   L.push('## Committed artifacts referenced (not re-run by this command)');

package/src/posture/autopilot.js

@@ -0,0 +1,225 @@
+// PRD Epic 4 — the autonomous loop.
+//
+// Every stage already existed as a separate command. What did not exist was the
+// chain: scan → prove → validate → fix → RE-VERIFY, with state between stages
+// and a gate before anything is written. This module is that chain and nothing
+// else — it owns no analysis, and each stage is injected, so the orchestration
+// can be tested without running an engine or calling a model.
+//
+// THE RULE THAT MAKES IT SAFE TO AUTOMATE: a fix is applied only if the PoC
+// that proved the bug no longer fires AND the test suite still passes. That is
+// `VERIFIED_FIXED`. Anything else is `NEEDS_REVIEW` and is NOT written. A loop
+// that applies patches on the strength of "the scanner stopped complaining"
+// automates the failure mode where a cosmetic edit silences a detector while
+// the vulnerability remains — the re-scan proves the DETECTOR went quiet, and
+// only re-running the exploit proves the hole is shut.
+//
+// GATES ARE ON BY DEFAULT. `apply` requires an explicit opt-in. Autonomy plus
+// write access is the combination that turns a bad patch into a bad commit, and
+// the default must be the one that cannot.
+//
+// RESUMABLE, AND HONEST ABOUT WHAT IT SKIPPED. Each stage records its outcome
+// per finding; a resumed run replays completed stages from state rather than
+// re-running them. A stage that was skipped is reported as skipped — never
+// folded into "nothing to do", which is how an interrupted run reads as a clean
+// one.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SCHEMA = 'agentic-security/autopilot@1';
+
+export const STAGES = Object.freeze(['scan', 'prove', 'validate', 'fix', 'reverify']);
+
+// Outcomes a finding can end a run in. Closed set: a new outcome must be
+// declared here, because the report groups on it and an unknown value would
+// silently vanish from every count.
+export const OUTCOMES = Object.freeze([
+  'VERIFIED_FIXED',   // patch applied (or ready): PoC no longer fires, tests pass
+  'NEEDS_REVIEW',     // a fix exists but did not re-verify — NOT applied
+  'NO_FIX',           // nothing was synthesised
+  'UNPROVEN',         // no PoC fired, so no fix was attempted at this tier
+]);
+
+export function loadAutopilotState(stateFile) {
+  try {
+    const j = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    if (j && j.schema === SCHEMA) return j;
+  } catch { /* absent -> clean */ }
+  return { schema: SCHEMA, stages: {}, findings: {} };
+}
+
+function _save(stateFile, state) {
+  if (!stateFile) return;
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+  } catch { /* state is an optimisation; losing it must not fail a run */ }
+}
+
+/**
+ * Run the loop.
+ *
+ * Every stage is injected. `apply` defaults to false: the loop produces
+ * VERIFIED_FIXED patches and does not write them unless told to.
+ *
+ * @param {object} stages
+ *   scan()                      -> { findings: [] }
+ *   prove(finding)              -> { proofTier, proofEvidence, poc }
+ *   validate(finding)           -> { verdict: 'upheld'|'refuted'|'undecided' }
+ *   synthesizeFix(finding)      -> { patch: {file: content} } | null
+ *   verifyFix(finding, patch)   -> { ok, pocStillFires, testsPass, reason }
+ *   applyFix(finding, patch)    -> void   (only called when apply === true)
+ */
+export async function runAutopilot({
+  stages = {}, stateFile = null, resume = true, apply = false,
+  onStage = () => {}, severities = ['critical', 'high'], maxFindings = Infinity,
+} = {}) {
+  const required = ['scan'];
+  for (const r of required) {
+    if (typeof stages[r] !== 'function') return { ok: false, reason: `no ${r} stage supplied` };
+  }
+  const state = resume && stateFile ? loadAutopilotState(stateFile) : { schema: SCHEMA, stages: {}, findings: {} };
+  const skipped = [];
+
+  // ── scan ────────────────────────────────────────────────────────────────
+  let findings;
+  if (resume && state.stages.scan) {
+    findings = state.stages.scan.findings || [];
+    skipped.push('scan');
+  } else {
+    const r = await stages.scan();
+    findings = r?.findings || [];
+    state.stages.scan = { findings };
+    _save(stateFile, state);
+  }
+  onStage({ stage: 'scan', count: findings.length });
+
+  // Only the severities asked for reach the expensive stages. Reported, so a
+  // reader can see what was in scope rather than assuming everything was.
+  const all = findings.filter(f => severities.includes(String(f.severity || '').toLowerCase()));
+  const outOfScope = findings.length - all.length;
+  // Every stage costs a sandboxed process and possibly a test-suite run, so the
+  // count is bounded. Reported, never silent: findings past the cap were NOT
+  // examined, and a run that quietly stopped at N would read as a run that
+  // found only N.
+  const inScope = all.slice(0, Number.isFinite(maxFindings) ? Math.max(0, maxFindings) : all.length);
+  const capped = all.length - inScope.length;
+
+  const results = [];
+  for (const f of inScope) {
+    const key = f.stableId || `${f.file}:${f.line}:${f.vuln}`;
+    const prior = resume ? state.findings[key] : null;
+    if (prior?.outcome) { results.push(prior); continue; }
+
+    const rec = { key, file: f.file, line: f.line, vuln: f.vuln, severity: f.severity };
+
+    // ── prove ─────────────────────────────────────────────────────────────
+    let proved = null;
+    if (typeof stages.prove === 'function') {
+      proved = await stages.prove(f).catch(e => ({ error: String(e?.message || e) }));
+      rec.proofTier = proved?.proofTier || null;
+    }
+    const isProven = rec.proofTier === 'execution-proven';
+
+    // ── validate ──────────────────────────────────────────────────────────
+    if (typeof stages.validate === 'function') {
+      const v = await stages.validate(f).catch(() => null);
+      rec.validation = v?.verdict || null;
+      // A refuted finding is NOT dropped — same recall-preserving rule the rest
+      // of the engine follows. It is recorded and skipped for fixing.
+      if (rec.validation === 'refuted') {
+        rec.outcome = 'NEEDS_REVIEW';
+        rec.reason = 'an independent verifier refuted this finding; not fixed automatically';
+        results.push(rec); state.findings[key] = rec; _save(stateFile, state);
+        onStage({ stage: 'validate', key, verdict: 'refuted' });
+        continue;
+      }
+    }
+
+    // Fixing is gated on proof at this tier. An unproven finding may still be
+    // real — it is reported UNPROVEN, not dismissed.
+    if (!isProven) {
+      rec.outcome = 'UNPROVEN';
+      rec.reason = proved?.proofEvidence?.reason || 'no proof-of-concept demonstrated this finding';
+      results.push(rec); state.findings[key] = rec; _save(stateFile, state);
+      continue;
+    }
+
+    // ── fix ───────────────────────────────────────────────────────────────
+    let patch = null;
+    if (typeof stages.synthesizeFix === 'function') {
+      patch = await stages.synthesizeFix(f).catch(() => null);
+    }
+    if (!patch || !patch.patch) {
+      rec.outcome = 'NO_FIX';
+      rec.reason = 'no patch was synthesised';
+      results.push(rec); state.findings[key] = rec; _save(stateFile, state);
+      continue;
+    }
+
+    // ── re-verify ─────────────────────────────────────────────────────────
+    // The gate. Without a verifier we cannot claim VERIFIED_FIXED, so we do
+    // not — an unverifiable patch is NEEDS_REVIEW even if it looks right.
+    if (typeof stages.verifyFix !== 'function') {
+      rec.outcome = 'NEEDS_REVIEW';
+      rec.reason = 'no verifyFix stage supplied — a patch that cannot be re-verified is never applied';
+      results.push(rec); state.findings[key] = rec; _save(stateFile, state);
+      continue;
+    }
+    const v = await stages.verifyFix(f, patch).catch(e => ({ ok: false, reason: String(e?.message || e) }));
+    rec.pocStillFires = v?.pocStillFires === true;
+    rec.testsPass = v?.testsPass !== false;
+
+    if (v?.ok && !rec.pocStillFires && rec.testsPass) {
+      rec.outcome = 'VERIFIED_FIXED';
+      if (apply && typeof stages.applyFix === 'function') {
+        try { await stages.applyFix(f, patch); rec.applied = true; }
+        catch (e) { rec.applied = false; rec.outcome = 'NEEDS_REVIEW'; rec.reason = `apply failed: ${e.message}`; }
+      } else {
+        rec.applied = false;
+        rec.reason = apply ? 'no applyFix stage supplied' : 'gates on: patch is ready but was not written';
+      }
+    } else {
+      rec.outcome = 'NEEDS_REVIEW';
+      rec.reason = rec.pocStillFires
+        ? 'the proof-of-concept still fires against the patch — the vulnerability is not fixed'
+        : (!rec.testsPass ? 'the project test suite fails with this patch'
+          : (v?.reason || 'the patch did not re-verify'));
+    }
+    results.push(rec);
+    state.findings[key] = rec;
+    _save(stateFile, state);
+    onStage({ stage: 'reverify', key, outcome: rec.outcome });
+  }
+
+  return { ok: true, results, skipped, outOfScope, capped, summary: summarizeAutopilot(results, outOfScope, capped) };
+}
+
+export function summarizeAutopilot(results, outOfScope = 0, capped = 0) {
+  const byOutcome = Object.fromEntries(OUTCOMES.map(o => [o, 0]));
+  for (const r of results) if (r.outcome in byOutcome) byOutcome[r.outcome]++;
+  return {
+    considered: results.length,
+    outOfScope,
+    capped,
+    byOutcome,
+    applied: results.filter(r => r.applied).length,
+  };
+}
+
+/** One line. Leads with what was NOT fixed, because that is the actionable part. */
+export function renderAutopilotSummary(s) {
+  if (!s) return null;
+  const b = s.byOutcome;
+  const bits = [`${s.considered} finding(s) in scope`];
+  if (b.VERIFIED_FIXED) bits.push(`${b.VERIFIED_FIXED} VERIFIED_FIXED (${s.applied} applied)`);
+  if (b.NEEDS_REVIEW) bits.push(`${b.NEEDS_REVIEW} NEEDS_REVIEW — not applied`);
+  if (b.NO_FIX) bits.push(`${b.NO_FIX} with no patch`);
+  if (b.UNPROVEN) bits.push(`${b.UNPROVEN} unproven (not dismissed — no PoC fired)`);
+  if (s.outOfScope) bits.push(`${s.outOfScope} below the severity floor and not considered`);
+  if (s.capped) bits.push(`${s.capped} in scope but NOT examined (per-run cap) — unexamined, not clean`);
+  return bits.join('; ') + '.';
+}
+
+export const _internals = { SCHEMA };