@clear-capabilities/agentic-security-scanner 0.172.1 → 0.174.0

package/src/fix/apply-fix-service.js

@@ -39,6 +39,10 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { verifyLastScan } from '../posture/integrity.js';
+import { verifyPatch, additiveFields } from './verify-patch.js';
+import { decidePatchApplication } from './patch-policy.js';
+import { beginBatch, commitBatch, abandonBatch, recoverBatches, faultPoint } from './batch-journal.js';
+import { spawnSync } from 'node:child_process';
 import { stateDir } from '../posture/state-dir.js';
 import { applyFix as applyFixHistory, revertEntryById as revertFixEntry } from '../posture/fix-history.js';
 import { classifyFixMaterialRisk } from '../posture/material-change.js';
@@ -209,7 +213,7 @@ async function getVerifyFixCore() {
  *   configured, tests when a runner is detected — genuinely ran and passed, not silently skipped.
  *   `verified:true, verifiedFull:false` is a real, honest state: applied, but on a degraded pass.
  */
-export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = null, dryRun = false, skipVerification = false, patchNegative = null, assuranceConfig } = {}) {
+export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = null, dryRun = false, skipVerification = false, patchNegative = null, assuranceConfig, applyMode = 'requested', policy } = {}) {
   if (!scanRoot) return { ok: false, applied: false, reason: 'scanRoot required' };
   if (!finding) return { ok: false, applied: false, reason: 'finding required' };
   if (!files || typeof files !== 'object' || !Object.keys(files).length) {
@@ -231,6 +235,9 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
     return { ok: false, applied: false, reason: `last-scan.json integrity check failed: ${integrityStatus}` };
   }
 
+  // A previous run that died part-way through a multi-file write is settled first, so everything below sees the tree it was in before that run.
+  const settledBatches = dryRun ? [] : await recoverBatches(scanRoot);
+
   const confined = {};
   for (const [rel, content] of Object.entries(files)) {
     let abs;
@@ -253,6 +260,12 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
     } catch (e) {
       return { ok: false, applied: false, reason: `could not read current content of ${rel} to detect concurrent changes: ${e.message}` };
     }
+    // Binary content cannot be patched as text: reading it as UTF-8 and writing it back would corrupt it.
+    if (String(content).includes('\0')) return { ok: false, applied: false, reason: `binary content refused: the replacement for ${rel} contains NUL bytes` };
+    if (fs.existsSync(abs)) {
+      const raw = fs.readFileSync(abs);
+      if (raw.includes(0) || Buffer.from(raw.toString('utf8'), 'utf8').compare(raw) !== 0) return { ok: false, applied: false, reason: `binary file refused: ${rel} is not valid UTF-8 text, so a text patch would corrupt it` };
+    }
     confined[rel] = { abs, content: String(content), baselineHash };
   }
 
@@ -323,6 +336,7 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
   }
 
   let verify = null;
+  let fixVerification = null;
   let pn = null;
   let repairRecords = [];
   const pnView = (r) => ({ status: r.status, verifiedFix: r.verifiedFix, incompleteStep: r.incompleteStep, failureCode: r.failureCode, reason: r.reason, steps: r.steps, patchDigest: r.patchDigest, summary: r.summary, verificationRecord: r.verificationRecord });
@@ -332,14 +346,14 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
     }
     let verdict;
     try {
-      const verifyFixCore = await getVerifyFixCore();
-      verdict = await verifyFixCore({
-        scanRoot,
-        originalFindingStableId: finding.stableId,
+      const central = await verifyPatch({
+        scanRoot, finding, route: 'apply-fix-service', mode: dryRun ? 'preview' : 'apply',
         files: Object.fromEntries(Object.entries(confined).map(([rel, v]) => [rel, v.content])),
-        fixMeta,
-        ...(patchNegative ? { patchNegative, assuranceConfig } : {}),
+        fixMeta, verify: await getVerifyFixCore(),
+        ...(patchNegative ? { extra: { patchNegative, assuranceConfig } } : {}),
       });
+      verdict = central.verdict;
+      fixVerification = central.fixVerification;
     } catch (e) {
       return { ok: false, applied: false, reason: `verification failed: ${e.message}` };
     }
@@ -357,12 +371,25 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
         reason: `rejected by verifier: ${verdict.summary || verdict.rescan?.reason || 'did not verify'}`,
         verify: { rescan: verdict.rescan, lint: verdict.lint ? { runner: verdict.lint.runner, ok: verdict.lint.ok } : null, honesty: verdict.honesty || null },
         ...(pn ? { patchNegative: pnView(pn), repairRecords } : {}),
+        ...(fixVerification ? additiveFields(fixVerification) : {}),
       };
     }
   }
 
+  // E3-06: may this be written? `requested` (a person asked) proceeds on any verified tier and carries the warnings; `automatic` needs the
+  // policy to enable it and every required check to have passed, otherwise the patch is only proposed.
+  const uncommitted = uncommittedFiles(scanRoot, Object.keys(confined));
+  let policyDecision = fixVerification ? decidePatchApplication({ record: fixVerification, finding, materialClassification, mode: applyMode, policy }) : null;
+  if (policyDecision && uncommitted.length) {
+    policyDecision = { ...policyDecision, warnings: [...policyDecision.warnings, `uncommitted changes in ${uncommitted.join(', ')}`] };
+    if (applyMode === 'automatic' && policyDecision.decision === 'apply') policyDecision = { ...policyDecision, decision: 'propose', reasons: [`uncommitted changes in ${uncommitted.join(', ')}: an automatic write would mix with unsaved work`] };
+  }
+  if (policyDecision && policyDecision.decision !== 'apply' && !dryRun) {
+    return { ok: true, applied: false, proposed: policyDecision.decision === 'propose', reason: `not applied: ${policyDecision.reasons[0]}`, files: Object.keys(confined), verify, materialClassification, policyDecision, ...additiveFields(fixVerification) };
+  }
+
   if (dryRun) {
-    return { ok: true, applied: false, dryRun: true, verified: !skipVerification, files: Object.keys(confined), verify, materialClassification, ...(pn ? { patchNegative: pnView(pn), repairRecords } : {}) };
+    return { ok: true, applied: false, dryRun: true, ...(policyDecision ? { policyDecision } : {}), verified: !skipVerification, files: Object.keys(confined), verify, materialClassification, ...(pn ? { patchNegative: pnView(pn), repairRecords } : {}), ...(fixVerification ? additiveFields(fixVerification) : {}) };
   }
 
   // FR-304: re-check every file against its pre-verification baseline hash,
