@clear-capabilities/agentic-security-scanner 0.143.0 → 0.145.0

package/src/posture/encryption-provider.js

@@ -0,0 +1,205 @@
+// FR-705 (assurance-hardening PRD): "Encrypt state classes marked
+// confidential when an encryption provider is configured or required |
+// Required encryption absence fails before sensitive state is written."
+//
+// SCOPE (Phase 1 of a deliberately staged rollout — see this module's own
+// header for what is and is not covered, and D-0039-style honesty about
+// what remains):
+//
+//   - Confidentiality is a NEW `confidential: true` field on specific
+//     artifact-registry.js entries (see that module for the exact list and
+//     the reasoning for each). `last-scan.json`/`findings.json` are
+//     DELIBERATELY EXCLUDED from Phase 1: dozens of commands read them
+//     directly as plain JSON, so encrypting them is a much larger,
+//     separate migration (every reader needs a decrypt-on-read hook) —
+//     doing that alongside a handful of narrow, low-traffic audit/evidence
+//     artifacts in one pass would repeat exactly the "large, structurally-
+//     coupled epic attempted in one unplanned cycle" mistake this session
+//     has deliberately avoided elsewhere (see D-0028, D-0039).
+//   - ONE provider is implemented: 'local-key' — AES-256-GCM with a
+//     per-install key generated the first time encryption is actually
+//     used, stored at the same $XDG_CONFIG_HOME/agentic-security/ directory
+//     integrity.js already uses for its own signing key (a SEPARATE key
+//     file — never reuse one key across different cryptographic purposes).
+//     A KMS/envelope-encryption provider is a real future extension point
+//     (the provider interface is already shaped to allow one) but is out
+//     of scope here: this codebase makes no runtime cloud calls, and a KMS
+//     call is unavoidably a network call.
+//   - "Configured or required" is a per-project opt-in policy file
+//     (.agentic-security/encryption-policy.yml: `provider: local-key`,
+//     `required: true|false`). No file means "not configured, not
+//     required" — every confidential artifact keeps writing exactly as it
+//     always has, so this feature is inert until an operator opts in,
+//     matching every other policy surface in this codebase
+//     (retention-policy.yml, risk-config.yml, sca-policy.yml, ...).
+//   - The FAIL-CLOSED half of the acceptance criterion is
+//     `maybeEncryptForWrite`'s own contract: when `required: true` is set
+//     for a confidential artifact but no working provider is available,
+//     it returns `{ok:false}` — the caller must not write ANYTHING in that
+//     case, plaintext or otherwise. This is checked BEFORE any bytes touch
+//     disk, per the literal "fails before sensitive state is written"
+//     wording.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from '../util/yaml.js';
+import { statePath } from './state-dir.js';
+import { confidentialOf } from './artifact-registry.js';
+
+export const ENCRYPTION_POLICY_FILE = 'encryption-policy.yml';
+export const ENCRYPTION_MARKER = '__agentic_security_encrypted_v1__';
+const KEY_FILE_NAME = 'encryption-key';
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+
+function _keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length ? xdg : path.join(os.homedir(), '.config');
+  return path.join(base, 'agentic-security');
+}
+function _keyPath() { return path.join(_keyDir(), KEY_FILE_NAME); }
+
+// Same atomic-publish shape as integrity.js's _publishKeyAtomically — a
+// hard-link into place is atomic and fails EEXIST rather than clobbering,
+// closing the same first-writer-wins race a plain exclusive-create alone
+// leaves open on filesystems without hard-link support (documented in
+// integrity.js's own header; reproduced here rather than imported, since
+// this is a genuinely separate key with its own purpose and no reason to
+// couple the two modules' internals together).
+function _publishKeyAtomically(fp, contents) {
+  const dir = _keyDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `${KEY_FILE_NAME}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, contents, { mode: 0o600 });
+    try {
+      fs.linkSync(tmp, fp);
+      return 'created';
+    } catch (e) {
+      if (e.code === 'EEXIST') return 'exists';
+      try {
+        fs.writeFileSync(fp, contents, { mode: 0o600, flag: 'wx' });
+        return 'created';
+      } catch (e2) {
+        if (e2.code === 'EEXIST') return 'exists';
+        throw e2;
+      }
+    }
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+  }
+}
+
+function _readOrGenerateKey() {
+  const fromEnv = process.env.AGENTIC_SECURITY_ENCRYPTION_KEY;
+  if (fromEnv && /^[0-9a-fA-F]{64}$/.test(fromEnv.trim())) return Buffer.from(fromEnv.trim(), 'hex');
+  const fp = _keyPath();
+  try {
+    if (fs.existsSync(fp)) {
+      const hex = fs.readFileSync(fp, 'utf8').trim();
+      if (/^[0-9a-fA-F]{64}$/.test(hex)) return Buffer.from(hex, 'hex');
+    }
+  } catch { /* fall through to generate */ }
+  const buf = crypto.randomBytes(32);
+  try {
+    const outcome = _publishKeyAtomically(fp, buf.toString('hex') + '\n');
+    if (outcome === 'created') return buf;
+    const hex = fs.readFileSync(fp, 'utf8').trim();
+    return Buffer.from(hex, 'hex');
+  } catch {
+    return buf; // ephemeral — a write can proceed this run, but nothing encrypted with it will ever decrypt again. Degraded, not blocked.
+  }
+}
+
+/**
+ * Read `.agentic-security/encryption-policy.yml`. Never throws; a missing
+ * or malformed file is "not configured, not required" (the safe,
+ * inert-by-default state every other policy file in this codebase uses).
+ */
+export function loadEncryptionPolicy(scanRoot) {
+  let fp;
+  try { fp = statePath(scanRoot, ENCRYPTION_POLICY_FILE); } catch { return null; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return null; }
+  try {
+    const doc = yaml.load(raw);
+    if (!doc || typeof doc !== 'object') return null;
+    const provider = doc.provider === 'local-key' ? 'local-key' : null;
+    return { provider, required: doc.required === true };
+  } catch { return null; }
+}
+
+function _encryptBuffer(plaintext, key) {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return { iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ciphertext: ciphertext.toString('base64') };
+}
+
+function _decryptBuffer(envelope, key) {
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, Buffer.from(envelope.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+  return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, 'base64')), decipher.final()]);
+}
+
+/**
+ * Is `parsed` (an already-JSON.parsed value) an encryption envelope this
+ * module produced?
+ */
+export function isEncryptedEnvelope(parsed) {
+  return !!(parsed && typeof parsed === 'object' && parsed[ENCRYPTION_MARKER] === true);
+}
+
+/**
+ * The fail-closed gate. `artifactName` is matched against
+ * artifact-registry.js's `confidential` flag — an artifact not marked
+ * confidential is always {ok:true, content} unchanged, regardless of
+ * policy, so this function is a safe no-op to call for every write site
+ * without needing to duplicate the confidentiality check at each caller.
+ *
+ * @returns {{ok:true, content:string, encrypted:boolean} | {ok:false, reason:string}}
+ */
+export function maybeEncryptForWrite(scanRoot, artifactName, content) {
+  if (!confidentialOf(artifactName)) return { ok: true, content, encrypted: false };
+
+  const policy = loadEncryptionPolicy(scanRoot);
+  if (!policy || !policy.provider) {
+    if (policy && policy.required) {
+      return { ok: false, reason: `encryption is required for confidential artifact "${artifactName}" but no provider is configured (.agentic-security/${ENCRYPTION_POLICY_FILE})` };
+    }
+    return { ok: true, content, encrypted: false };
+  }
+
+  try {
+    const key = _readOrGenerateKey();
+    const envelope = _encryptBuffer(Buffer.from(content, 'utf8'), key);
+    return { ok: true, content: JSON.stringify({ [ENCRYPTION_MARKER]: true, provider: 'local-key', ...envelope }), encrypted: true };
+  } catch (e) {
+    if (policy.required) return { ok: false, reason: `encryption required but failed for "${artifactName}": ${e.message}` };
+    return { ok: true, content, encrypted: false };
+  }
+}
+
+/**
+ * Transparent decrypt-on-read: if `rawContent` parses as an envelope this
+ * module produced, decrypt and return the original plaintext string;
+ * otherwise return `rawContent` unchanged (a plaintext file, or a file
+ * from before encryption was ever configured). Never throws — a corrupt
+ * or undecryptable envelope degrades to returning the raw envelope JSON
+ * back (a caller expecting markdown/plaintext will visibly get neither,
+ * which is the correct, honest failure mode for a decrypt this module
+ * cannot perform, rather than silently returning empty content).
+ */
+export function maybeDecryptForRead(rawContent) {
+  let parsed;
+  try { parsed = JSON.parse(rawContent); } catch { return rawContent; }
+  if (!isEncryptedEnvelope(parsed)) return rawContent;
+  try {
+    const key = _readOrGenerateKey();
+    return _decryptBuffer(parsed, key).toString('utf8');
+  } catch { return rawContent; }
+}
+
+export const _internals = { _readOrGenerateKey, _encryptBuffer, _decryptBuffer, _keyPath };

package/src/posture/evidence-grade-wording.js

@@ -0,0 +1,71 @@
+// Canonical evidence-grade wording (assurance-hardening PRD FR-507).
+//
+// Every compliance-adjacent artifact this engine emits needs to disclaim
+// the same thing, and four of them had already drifted into hand-rolled,
+// SLIGHTLY WRONG phrasings before this module existed: compliance-policy.js
+// and auditor-walkthrough.js both said "A licensed assessor... is
+// responsible for the final attestation" — which conflates two DIFFERENT
+// things the PRD (and the standards this tooling maps to) treat as
+// distinct:
+//
+//   - An ATTESTATION is the ORGANIZATION'S OWN management formally
+//     asserting that stated controls are in place and operating (SOC 2's
+//     "management assertion" is the canonical example). This tool has no
+//     visibility into organizational process, personnel, or intent, so it
+//     cannot produce one.
+//   - A CERTIFICATION is a formal opinion or certificate issued by an
+//     ACCREDITED, INDEPENDENT third party (an ISO 27001 certification
+//     body, a SOC 2 auditor, a PCI DSS QSA) after their own examination.
+//     A "licensed assessor" produces a certification/independent
+//     assessment, not an attestation — the exact word swap the old
+//     wording got backwards.
+//
+// This tool produces neither. It produces the third, distinct tier:
+//
+//   - AUTOMATED TECHNICAL ASSESSMENT — deterministic, code-derived
+//     evidence for a bounded, disclosed set of controls. Real evidence,
+//     scoped honestly, but not a judgment about the organization.
+//
+// Naming all three, every time, is what FR-507 asks for ("UI and docs
+// distinguish automated technical assessment, management attestation, and
+// independent certification") — not just a generic "this isn't
+// certification" caveat, which is necessary but not sufficient: a reader
+// who has never heard the word "attestation" used correctly has no way to
+// know a real management attestation is a DIFFERENT, valid artifact they
+// might separately need.
+//
+// Every artifact quoting from here keeps the exact substring "does not
+// certify compliance" — several existing tests (world-class-batch2.test.js's
+// CMP-5 cases) already pin that phrase, and there's no reason to break a
+// correct, if incomplete, assertion while fixing the incompleteness.
+
+export const ASSURANCE_TIERS = Object.freeze({
+  automatedTechnicalAssessment:
+    'Automated technical assessment — what THIS TOOL produces: deterministic, ' +
+    'code-derived evidence for a bounded, disclosed set of controls.',
+  managementAttestation:
+    'Management attestation — the ORGANIZATION\'S OWN leadership formally ' +
+    'asserting that stated controls are in place and operating. This tool ' +
+    'cannot produce one; only the organization\'s management can.',
+  independentCertification:
+    'Independent certification — a formal opinion or certificate issued by an ' +
+    'ACCREDITED, INDEPENDENT third party (e.g. an ISO 27001 certification body, ' +
+    'a SOC 2 auditor, a PCI DSS QSA) after their own examination. This tool ' +
+    'cannot produce one; only an accredited independent party can.',
+});
+
+/** One-paragraph disclaimer for machine-consumed / GRC-ingested artifacts. */
+export const EVIDENCE_GRADE_DISCLAIMER =
+  'This artifact organizes automated technical assessment evidence produced by this scanner. ' +
+  'It does not certify compliance, and it is not a management attestation: only the ' +
+  'organization\'s own leadership can formally assert that stated controls are in place ' +
+  'and operating. It is also not an independent certification: only an accredited, ' +
+  'independent third party (an auditor, assessor, or certification body) examining the ' +
+  'organization directly can issue one.';
+
+/** Shorter inline variant for a markdown blockquote or narrow UI surface. */
+export const EVIDENCE_GRADE_DISCLAIMER_SHORT =
+  'This is automated technical assessment evidence — it does not certify compliance. ' +
+  'It is neither a management attestation (the organization\'s own sign-off) nor an ' +
+  'independent certification (an accredited third party\'s opinion); a licensed assessor ' +
+  'or the organization\'s management, not this tool, is responsible for either.';

package/src/posture/fix-history.js

@@ -13,6 +13,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { isSafeStateDir, statePath, stateWritesEnabled } from './state-dir.js';
+import { AGE_BASIS } from './provenance/schema.js';
 
 function historyDir(scanRoot) {
   return statePath(scanRoot, 'fix-history');
@@ -58,10 +59,6 @@ export function fixAcceptanceRate(scanRoot) {
   return acceptanceFromEntries(readLog(scanRoot));
 }
 
-function writeLog(scanRoot, log) {
-  ensure(scanRoot);
-  fs.writeFileSync(logPath(scanRoot), JSON.stringify(log, null, 2));
-}
 function sha(s) { return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16); }
 
 // Premortem 3R-12: cross-check helpers for last-scan.json. We look up
@@ -242,7 +239,36 @@ function _countPriorAttempts(log, stableId, findingId) {
   return n;
 }
 
-export async function applyFix({ scanRoot, file, originalContent, newContent, findingId, ruleId, vuln, stableId }) {
+// FR-PROV §7.4 / M2 §2.2: how old was this finding, by which basis, at the
+// moment it was fixed. Computed ONCE, at fix time, and never re-derived
+// later — a finding's origin doesn't change, but re-computing "age at fix"
+// from a LATER read of findingProvenance would silently answer "how old is
+// it now", not "how old was it when fixed". Mirrors mttr.js's ageBasis
+// tiering (Task 6) so the two surfaces agree on vocabulary.
+function _snapshotProvenanceAtFix(findingProvenance, appliedAt) {
+  if (!findingProvenance) return null;
+  const status = findingProvenance.status;
+  const origin = findingProvenance.findingOrigin;
+  const observedAt = findingProvenance.firstObserved?.observedAt || null;
+  let ageBasis, basisDate;
+  if (status === 'complete' && origin?.authorDate) { ageBasis = AGE_BASIS.FINDING_ORIGIN; basisDate = origin.authorDate; }
+  else if (status === 'partial' && origin?.authorDate) { ageBasis = AGE_BASIS.EARLIEST_OBSERVABLE; basisDate = origin.authorDate; }
+  else if (status === 'uncommitted') { ageBasis = AGE_BASIS.UNCOMMITTED; basisDate = observedAt; }
+  else { ageBasis = AGE_BASIS.FIRST_OBSERVED; basisDate = observedAt; }
+  const ageDays = basisDate ? Math.max(0, Math.floor((Date.parse(appliedAt) - Date.parse(basisDate)) / 86400000)) : null;
+  return { commit: origin?.commit || null, authorDate: basisDate, ageBasis, ageDays };
+}
+
+// @param {boolean} [fileExisted] - did `file` exist on disk before this call?
+//   Determines what "restore" means on rollback: write `originalContent`
+//   back for a file that existed (default, for backward compatibility with
+//   callers that don't pass it — safer to assume "existed" than to risk
+//   deleting a real file), or delete the file entirely for one that did not
+//   (a fix that created a NEW file, which is `originalContent: ''`'s only
+//   real-world meaning in this codebase's callers — writing '' back would
+//   leave a phantom empty file where none existed before, not a true
+//   rollback).
+export async function applyFix({ scanRoot, file, originalContent, newContent, findingId, ruleId, vuln, stableId, fileExisted = true, findingProvenance = null }) {
   return _withLogLock(scanRoot, async () => {
     ensure(scanRoot);
     const absFile = path.resolve(scanRoot, file);
@@ -260,8 +286,11 @@ export async function applyFix({ scanRoot, file, originalContent, newContent, fi
         MAX_ATTEMPTS_PER_KEY,
       );
     }
-    // Phase 1: backup + fsync.
-    await _writeAndSync(bakPath, originalContent);
+    // Phase 1: backup + fsync. Atomic for the same reason the target write
+    // is below — a corrupted backup is worse than no backup, because it
+    // silently defeats rollback.
+    await _writeAtomicAndSync(bakPath, originalContent);
+    const appliedAt = new Date().toISOString();
     const entry = {
       id,
       findingId,
@@ -269,22 +298,52 @@ export async function applyFix({ scanRoot, file, originalContent, newContent, fi
       ruleId: ruleId || null,
       vuln: vuln || null,
       file,
+      fileExisted,
       backupPath: path.relative(scanRoot, bakPath),
       originalSha: sha(originalContent),
       newSha: sha(newContent),
-      appliedAt: new Date().toISOString(),
+      appliedAt,
       status: 'pending',
       reverted: false,
       attemptOrdinal: priorAttempts + 1,
+      provenanceAtFix: _snapshotProvenanceAtFix(findingProvenance, appliedAt),
     };
     // Phase 2: log entry marked pending + fsync.
     const log = priorLog;
     log.push(entry);
     await _writeLogAndSync(scanRoot, log);
-    // Phase 3: write the new content to the target file + fsync.
+    // Phase 3: atomic write of the new content, then FR-306's post-write
+    // hash verification — read the file back and confirm it genuinely
+    // contains what was just written, not merely that the write call
+    // returned without throwing (a write can "succeed" against a
+    // corrupting filesystem, a truncated disk-full write that still exits
+    // 0, or a concurrent external modification landing between our write
+    // and the read-back proving it).
     try {
-      await _writeAndSync(absFile, newContent);
+      await _writeAtomicAndSync(absFile, newContent);
+      const writtenBack = await fsp.readFile(absFile, 'utf8');
+      if (sha(writtenBack) !== entry.newSha) {
+        throw new Error(`post-write hash verification failed for ${file}: on-disk content does not match what was written`);
+      }
     } catch (e) {
+      // FR-306: "injected write failure restores all files" — a failure at
+      // this point (the write itself, or the verification catching a
+      // corrupted write) must not leave the target in a partial or wrong
+      // state. Restore it now, synchronously with the failure, not as a
+      // later manual `recover()` step.
+      try {
+        if (fileExisted) {
+          await _writeAtomicAndSync(absFile, originalContent);
+        } else {
+          await fsp.unlink(absFile).catch(() => {}); // the failed write may not have landed at all
+        }
+        entry.rolledBack = true;
+      } catch (restoreErr) {
+        // Genuinely worse case (e.g. the filesystem itself is unwritable) —
+        // recorded honestly rather than silently claimed as rolled back.
+        entry.rolledBack = false;
+        entry.restoreError = restoreErr.message;
+      }
       entry.status = 'failed';
       entry.error = e.message;
       await _writeLogAndSync(scanRoot, log);
@@ -308,6 +367,33 @@ async function _writeAndSync(fp, content) {
   }
 }
 
+// FR-306: "atomic replacement". `_writeAndSync` above opens the TARGET path
+// directly in truncate mode — a crash or thrown error between the truncate
+// and the write completing leaves the file partially written, not atomically
+// replaced. This writes to a sibling temp file first, fsyncs it, then
+// renames it over the target — `rename()` is atomic on the same filesystem,
+// so the target is either the old content or the new content in full, never
+// a partial mix. The temp file is cleaned up on any failure before the
+// rename so a crash never leaves an orphaned `.tmp-*` file behind.
+async function _writeAtomicAndSync(fp, content) {
+  const dir = path.dirname(fp);
+  await fsp.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(fp)}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    const handle = await fsp.open(tmp, 'w');
+    try {
+      await handle.writeFile(content);
+      if (typeof handle.sync === 'function') await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fsp.rename(tmp, fp);
+  } catch (e) {
+    try { await fsp.unlink(tmp); } catch { /* never existed, or already gone — fine either way */ }
+    throw e;
+  }
+}
+
 async function _writeLogAndSync(scanRoot, log) {
   ensure(scanRoot);
   const fp = logPath(scanRoot);
@@ -369,22 +455,37 @@ async function _recoverInner(scanRoot) {
   return recovered;
 }
 
+// Shared revert primitive. `fileExisted === false` means the fix created a
+// file that did not exist beforehand — reverting deletes it rather than
+// writing the empty-string sentinel back, which would leave a phantom empty
+// file where none existed (see applyFix's `fileExisted` doc comment for why
+// that distinction matters). Entries logged before FR-306 have no
+// `fileExisted` field at all; `undefined !== false` so they fall through to
+// the pre-existing "write original content back" behavior, unchanged.
+async function _revertEntryInner(scanRoot, entry) {
+  const bak = path.resolve(scanRoot, entry.backupPath);
+  const absFile = path.resolve(scanRoot, entry.file);
+  if (!fs.existsSync(bak)) return { error: `backup missing: ${bak}` };
+  const original = await fsp.readFile(bak, 'utf8');
+  if (entry.fileExisted === false) {
+    await fsp.unlink(absFile).catch(() => {}); // may already be gone; deletion is the goal either way
+  } else {
+    await _writeAtomicAndSync(absFile, original);
+  }
+  entry.reverted = true;
+  entry.revertedAt = new Date().toISOString();
+  return entry;
+}
+
 // Revert the most recent un-reverted fix. Returns the entry or null.
 export async function undoLast(scanRoot) {
   return _withLogLock(scanRoot, async () => {
     const log = readLog(scanRoot);
     for (let i = log.length - 1; i >= 0; i--) {
       if (!log[i].reverted) {
-        const entry = log[i];
-        const bak = path.resolve(scanRoot, entry.backupPath);
-        const absFile = path.resolve(scanRoot, entry.file);
-        if (!fs.existsSync(bak)) return { error: `backup missing: ${bak}` };
-        const original = await fsp.readFile(bak, 'utf8');
-        await fsp.writeFile(absFile, original);
-        entry.reverted = true;
-        entry.revertedAt = new Date().toISOString();
-        writeLog(scanRoot, log);
-        return entry;
+        const result = await _revertEntryInner(scanRoot, log[i]);
+        if (!result.error) await _writeLogAndSync(scanRoot, log);
+        return result;
       }
     }
     return null;
@@ -399,6 +500,22 @@ export async function undoAll(scanRoot) {
   return reverted;
 }
 
+// FR-306: revert ONE specific entry by id, regardless of its position in the
+// log. The building block for same-batch rollback — a multi-file apply that
+// fails partway through must undo only the files THIS batch itself wrote,
+// not every unrelated pending entry `undoAll` would touch.
+export async function revertEntryById(scanRoot, entryId) {
+  return _withLogLock(scanRoot, async () => {
+    const log = readLog(scanRoot);
+    const entry = log.find(e => e.id === entryId);
+    if (!entry) return { error: `no such history entry: ${entryId}` };
+    if (entry.reverted) return entry;
+    const result = await _revertEntryInner(scanRoot, entry);
+    if (!result.error) await _writeLogAndSync(scanRoot, log);
+    return result;
+  });
+}
+
 export function listHistory(scanRoot) { return readLog(scanRoot); }
 
 // Premortem 3R-17: fix-history/log.json grows monotonically. A long-running

package/src/posture/fix-honesty-gate.js

@@ -141,23 +141,64 @@ export function computeFixTier(signals) {
 }
 
 /**
- * Compose the three gates for a single fix's output.
+ * FR-308: cross-check a fix-completeness TIER against MECHANICAL evidence,
+ * when any is available. `signals` (computeFixTier's input) is agent-
+ * self-reported — this module cannot compute sinkSignatureChanged /
+ * allCallersRouted / testDiscriminates itself (see the header above: "the
+ * gate can only run against claims the AGENT self-reports... nothing here
+ * is server-computable"). `pocLeg` is different: fix-verify.js's PoC leg is
+ * a REAL execution result (posture/CLAUDE.md's execution-proof tiers), not
+ * a claim. When it is available and shows the proof-of-concept STILL
+ * demonstrates the vulnerability against the patch, a self-reported FULL
+ * tier is not merely internally inconsistent — it is REFUTED by fact. This
+ * is the literal "a mitigation or workaround cannot be represented as a
+ * full fix" acceptance criterion, now backed by mechanical evidence where
+ * it exists rather than by self-report consistency alone.
  *
- * ok = residual-honesty ok AND evidence-citation ok, further constrained by the
- * tier/residual consistency invariant:
+ * A `pocLeg` of `not-requested` or `inconclusive` carries no mechanical
+ * signal either way and is a no-op here — this check can only ever ADD a
+ * violation on real contrary evidence, never manufacture one from absence.
+ *
+ * @param {string} tier
+ * @param {{status: string, reason?: string}|null} pocLeg
+ * @returns {{ ok: boolean, violations: string[] }}
+ */
+export function checkMechanicalTierEvidence(tier, pocLeg) {
+  if (!pocLeg || typeof pocLeg !== 'object') return { ok: true, violations: [] };
+  if (tier === 'FULL' && pocLeg.status === 'still-exploitable') {
+    return {
+      ok: false,
+      violations: [`tier 'FULL' is refuted by mechanical evidence: the proof-of-concept still demonstrates the vulnerability against the patch${pocLeg.reason ? ` (${pocLeg.reason})` : ''}`],
+    };
+  }
+  return { ok: true, violations: [] };
+}
+
+/**
+ * Compose the four gates for a single fix's output.
+ *
+ * ok = residual-honesty ok AND evidence-citation ok AND mechanical-tier-
+ * evidence ok, further constrained by the tier/residual consistency
+ * invariant:
  *   - a FULL tier must NOT carry a residual (a full fix has nothing left);
  *   - a non-FULL tier MUST document a residual (say what's still open).
  *
  * @param {{ residual?: string, verdict?: string, evidence?: any, signals?: object }} input
+ * @param {{ pocLeg?: object|null }} [mechanical] - FR-308: optional real
+ *   execution evidence (fix-verify.js's pocLeg) to cross-check the
+ *   self-reported tier against. Omitted entirely by any caller that has no
+ *   PoC leg to offer — this parameter never REQUIRES mechanical evidence,
+ *   it only USES it when present.
  * @returns {{ ok: boolean, tier: string, violations: string[] }}
  */
-export function gateFixOutput({ residual, verdict, evidence, signals } = {}) {
+export function gateFixOutput({ residual, verdict, evidence, signals } = {}, { pocLeg = null } = {}) {
   const tier = computeFixTier(signals);
   const residualCheck = checkResidualHonesty(residual);
   const evidenceCheck = requireCitedEvidence(verdict, evidence);
+  const mechanicalCheck = checkMechanicalTierEvidence(tier, pocLeg);
 
-  const violations = [...residualCheck.violations, ...evidenceCheck.violations];
-  let ok = residualCheck.ok && evidenceCheck.ok;
+  const violations = [...residualCheck.violations, ...evidenceCheck.violations, ...mechanicalCheck.violations];
+  let ok = residualCheck.ok && evidenceCheck.ok && mechanicalCheck.ok;
 
   const residualEmpty = typeof residual !== 'string' || residual.trim() === '';
   if (tier === 'FULL' && !residualEmpty) {