@@ -375,8 +402,11 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
   }
 
   const written = [];
+  const batch = await beginBatch(scanRoot, { findingId: finding.id || finding.findingId, files: Object.entries(confined).map(([rel, v]) => ({ file: rel, content: v.content, existed: fs.existsSync(v.abs) })) });
   try {
+    let n = 0;
     for (const [rel, v] of Object.entries(confined)) {
+      faultPoint(`before-file-${n}`);
       const fileExisted = fs.existsSync(v.abs);
       const originalContent = fileExisted ? await fsp.readFile(v.abs, 'utf8') : '';
       const entry = await applyFixHistory({
@@ -388,7 +418,10 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
         findingProvenance: finding.findingProvenance || null,
       });
       written.push({ file: rel, historyId: entry.id, backupPath: entry.backupPath, attemptOrdinal: entry.attemptOrdinal });
+      faultPoint(`after-file-${n}`);
+      n++;
     }
+    await commitBatch(scanRoot, batch);
   } catch (e) {
     // FR-306: "injected write failure restores all files" — applyFixHistory
     // already rolled back the ONE file that just failed; this rolls back
@@ -400,6 +433,7 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
     for (const w of written) {
       try { await revertFixEntry(scanRoot, w.historyId); } catch { /* best-effort; original error still propagates below */ }
     }
+    await abandonBatch(scanRoot, batch).catch(() => {});
     // X-204: the rollback is its own record, after the promotion it undoes (a write that failed part-way)
     if (pn) {
       const rolled = appendRepairRecord(repairRecords, { kind: 'rolled-back', hypothesisId: finding.stableId, revision: pn.promotion?.revision ?? null, diffDigest: pn.patchDigest, reason: `the write failed and every file written in this batch was restored: ${String(e?.message || e).slice(0, 160)}` });
@@ -429,6 +463,19 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
     written,
     verify: verify ? { summary: verify.summary, verifiedFull: verify.verifiedFull, degradedLegs: verify.degradedLegs || [] } : null,
     materialClassification,
+    ...(policyDecision ? { policyDecision } : {}),
+    ...(settledBatches.length ? { recoveredBatches: settledBatches } : {}),
     ...(pn ? { patchNegative: pnView(pn), repairRecords } : {}),
+    // the canonical record is the authority for verifiedFull and degradedLegs: it also knows when the tests ran before the patch existed
+    ...(fixVerification ? additiveFields(fixVerification) : {}),
   };
 }
+
+/** Files among `rels` with uncommitted changes in a git work tree. [] when not a git repo or git is unavailable (unknown is not clean, but is not blocking). */
+function uncommittedFiles(scanRoot, rels) {
+  try {
+    const r = spawnSync('git', ['status', '--porcelain', '--', ...rels], { cwd: scanRoot, encoding: 'utf8', timeout: 8000 });
+    if (r.status !== 0 || !r.stdout) return [];
+    return r.stdout.split('\n').filter(Boolean).map((l) => l.slice(3).trim()).filter((f) => rels.includes(f));
+  } catch { return []; }
+}

package/src/fix/batch-journal.js

@@ -0,0 +1,84 @@
+// All-or-nothing multi-file application that survives a crash (E3-07).
+//
+// fix-history.js already makes ONE file's write crash-safe: backup, pending log entry, atomic rename, promote. A patch that touches
+// several files was only safe against an exception: if the process died after file A was promoted and before file B was written, A stayed
+// patched and B did not, with nothing that said so. This journal closes that gap. Before the first write the batch is recorded as
+// `writing`; after the last file is promoted it is `committed`. On the next run, `recoverBatches` finds any batch still `writing`, settles
+// the per-file history first, then reverts every file of the batch that reached its patched content, so the tree returns to what it was.
+//
+// A fault seam (`faultPoint`) lets a test kill the process at a named point. It does nothing unless BOTH environment variables are set,
+// so it cannot fire in normal use.
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { statePath } from '../posture/state-dir.js';
+import { readLog, recover, revertEntryById } from '../posture/fix-history.js';
+
+const dirOf = (root) => statePath(root, 'fix-batches');
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+export function faultPoint(name) {
+  if (process.env.AGENTIC_SECURITY_TEST_FAULTS !== '1') return;
+  if (process.env.AGENTIC_SECURITY_FAULT_AT === name) process.kill(process.pid, 'SIGKILL');
+}
+
+async function writeJson(file, value) {
+  await fsp.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(3).toString('hex')}`;
+  const h = await fsp.open(tmp, 'w');
+  try { await h.writeFile(JSON.stringify(value, null, 2)); await h.sync(); } finally { await h.close(); }
+  await fsp.rename(tmp, file);
+}
+
+export async function beginBatch(scanRoot, { files, findingId }) {
+  const id = `batch-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+  const batch = { id, state: 'writing', findingId: findingId ?? null, startedAt: new Date().toISOString(), files: files.map((f) => ({ file: f.file, newSha: sha(f.content), existed: f.existed })) };
+  await writeJson(path.join(dirOf(scanRoot), `${id}.json`), batch);
+  return batch;
+}
+
+export async function commitBatch(scanRoot, batch) {
+  await writeJson(path.join(dirOf(scanRoot), `${batch.id}.json`), { ...batch, state: 'committed', committedAt: new Date().toISOString() });
+}
+
+export async function abandonBatch(scanRoot, batch, state = 'rolled-back') {
+  await writeJson(path.join(dirOf(scanRoot), `${batch.id}.json`), { ...batch, state, settledAt: new Date().toISOString() });
+}
+
+const STRAY_TMP = /^\..+\.tmp-\d+-[0-9a-f]{8}$/;
+
+/**
+ * Settle every batch that was still `writing` when a previous run stopped. Safe to call at any time; a no-op when nothing is pending.
+ * @returns {Promise<{batch:string, reverted:string[], untouched:string[], failed:string[]}[]>}
+ */
+export async function recoverBatches(scanRoot) {
+  const dir = dirOf(scanRoot);
+  let names = [];
+  try { names = (await fsp.readdir(dir)).filter((n) => n.endsWith('.json')); } catch { return []; }
+  const out = [];
+  let settled = false;
+  for (const n of names.sort()) {
+    let batch; try { batch = JSON.parse(await fsp.readFile(path.join(dir, n), 'utf8')); } catch { continue; }
+    if (batch.state !== 'writing') continue;
+    if (!settled) { await recover(scanRoot); settled = true; }
+    const log = readLog(scanRoot);
+    const reverted = []; const untouched = []; const failed = [];
+    for (const f of batch.files) {
+      const hits = log.filter((e) => e.file === f.file && !e.reverted && e.newSha === f.newSha.slice(0, 16) && e.appliedAt >= batch.startedAt && (e.status === 'applied' || e.status === 'applied-stale'));
+      if (!hits.length) { untouched.push(f.file); continue; }
+      for (const e of hits.reverse()) {
+        const r = await revertEntryById(scanRoot, e.id);
+        if (r && !r.error) reverted.push(f.file); else failed.push(f.file);
+      }
+    }
+    // an interrupted atomic write leaves a hidden temp file beside its target
+    for (const f of batch.files) {
+      const d = path.dirname(path.join(path.resolve(scanRoot), f.file));
+      try { for (const t of await fsp.readdir(d)) if (STRAY_TMP.test(t)) await fsp.unlink(path.join(d, t)).catch(() => {}); } catch { /* directory gone */ }
+    }
+    await abandonBatch(scanRoot, batch, failed.length ? 'rollback-incomplete' : 'rolled-back');
+    out.push({ batch: batch.id, reverted: [...new Set(reverted)], untouched, failed });
+  }
+  return out;
+}

package/src/fix/exploit-replay.js

@@ -0,0 +1,51 @@
+// Controlled pre/post exploit replay for a candidate patch (E3-04).
+//
+// Runs the SAME local reproducer against the pristine code and then against the code with the patch overlaid, using the proof fabric's
+// confined runner (confined filesystem, scrubbed environment, bounded time and output, no external network, repository sources read-only
+// and confined to the scan root). It targets only files under `scanRoot`; there is no URL input.
+//
+// What each outcome means:
+//   before  every attempt completed and the oracle fired in all of them   -> the exploit is real on the original code
+//   after   every attempt completed and the oracle fired in none          -> the patch blocks it
+//   anything that did not complete (timeout, build failure, no sandbox, invalid reproducer) is `not_run`/inconclusive. It is NEVER read
+//   as "the exploit failed", so an unavailable replay cannot masquerade as a fix.
+//
+// `executionProven` is true only when the precondition held (before) AND the postcondition failed on completed runs (after). It says the
+// exploit stopped; whether the intended behaviour survived is a different question (functional preservation, E3-05).
+import { runAttempt as defaultAttempt } from '../posture/proof-fabric/runner.js';
+import { validateReproducer, reproducerDigest } from '../posture/proof-fabric/reproducer.js';
+
+const clampAttempts = (n) => Math.max(1, Math.min(5, Number.isInteger(n) ? n : 3));
+
+async function series(reproducer, n, opts, attemptFn) {
+  const rows = [];
+  for (let i = 0; i < n; i++) {
+    if (opts.signal?.aborted) break;
+    const r = await attemptFn(structuredClone(reproducer), opts);
+    rows.push({ status: r.status, fired: r.oracle?.fired === true, inconclusive: r.oracle?.inconclusive === true || r.status !== 'completed', reasons: r.reasons || [], degraded: r.degraded || [] });
+  }
+  return rows;
+}
+
+const summarize = (rows) => ({ attempts: rows.length, completed: rows.filter((r) => !r.inconclusive).length, fired: rows.filter((r) => r.fired && !r.inconclusive).length, statuses: rows.map((r) => r.status), reasons: [...new Set(rows.flatMap((r) => r.reasons))].slice(0, 5) });
+
+/**
+ * @param {{scanRoot:string, reproducer:object, files:Record<string,string>, attempts?:number, timeoutMs?:number, signal?:AbortSignal, attemptFn?:Function}} o
+ */
+export async function replayExploit({ scanRoot, reproducer, files, attempts, timeoutMs, signal, attemptFn = defaultAttempt }) {
+  const base = { schema: 'agentic-security/exploit-replay', version: 1, reproducerDigest: null };
+  const errs = validateReproducer(reproducer);
+  if (errs.length) return { ...base, before: null, after: null, beforeStatus: 'not_run', afterStatus: 'not_run', executionProven: false, reason: `the reproducer is invalid: ${errs[0]}` };
+  base.reproducerDigest = reproducerDigest(reproducer);
+  const n = clampAttempts(attempts);
+  const common = { sourceRoot: scanRoot, requireContainer: false, signal, limits: timeoutMs ? { timeoutMs } : undefined };
+
+  const before = summarize(await series(reproducer, n, common, attemptFn));
+  if (before.completed < before.attempts || before.attempts === 0) return { ...base, before, after: null, beforeStatus: 'not_run', afterStatus: 'not_run', executionProven: false, reason: `the original-code replay did not complete (${before.reasons[0] || before.statuses.join(',')}), so nothing can be said about the patch` };
+  if (before.fired < before.attempts) return { ...base, before, after: null, beforeStatus: 'not_run', afterStatus: 'not_run', executionProven: false, reason: `the exploit did not succeed on the original code in all ${before.attempts} attempts (${before.fired}), so the precondition is not established` };
+
+  const after = summarize(await series(reproducer, n, { ...common, overlay: files }, attemptFn));
+  if (after.fired > 0) return { ...base, before, after, beforeStatus: 'passed', afterStatus: 'failed', executionProven: false, reason: `the exploit still succeeds against the patched code (${after.fired} of ${after.attempts})` };
+  if (after.completed < after.attempts || after.attempts === 0) return { ...base, before, after, beforeStatus: 'passed', afterStatus: 'not_run', executionProven: false, reason: `the patched replay did not complete (${after.reasons[0] || after.statuses.join(',')}); an incomplete replay is not a blocked exploit` };
+  return { ...base, before, after, beforeStatus: 'passed', afterStatus: 'passed', executionProven: true, mechanism: 'the oracle did not fire in any completed replay of the patched code', reason: null };
+}

package/src/fix/footprint.js

@@ -0,0 +1,65 @@
+// Functional footprint of a patch (E3-05): did the patch fix the weakness, or remove the feature?
+//
+// A rescan only proves the finding stopped firing. A patch that deletes the vulnerable behaviour (a blanket 403 on an IDOR route, a 501 on
+// the SQL endpoint, an emptied file) satisfies that just as well, so it is checked separately: the kinds of sensitive operation the
+// changed files performed BEFORE the patch must still be performed AFTER it. A parameterised query is still a database read; an
+// execFile call is still a process execution; a deny-all handler is neither.
+//
+// This is a HEURISTIC over source text, not a proof of equivalence. It catches the removal of a whole operation kind, not a subtler
+// behaviour change. When it cannot see any operation kind in the original it says `unobservable` and the leg is not_run, never passed.
+const KINDS = {
+  'process-exec': /require\s*\(\s*['"](?:node:)?child_process['"]\s*\)|from\s+['"](?:node:)?child_process['"]|\b(?:execSync|execFileSync|execFile|spawnSync|spawn|exec|system|popen|Runtime\s*\.\s*getRuntime\s*\(\s*\)\s*\.\s*exec|ProcessBuilder|subprocess\s*\.\s*\w+|os\s*\.\s*system|shell_exec|passthru|proc_open)\s*\(/,
+  'data-access': /\b(?:SELECT|INSERT\s+INTO|UPDATE|DELETE\s+FROM)\b|\.(?:find|findOne|findById|findAll|findUnique|findFirst|query|execute|executeQuery|executemany|prepare|raw|where|get_object_or_404|createQuery|queryForObject)\s*\(|\b(?:db|database|conn|connection|pool|cursor|collection|repository|repo|prisma|knex|sequelize|session)\w*\s*\.\s*\w+\s*\(/i,
+  'file-access': /\b(?:readFile|readFileSync|createReadStream|writeFile|writeFileSync|createWriteStream|sendFile|readdir|readdirSync|unlink|open|os\.Open|ioutil\.ReadFile|file_get_contents|File\s*\(|FileInputStream|FileReader|Files\s*\.\s*\w+)\s*\(/,
+  'network-out': /\b(?:fetch|axios|got|request|urlopen|requests\s*\.\s*\w+|http\s*\.\s*(?:get|request)|https\s*\.\s*(?:get|request)|HttpClient|http\.Get|curl_exec)\s*\(/,
+  'html-output': /\b(?:res|response|reply|ctx)\b[^;\n]*\.\s*(?:send|write|render|json|end)\s*\(|\b(?:render_template|HttpResponse|JsonResponse|jsonify|innerHTML|echo|ResponseEntity|c\.JSON|c\.String)\b/,
+};
+const DENIAL = /\b(?:status\s*\(\s*(?:401|403|404|405|410|501|503)\s*\)|(?:abort|HTTPException|http_error|ResponseStatusException)\s*\(\s*(?:401|403|404|501)|(?:PermissionDenied|Forbidden|NotImplemented|AccessDenied|Unauthorized)\b|(?:forbidden|not implemented|access denied|disabled)\b|return\s+(?:403|401|501)\b|StatusForbidden|StatusNotImplemented)/i;
+// Which kinds a CWE's fix must keep. Unlisted weaknesses are held to every kind the original had.
+const CWE_KINDS = {
+  'CWE-78': ['process-exec'], 'CWE-77': ['process-exec'], 'CWE-89': ['data-access'], 'CWE-564': ['data-access'], 'CWE-22': ['file-access'], 'CWE-73': ['file-access'],
+  'CWE-918': ['network-out'], 'CWE-79': ['html-output'], 'CWE-639': ['data-access'], 'CWE-284': ['data-access'], 'CWE-285': ['data-access'], 'CWE-862': ['data-access'], 'CWE-863': ['data-access'], 'CWE-566': ['data-access'],
+};
+
+const stripComments = (t) => String(t || '').replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:\\])\/\/[^\n]*/g, '$1').replace(/(^|\s)#[^\n!][^\n]*/g, '$1');
+const codeLines = (t) => stripComments(t).split('\n').filter((l) => l.trim() && !/^\s*[{}();,]*\s*$/.test(l)).length;
+
+export function kindsOf(text) {
+  const src = stripComments(text);
+  return Object.entries(KINDS).filter(([, re]) => re.test(src)).map(([k]) => k).sort();
+}
+
+/**
+ * @param {{before:Record<string,string|null>, after:Record<string,string>, cwe?:string|null, intentionalRemoval?:{reason:string}|null}} o
+ * @returns {{status:'passed'|'failed'|'not_run', reason:string|null, files:object[], lost:string[]}}
+ */
+export function checkFootprint({ before, after, cwe = null, intentionalRemoval = null }) {
+  const required = CWE_KINDS[String(cwe || '').toUpperCase()] || null;
+  const files = [];
+  const lostAll = new Set();
+  let observed = false;
+  for (const [rel, afterText] of Object.entries(after)) {
+    const b = before[rel];
+    if (b === null || b === undefined) { files.push({ file: rel, note: 'new file' }); continue; }
+    const kb = kindsOf(b); const ka = kindsOf(afterText);
+    const held = required ? kb.filter((k) => required.includes(k)) : kb;
+    if (held.length) observed = true;
+    let lost = held.filter((k) => !ka.includes(k));
+    const emptied = codeLines(afterText) === 0 && codeLines(b) > 0;
+    const denialOnly = lost.length > 0 && DENIAL.test(stripComments(afterText)) && !DENIAL.test(stripComments(b));
+    // With no known weakness class, losing an operation kind is not by itself a defect (an auth fix may legitimately drop a response path).
+    // What marks feature REMOVAL is the signature of it: the file emptied, or the lost operation replaced by a deny response.
+    if (!required && !emptied && !denialOnly) lost = [];
+    const shrunk = codeLines(b) >= 6 && codeLines(afterText) <= Math.floor(codeLines(b) * 0.25);
+    files.push({ file: rel, kindsBefore: kb, kindsAfter: ka, lost, emptied, denialOnly, shrunk });
+    if (emptied) { lost.push('everything'); observed = true; }
+    for (const k of lost) lostAll.add(k);
+  }
+  if (!observed && ![...lostAll].length) return { status: 'not_run', reason: 'unobservable: no sensitive operation was recognised in the original files, so removal of the feature cannot be judged', files, lost: [] };
+  if (lostAll.size) {
+    if (intentionalRemoval && typeof intentionalRemoval.reason === 'string' && intentionalRemoval.reason.trim()) return { status: 'not_run', reason: `the patch removes ${[...lostAll].join(', ')} and the caller declared that intentional (${intentionalRemoval.reason.trim().slice(0, 200)}); a person must confirm it`, files, lost: [...lostAll] };
+    const why = files.filter((f) => f.lost?.length).map((f) => `${f.file}: no longer performs ${f.lost.join(', ')}${f.denialOnly ? ' (replaced by a deny response)' : ''}${f.emptied ? ' (file emptied)' : ''}`).join('; ');
+    return { status: 'failed', reason: `the patch removes functionality instead of fixing it: ${why}`, files, lost: [...lostAll] };
+  }
+  return { status: 'passed', reason: null, files, lost: [] };
+}

package/src/fix/patch-policy.js

@@ -0,0 +1,49 @@
+// Risk-tiered patch policy (E3-06): given a verified-patch record, may it be applied without a person, proposed for a person, or refused?
+//
+// Two modes. `requested` is a person (or an agent acting for one) who asked for the write: it proceeds on any tier that is not
+// unverified or blocked, and the result carries the degraded legs as warnings so nothing about the pass is hidden. `automatic` is
+// anything that would write with nobody asking: it is OFF unless the policy enables it, and even then it applies only a configured
+// low-risk patch whose every REQUIRED check passed. Absent tests, a replay that did not run, an unobservable footprint, or any other
+// degraded leg make an automatic write a proposal, never a silent write. Preview and undo are never removed by this module.
+//
+// Pure: no fs, no clock.
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+const AUTH_CATEGORIES = /auth|crypto|permission|access|privilege|session|tenant/i;
+
+export const DEFAULT_POLICY = Object.freeze({
+  automatic: Object.freeze({ enabled: false, maxSeverity: 'medium', allowedMaterialRisk: Object.freeze(['low']), requireExploitProof: false, maxResidualRisk: 'low' }),
+});
+const RESIDUAL_RANK = { none: 0, low: 1, medium: 2, high: 3, unknown: 4 };
+
+export { deriveResidualRiskOf as deriveResidualRisk } from './verification-record.js';
+
+const decide = (decision, record, reasons, extra = {}) => ({ decision, tier: record.fixCompleteness, verifiedFull: record.verifiedFull, residualRisk: record.residualRisk, reasons, warnings: record.degradedLegs, preview: true, undo: true, ...extra });
+
+/**
+ * @param {{record:object, finding?:{severity?:string}, materialClassification?:{highImpactCategories?:string[], risk?:string}, mode?:'requested'|'automatic', policy?:object}} o
+ */
+export function decidePatchApplication({ record, finding = {}, materialClassification = {}, mode = 'requested', policy = DEFAULT_POLICY }) {
+  const tier = record.fixCompleteness;
+  if (tier === 'blocked') return decide('refuse', record, ['a required check was blocked or a failure was recorded, so the patch cannot be applied']);
+  if (tier === 'unverified') return decide('refuse', record, ['the weakness is not shown to be gone, or a check failed']);
+  if (mode === 'requested') return decide('apply', record, [`${tier}: applied at the request of a person`]);
+
+  const a = { ...DEFAULT_POLICY.automatic, ...(policy?.automatic || {}) };
+  if (!a.enabled) return decide('propose', record, ['automatic application is not enabled by policy; the patch is proposed for a person to apply']);
+  const reasons = [];
+  if (tier !== 'FULL') reasons.push(`completeness is ${tier}, automatic application needs FULL`);
+  if (!record.verifiedFull) reasons.push('not every required check passed');
+  for (const d of record.degradedLegs) reasons.push(`degraded: ${d}`);
+  if (a.requireExploitProof && record.exploitProofAfter.status !== 'passed') reasons.push('policy requires an exploit replay and none confirmed the fix');
+  for (const leg of ['behaviorTests', 'behaviorPreservation']) if (record[leg].status !== 'passed') reasons.push(`${leg} did not pass (${record[leg].status})`);
+  const sev = SEVERITY_RANK[String(finding.severity || '').toLowerCase()];
+  if (sev === undefined) reasons.push('the finding severity is unknown');
+  else if (sev > SEVERITY_RANK[a.maxSeverity]) reasons.push(`severity ${finding.severity} is above the automatic limit (${a.maxSeverity})`);
+  const cats = materialClassification.highImpactCategories || [];
+  if (cats.length) reasons.push(`high-impact change (${cats.join(', ')}) needs a person`);
+  if (cats.some((c) => AUTH_CATEGORIES.test(c))) reasons.push('the change alters authentication, authorization or cryptography');
+  if (materialClassification.risk && !a.allowedMaterialRisk.includes(materialClassification.risk)) reasons.push(`material risk ${materialClassification.risk} is not in the allowed set`);
+  if ((RESIDUAL_RANK[record.residualRisk.level] ?? 4) > RESIDUAL_RANK[a.maxResidualRisk]) reasons.push(`residual risk ${record.residualRisk.level} is above ${a.maxResidualRisk}`);
+  if (reasons.length) return decide('propose', record, reasons);
+  return decide('apply', record, ['FULL, low risk, every required check passed']);
+}

package/src/fix/secret-persistence.js

@@ -0,0 +1,39 @@
+// Did the patch REMOVE a hard-coded secret, or only change how it is written? (E3-08)
+//
+// Moving `const k = 'abc123...'` to `const k = atob('YWJjMTIz...')`, splitting it in two literals, reversing it or hex-encoding it all
+// make a pattern-based scanner stop seeing a secret that is still in the source. This looks for the original literal after the patch in
+// the forms a lazy "fix" uses. It cannot catch encryption with a key kept next to it or other transformations; it says what it checked.
+const MIN_LEN = 8;
+
+const literalsOnLines = (text, lines) => {
+  const out = new Set();
+  const all = String(text).split('\n');
+  for (const n of lines) {
+    const l = all[n - 1];
+    if (!l) continue;
+    for (const m of l.matchAll(/(["'`])((?:\\.|(?!\1).){8,})\1/g)) out.add(m[2]);
+  }
+  return [...out].filter((s) => s.length >= MIN_LEN);
+};
+const squash = (t) => String(t).replace(/["'`+\s]/g, '');
+const forms = (v) => {
+  const b64 = Buffer.from(v).toString('base64');
+  return [v, [...v].reverse().join(''), Buffer.from(v).toString('hex'), b64, b64.replace(/=+$/, ''), encodeURIComponent(v)].filter((x) => x.length >= MIN_LEN);
+};
+
+/**
+ * @param {{before:string, after:string, line:number|null}} o
+ * @returns {{status:'passed'|'failed'|'not_run', reason:string|null, checked:number}}
+ */
+export function checkSecretPersistence({ before, after, line }) {
+  if (!Number.isInteger(line) || line < 1) return { status: 'not_run', reason: 'the finding has no line, so the secret literal cannot be located', checked: 0 };
+  const lits = literalsOnLines(before, [line - 1, line, line + 1].filter((n) => n >= 1));
+  if (!lits.length) return { status: 'not_run', reason: 'no string literal of 8 or more characters near the finding line', checked: 0 };
+  const flat = squash(after);
+  for (const lit of lits) {
+    for (const f of forms(lit)) {
+      if (String(after).includes(f) || flat.includes(squash(f))) return { status: 'failed', reason: `the secret is still in the source (${f === lit ? 'unchanged' : 'as a re-encoded or split form'}); moving or encoding it does not remove it`, checked: lits.length };
+    }
+  }
+  return { status: 'passed', reason: null, checked: lits.length };
+}

package/src/fix/test-commands.js

@@ -0,0 +1,84 @@
+// Run the project's tests against the PATCHED tree, in a throwaway copy (E3-05).
+//
+// verifyFix used to run the tests on the tree as it was before the patch was written, which says nothing about the patch. Here the
+// patch is overlaid on a copy and the tests run there; the real tree is never touched.
+//
+// Runner discovery covers what the existing detector does (npm/pnpm/yarn/bun scripts, pytest, go test) plus cargo, dotnet, maven,
+// gradle and rspec, and an explicit argv from the caller (`command`) which always wins. Commands are argv arrays, never a shell string.
+// When the patched run fails the pristine copy is run too, so "the suite was already red" is not mistaken for "the patch broke it".
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { detectTestCommand } from '../posture/test-runner.js';
+import { STATE_DIR_NAME } from '../posture/state-dir.js';
+
+const MAX_COPY_BYTES = 200 * 1024 * 1024;
+const SKIP_DIRS = new Set(['.git', STATE_DIR_NAME, 'node_modules', 'target', 'dist', 'build', '.venv', '__pycache__', 'bin', 'obj']);
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+const has = (root, rel) => { try { return fs.existsSync(path.join(root, rel)); } catch { return false; } };
+const available = (cmd) => { try { const r = spawnSync(cmd, ['--version'], { timeout: 8000, stdio: 'ignore' }); return !(r.error && r.error.code === 'ENOENT'); } catch { return false; } };
+
+/** @returns {{cmd:string,args:string[],kind:string}|null} */
+export function discoverTestCommand(root, { available: avail = available } = {}) {
+  const base = detectTestCommand(root);
+  if (base) return base;
+  if (has(root, 'Cargo.toml') && avail('cargo')) return { cmd: 'cargo', args: ['test', '--quiet'], kind: 'cargo' };
+  try { if (fs.readdirSync(root).some((f) => /\.(sln|csproj)$/.test(f)) && avail('dotnet')) return { cmd: 'dotnet', args: ['test', '--nologo'], kind: 'dotnet' }; } catch { /* unreadable root */ }
+  if (has(root, 'pom.xml') && avail('mvn')) return { cmd: 'mvn', args: ['-q', 'test'], kind: 'maven' };
+  if ((has(root, 'build.gradle') || has(root, 'build.gradle.kts')) && avail('gradle')) return { cmd: 'gradle', args: ['test', '--quiet'], kind: 'gradle' };
+  if ((has(root, '.rspec') || has(root, 'spec')) && has(root, 'Gemfile') && avail('bundle')) return { cmd: 'bundle', args: ['exec', 'rspec'], kind: 'rspec' };
+  return null;
+}
+
+function copyTree(root, dest) {
+  let bytes = 0;
+  fs.cpSync(root, dest, {
+    recursive: true, dereference: false, verbatimSymlinks: true,
+    filter: (src) => {
+      const rel = path.relative(root, src);
+      if (!rel) return true;
+      if (rel.split(path.sep).some((s) => SKIP_DIRS.has(s))) return false;
+      try { const st = fs.lstatSync(src); if (st.isFile()) { bytes += st.size; if (bytes > MAX_COPY_BYTES) throw new Error('tree-too-large'); } } catch (e) { if (e.message === 'tree-too-large') throw e; }
+      return true;
+    },
+  });
+  // dependencies are linked, not copied: tests need them, and the copy must not be able to change them
+  const nm = path.join(root, 'node_modules');
+  if (fs.existsSync(nm)) { try { fs.symlinkSync(nm, path.join(dest, 'node_modules'), 'dir'); } catch { /* best effort */ } }
+}
+
+function run(cwd, cmd, args, timeoutMs) {
+  const t0 = Date.now();
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: timeoutMs, env: { ...process.env, CI: '1' } });
+  const durationMs = Date.now() - t0;
+  if (r.error && r.error.code === 'ENOENT') return { status: 'skipped', passed: null, skipped: true, reason: `${cmd}-not-installed`, exitCode: null, timedOut: false, durationMs };
+  if (r.status === null) return { status: 'failed', passed: false, skipped: false, reason: 'timed-out', exitCode: null, timedOut: true, durationMs };
+  return { status: r.status === 0 ? 'passed' : 'failed', passed: r.status === 0, skipped: false, reason: r.status === 0 ? null : `exit-${r.status}`, exitCode: r.status, timedOut: false, durationMs };
+}
+
+/**
+ * @param {{scanRoot:string, files:Record<string,string>, command?:string[], timeoutMs?:number}} o
+ */
+export function runTestsOnPatchedCopy({ scanRoot, files, command, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const spec = command && command.length ? { cmd: command[0], args: command.slice(1), kind: 'explicit' } : discoverTestCommand(scanRoot);
+  if (!spec) return { status: 'skipped', passed: null, skipped: true, reason: 'no-test-command-detected', exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false };
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'patched-tests-'));
+  try {
+    const patched = path.join(work, 'patched');
+    try { copyTree(scanRoot, patched); } catch (e) { return { status: 'skipped', passed: null, skipped: true, reason: e.message === 'tree-too-large' ? 'tree-too-large-to-copy' : `copy-failed: ${e.message}`, exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false }; }
+    for (const [rel, text] of Object.entries(files || {})) {
+      const abs = path.resolve(patched, rel);
+      if (abs !== patched && !abs.startsWith(patched + path.sep)) return { status: 'skipped', passed: null, skipped: true, reason: 'patch-path-escapes-the-copy', exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false };
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, String(text));
+    }
+    const result = { ...run(patched, spec.cmd, spec.args, timeoutMs), runner: spec.kind, onPatchedTree: true, preExistingFailure: false };
+    if (result.status === 'failed') {
+      const pristine = path.join(work, 'pristine');
+      try { copyTree(scanRoot, pristine); const base = run(pristine, spec.cmd, spec.args, timeoutMs); if (base.status === 'failed') result.preExistingFailure = true; } catch { /* attribution is best effort */ }
+    }
+    return result;
+  } finally { fs.rmSync(work, { recursive: true, force: true }); }
+}

package/src/fix/verification-adapters.js

@@ -0,0 +1,97 @@
+// Adapters from the results the existing routes already produce to the patch-level verification record (E3-02).
+//
+// An adapter only RELAYS: it maps what a route observed onto legs, and anything the route did not observe becomes `not_run` with the
+// reason. It never upgrades a result. In particular a test run that happened before the patch was written (verifyFix sets
+// `testedPrePatch`) is recorded as `not_run` for the patched tree, not as passed.
+import { createHash } from 'node:crypto';
+import { digestOf } from '../posture/assurance/identity.js';
+import { buildFixVerificationRecord, evidenceItem, leg } from './verification-record.js';
+
+const sha256Hex = (s) => createHash('sha256').update(s).digest('hex');
+
+/** Digest of a patch: the files it writes, by path and content digest. Independent of key order. */
+export function patchHashOf(files) {
+  const rows = Object.keys(files || {}).sort().map((p) => [p, sha256Hex(String(files[p]))]);
+  return digestOf({ files: rows });
+}
+
+/** Digest of the files as they were before the patch, for the paths the patch touches. `read(path)` returns the text or null. */
+export function treeHashOf(paths, read) {
+  const rows = [...paths].sort().map((p) => { const t = read(p); return [p, t === null || t === undefined ? null : sha256Hex(String(t))]; });
+  return digestOf({ files: rows });
+}
+
+const asEvidence = (kind, value, note = null) => evidenceItem({ kind, mediaType: 'application/json', sha256: digestOf(value).slice('sha256:'.length), note });
+
+/**
+ * @param {object} v        the object verifyFix returns
+ * @param {object} ctx      { finding:{id,stableId}, files, route, mode, preCommit, preFiles(read), tools, requiredLegs, findingPresent }
+ */
+export function recordFromVerifyFix(v, ctx) {
+  const evidence = [];
+  const add = (kind, value, note) => { const e = asEvidence(kind, value, note); if (!evidence.some((x) => x.id === e.id)) evidence.push(e); return e.id; };
+  const failures = [];
+
+  const rescanId = v.rescan ? add('rescan-result', v.rescan, 'verifyFix rescan leg') : null;
+  const securityAfter = !v.rescan ? leg('not_run', { reason: 'the route returned no rescan result' })
+    : v.rescan.ok ? leg('passed', { evidenceIds: [rescanId] }) : leg('failed', { evidenceIds: [rescanId], reason: `the original finding is still present (${v.rescan.reason})` });
+  if (ctx.persistence?.status === 'failed') {
+    const id = add('secret-persistence', ctx.persistence, 'the original secret literal searched for in the patched source');
+    securityAfter.status = 'failed'; securityAfter.evidenceIds = [...securityAfter.evidenceIds, id]; securityAfter.reason = ctx.persistence.reason;
+  }
+  const introduced = v.rescan?.introduced || [];
+  const newFindingDelta = !v.rescan ? leg('not_run', { reason: 'the route returned no rescan result' })
+    : introduced.length ? leg('failed', { evidenceIds: [rescanId], reason: `${introduced.length} finding(s) introduced by the patch` }) : leg('passed', { evidenceIds: [rescanId] });
+
+  let lint;
+  if (!v.lint) lint = leg('not_run', { reason: 'the route returned no lint result' });
+  else if (v.lint.runner === 'none') lint = leg('not_applicable', { reason: 'no linter is configured for this project' });
+  else lint = v.lint.ok ? leg('passed', { evidenceIds: [add('lint-result', v.lint)] }) : leg('failed', { evidenceIds: [add('lint-result', v.lint)], reason: 'the linter reported errors on the patched files' });
+
+  let behaviorTests;
+  if (!v.tests) behaviorTests = leg('not_run', { reason: 'the route returned no test result' });
+  else if (v.tests.skipped) behaviorTests = leg('not_run', { reason: `tests were skipped (${v.tests.reason || 'no reason recorded'})` });
+  else if (v.tests.preExistingFailure || v.tests.reason === 'suite-already-failing-before-the-patch') behaviorTests = leg('not_run', { reason: 'the project test suite was already failing before the patch, so it cannot show the patch preserved behaviour' });
+  else if (v.testedPrePatch) behaviorTests = leg('not_run', { evidenceIds: [], reason: 'the tests ran on the tree BEFORE the patch was written, so they say nothing about the patch' });
+  else behaviorTests = v.tests.passed ? leg('passed', { evidenceIds: [add('test-result', v.tests)] }) : leg('failed', { evidenceIds: [add('test-result', v.tests)], reason: 'the project tests failed on the patched tree' });
+
+  const poc = v.poc?.status;
+  const pocId = v.poc && poc !== 'not-requested' ? add('exploit-replay', v.poc) : null;
+  const replay = ctx.replay || null;
+  const replayId = replay ? add('exploit-replay', replay, 'pre/post replay of the same reproducer') : null;
+  const replayLeg = (status, ok, bad) => status === 'passed' ? leg('passed', { evidenceIds: [replayId] }) : status === 'failed' ? leg('failed', { evidenceIds: [replayId], reason: bad }) : leg('not_run', { reason: replay.reason || ok });
+  const exploitProofAfter = replay ? replayLeg(replay.afterStatus, 'the replay did not run', replay.reason) : !v.poc || poc === 'not-requested' ? leg('not_run', { reason: 'no exploit replay was requested by this route' })
+    : poc === 'no-longer-proven' ? leg('passed', { evidenceIds: [pocId] })
+    : poc === 'still-exploitable' ? leg('failed', { evidenceIds: [pocId], reason: 'the exploit still works against the patched code' })
+    : leg('not_run', { evidenceIds: [], reason: `the exploit replay was inconclusive (${v.poc.reason || 'no reason recorded'})` });
+  const exploitProofBefore = replay ? replayLeg(replay.beforeStatus, 'the replay did not run', replay.reason) : !v.poc || poc === 'not-requested' ? leg('not_run', { reason: 'no exploit replay was requested by this route' })
+    : poc === 'inconclusive' ? leg('not_run', { reason: 'the exploit could not be reproduced on the original code' })
+    : leg('passed', { evidenceIds: [pocId] });
+
+  const findingEv = ctx.findingPresent === true && ctx.finding ? add('finding', { id: ctx.finding.id, stableId: ctx.finding.stableId ?? null }, 'the finding in the signed scan') : null;
+  const securityBefore = findingEv ? leg('passed', { evidenceIds: [findingEv] }) : leg('not_run', { reason: 'the finding was not shown to be present on the original code' });
+
+  if (v.honesty && v.honesty.ok === false) failures.push({ leg: 'securityAfter', reason: 'the honesty gate refused the claimed fix quality' });
+
+  const fp = ctx.footprint || null;
+  const footprintLeg = !fp ? leg('not_run', { reason: 'this route does not check that intended functionality survived' })
+    : fp.status === 'passed' ? leg('passed', { evidenceIds: [add('footprint', fp, 'sensitive operation kinds before and after the patch')] })
+    : fp.status === 'failed' ? leg('failed', { evidenceIds: [add('footprint', fp, 'sensitive operation kinds before and after the patch')], reason: fp.reason })
+    : leg('not_run', { reason: fp.reason });
+  const files = ctx.files || {};
+  return buildFixVerificationRecord({
+    findingId: ctx.finding?.id ?? 'unknown', findingStableId: ctx.finding?.stableId, mode: ctx.mode || 'verify', route: ctx.route || 'verify-fix',
+    preCommit: ctx.preCommit ?? null, preTreeHash: ctx.preFiles ? treeHashOf(Object.keys(files), ctx.preFiles) : null, postPatchHash: patchHashOf(files), patchHash: patchHashOf(files),
+    affectedFiles: Object.keys(files),
+    securityBefore, securityAfter, exploitProofBefore, exploitProofAfter, newFindingDelta, behaviorTests, lint,
+    behaviorPreservation: footprintLeg,
+    regressionTests: leg('not_run', { reason: 'this route runs a single test leg' }),
+    typecheck: leg('not_run', { reason: 'this route does not run a type checker' }),
+    dependencyChecks: leg('not_applicable', { reason: 'a source patch changes no dependency' }),
+    requiredLegs: ctx.requiredLegs || ['securityAfter', 'newFindingDelta', 'behaviorTests'],
+    failures, evidence, tools: ctx.tools || { engineVersion: null, verifier: 'verifyFix' },
+    residualRisk: ctx.residualRisk,
+    confidence: ctx.confidence || (replay?.executionProven ? { level: 'proven', policy: 'exploit-replay-v1', evidenceIds: [replayId] } : undefined),
+    ...(ctx.timestamps ? { timestamps: ctx.timestamps } : {}),
+  });
+}