@clear-capabilities/agentic-security-scanner 0.142.0 → 0.144.0

package/src/llm-validator/index.js

@@ -65,7 +65,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { ensureStateDir, safeWriteState, statePath } from '../posture/state-dir.js';
-import { redactSecrets } from './redact.js';
+import { redactPayload } from '../egress/redact.js';
 import { signLastScan } from '../posture/integrity.js';
 
 // Bump on every prompt change so the cache invalidates. Exported as a
@@ -74,6 +74,9 @@ import { signLastScan } from '../posture/integrity.js';
 import { createCostLedger, parseCapUsd, renderCostCeiling } from './cost-ceiling.js';
 import { localEndpointConfig } from './local-endpoint.js';
 import { resolveProvider, buildProviderRequest, providerMatrix } from './providers.js';
+import { evaluateEgress } from '../egress/policy.js';
+import { recordEgressCall, payloadMetrics } from '../egress/audit.js';
+import { MODEL_STATUS, summarizeModelStatus } from './model-status.js';
 
 // The output cap we request. Shared with the cost estimate so the ceiling
 // charges exactly what we permit the model to produce.
@@ -295,7 +298,7 @@ export function sanitizeReasoning(s) {
     .slice(0, 280);
 }
 
-function renderPrompt(finding, fileContents, challenge, nonce) {
+function renderPrompt(finding, fileContents, challenge, nonce, scanRoot) {
   const code = fileContents?.[finding.file];
   let context = '';
   if (code && finding.line) {
@@ -315,12 +318,14 @@ function renderPrompt(finding, fileContents, challenge, nonce) {
   let sterileSnippet = String(finding.snippet || '')
     .replace(/[\r\n]+/g, ' ')
     .slice(0, 400);
-  // R10 — redact likely live credentials (API keys, tokens, private keys,
-  // connection-string passwords, ...) out of BOTH excerpts before anything
-  // leaves the machine. This is the last choke point before the prompt is
-  // assembled — everything downstream sees only redacted text.
-  sterileContext = redactSecrets(sterileContext).text;
-  sterileSnippet = redactSecrets(sterileSnippet).text;
+  // R10 / FR-603 — redact secrets (API keys, tokens, private keys,
+  // connection-string passwords), PII/PHI/PCI/FIN-shaped fields, operator-
+  // configured customer-data patterns, and whole-file content from an
+  // operator-configured proprietary path out of BOTH excerpts before
+  // anything leaves the machine. This is the last choke point before the
+  // prompt is assembled — everything downstream sees only redacted text.
+  sterileContext = redactPayload({ text: sterileContext, filePath: finding.file, scanRoot }).text;
+  sterileSnippet = redactPayload({ text: sterileSnippet, filePath: finding.file, scanRoot }).text;
   return PROMPT_TEMPLATE
     .replace(/\{\{nonce\}\}/g, nonce)
     .replace(/\{\{challenge\}\}/g, challenge)
@@ -440,8 +445,35 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
   if (!cfg) {
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
+    // FR-606: distinguish "the local preset refused a configured but
+    // non-loopback endpoint" (a policy decision) from "nothing was
+    // configured at all" (the tier is simply off) — endpointConfig()
+    // leaves _localPresetRefusal set only for the former.
+    finding.llmValidationStatus = _localPresetRefusal ? MODEL_STATUS.POLICY_BLOCKED : MODEL_STATUS.DISABLED;
     return { verdict: 'unvalidated' };
   }
+  // FR-601: egress policy evaluated before anything about this finding is
+  // rendered into a prompt (renderPrompt runs later, at line ~486) and before
+  // callEndpoint's fetch. A denial short-circuits here — no prompt is ever
+  // built for a denied endpoint, and the finding gets a distinct, honest
+  // error tag rather than being silently lumped in with "no answer received".
+  // FR-602: role/model are already resolved above (resolveProvider's own
+  // 'validate' role, cfg.model) — threading them through here is what
+  // makes the model/role constraint dimensions genuinely enforceable for a
+  // real caller, not just a mechanism nothing exercises.
+  const egressDecision = evaluateEgress({ scanRoot, purpose: 'llm-validator', endpoint: cfg.endpoint, role: 'validate', model: cfg.model });
+  if (!egressDecision.allowed) {
+    finding.validator_verdict = 'unvalidated';
+    finding.unvalidated = true;
+    finding._validatorError = 'egress-policy-denied';
+    finding._egressDecision = egressDecision;
+    finding.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
+    // FR-604: a denied call still gets an audit entry — purpose/provider/
+    // model/policy/outcome are all known without ever building a prompt,
+    // so byte/token/hash fields are simply absent (nothing was constructed).
+    recordEgressCall({ scanRoot, decision: egressDecision, ctx: { model: cfg.model, region: null } });
+    return { verdict: 'unvalidated', error: 'egress-policy-denied', egressDecision };
+  }
   // Pre-flight: refuse to validate location-less findings. Without a precise
   // file:line, the response cross-check degenerates and the validator can be
   // spoofed by trivially-true echoes.
@@ -479,11 +511,20 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     // against any future write-path regression that might cache un-sanitized text).
     finding.validator_reasoning = sanitizeReasoning(cached.reasoning);
     finding._validatorCache = 'hit';
+    // FR-606: a cache hit means the model DID answer at some point — not
+    // re-asking is an optimization, not a different outcome.
+    finding.llmValidationStatus = MODEL_STATUS.COMPLETED;
     return cached;
   }
   const challenge = crypto.randomBytes(8).toString('hex');
   const nonce     = crypto.randomBytes(8).toString('hex');
-  const prompt = renderPrompt(finding, fileContents, challenge, nonce);
+  const prompt = renderPrompt(finding, fileContents, challenge, nonce, scanRoot);
+  // FR-604: audit the allowed call now that the final (redacted) outbound
+  // payload is known — byte/token counts and a content hash, never the
+  // payload text itself. Recorded even if the call below fails or is
+  // blocked by the cost ceiling: the egress DECISION was 'allow' and a
+  // real payload was built, which is the fact this entry attests to.
+  recordEgressCall({ scanRoot, decision: egressDecision, ctx: { model: cfg.model, region: null }, metrics: payloadMetrics(prompt) });
 
   // R12 — the hard ceiling. Checked BEFORE the call, against a conservative
   // estimate: input from the prompt we are about to send, output at the full
@@ -503,6 +544,9 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
       finding.validator_verdict = 'unvalidated';
       finding.unvalidated = true;
       finding.validator_skipped_reason = afford.reason;
+      // FR-606: a cost ceiling is an operator-configured policy denying the
+      // call, the same bucket as an egress denial — not a network failure.
+      finding.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
       return { verdict: 'unvalidated', error: 'cost-ceiling' };
     }
   }
@@ -522,6 +566,11 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
     finding._validatorError = resp.error;
+    // FR-606: the call was attempted and failed before any usable response
+    // arrived (non-2xx HTTP, or a fetch/network exception in callEndpoint)
+    // — the endpoint is unavailable right now, distinct from a policy
+    // refusal or a malformed reply.
+    finding.llmValidationStatus = MODEL_STATUS.UNAVAILABLE;
     return { verdict: 'unvalidated', error: resp.error };
   }
   const obj = parseLastJsonObject(resp.text);
@@ -533,6 +582,11 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     finding._validatorError = `verify-failed:${v.reason}`;
     finding.llm_confidence = 0.5;
     finding.validator_reasoning = sanitizeReasoning(`escalate (verify-failed:${v.reason})`);
+    // FR-606: a response DID come back, but its content could not be
+    // parsed/verified into a usable answer — the model answered something,
+    // just not something usable. Distinct from UNAVAILABLE (no response at
+    // all) and from a real verdict.
+    finding.llmValidationStatus = MODEL_STATUS.MALFORMED;
     return { verdict: 'escalate', error: v.reason };
   }
   const parsed = v.parsed;
@@ -541,6 +595,7 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
   finding.llm_confidence = parsed.confidence;
   finding.validator_reasoning = parsed.reasoning;
   finding._validatorCache = 'miss';
+  finding.llmValidationStatus = MODEL_STATUS.COMPLETED;
   return parsed;
 }
 
@@ -563,12 +618,19 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
   const optOut = process.env.AGENTIC_SECURITY_LLM_VALIDATE === '0';
   const enabled = !!cfg && !optOut;
   if (!enabled) {
+    // FR-606: same distinction as validateOne's own !cfg branch — a
+    // configured-but-refused endpoint (local preset, non-loopback) is
+    // policy-blocked; nothing configured, OR an explicit operator opt-out
+    // (AGENTIC_SECURITY_LLM_VALIDATE=0), is the tier simply being off.
+    const status = _localPresetRefusal ? MODEL_STATUS.POLICY_BLOCKED : MODEL_STATUS.DISABLED;
     for (const f of findings) {
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
       if (_localPresetRefusal) f.validator_skipped_reason = _localPresetRefusal;
+      f.llmValidationStatus = status;
     }
     if (_localPresetRefusal) findings.localPathRefusal = _localPresetRefusal;
+    findings.llmValidatorStatus = summarizeModelStatus(findings);
     return findings;
   }
   const candidates = findings.filter(f =>
@@ -593,7 +655,11 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
       f.validator_skipped_reason = e.message;
+      // FR-606: a malformed operator config is a policy problem, same
+      // bucket as a valid-but-exceeded cost ceiling — not a network failure.
+      f.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
     }
+    findings.llmValidatorStatus = summarizeModelStatus(findings);
     return findings;
   }
 
@@ -606,6 +672,11 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
         // FAIL-CLOSED on exception too.
         candidates[idx].validator_verdict = 'escalate';
         candidates[idx]._validatorError = e.message;
+        // FR-606: an unexpected exception during validation (not a
+        // network-layer failure — those are already caught inside
+        // callEndpoint/validateOne) still means no usable answer was
+        // produced; closest of the five to what actually happened.
+        candidates[idx].llmValidationStatus = MODEL_STATUS.UNAVAILABLE;
       }
     }
   }
@@ -635,7 +706,13 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     if (f.validator_verdict) continue;
     f.validator_verdict = 'unvalidated';
     f.unvalidated = true;
+    // FR-606 defensive fallback: every real branch above already sets this;
+    // reaching here means a candidate was filtered out (not a model-tier
+    // pass at all) — DO NOT stamp llmValidationStatus for those, the same
+    // "not applicable" convention validateOne itself uses for SCA locators
+    // and no-precise-location findings.
   }
+  findings.llmValidatorStatus = summarizeModelStatus(findings);
   return findings;
 }
 

package/src/llm-validator/model-status.js

@@ -0,0 +1,66 @@
+// FR-606 (assurance-hardening PRD): the 5-state model-status vocabulary
+// reports must distinguish, so an LLM-backed feature never converts "the
+// model didn't answer" into an undifferentiated clean result.
+//
+// Before this module, every degrade path in llm-validator/index.js set the
+// SAME finding.validator_verdict ('unvalidated'), with the actual reason
+// scattered across an inconsistently-populated free-text field
+// (_validatorError: 'egress-policy-denied' | 'cost-ceiling' | 'HTTP 500' |
+// an arbitrary exception message | ...unset entirely for the "nothing
+// configured" case). A reader — human or downstream tool — had no reliable
+// way to answer "did the model tier even run, and if not, why" from that
+// shape alone.
+//
+// Attached to each finding llm-validator touches as
+// finding.llmValidationStatus, carrying EXACTLY one of the five values
+// below (never a sixth ad-hoc string), and aggregated into a scan-level
+// summary via summarizeModelStatus so a reader gets the headline without
+// inspecting every finding.
+//
+// Deliberately NOT stamped on findings the validator skips for reasons
+// that have nothing to do with MODEL availability (an SCA locator with no
+// line number, a finding with no precise file:line at all) — those already
+// have their own honest verdict ('not-applicable') and status; forcing
+// them into this taxonomy would misrepresent a finding-suitability
+// question as a model-availability one.
+
+export const MODEL_STATUS = Object.freeze({
+  // No endpoint resolved at all — no API key, no BYO endpoint, nothing
+  // configured. The tier is off, not broken; nothing was attempted.
+  DISABLED: 'model-disabled',
+  // Something WAS configured, but a policy refused to use it before any
+  // network call was attempted — the egress policy's mode:deny/local-only/
+  // provider allow-deny lists, the local preset's own loopback-only
+  // refusal, or an internal cost-ceiling cap.
+  POLICY_BLOCKED: 'policy-blocked',
+  // The call was attempted and failed before a usable response arrived —
+  // a network error, a timeout, or a non-2xx HTTP status.
+  UNAVAILABLE: 'unavailable',
+  // A response DID come back, but its content could not be parsed into a
+  // usable answer, or failed the challenge/nonce cross-check — the model
+  // answered something, just not something usable.
+  MALFORMED: 'malformed',
+  // A real, validated verdict was produced (including a cache hit of one
+  // produced earlier — the model answered at some point; not re-asking is
+  // an optimization, not a different outcome).
+  COMPLETED: 'completed',
+});
+
+const ALL_STATUSES = Object.values(MODEL_STATUS);
+
+/**
+ * Aggregate the per-finding llmValidationStatus values into scan-level
+ * counts. Findings with no llmValidationStatus at all (not applicable to
+ * model availability — see the module header) are counted separately and
+ * never silently folded into one of the five buckets.
+ */
+export function summarizeModelStatus(findings) {
+  const counts = Object.fromEntries(ALL_STATUSES.map(s => [s, 0]));
+  let notApplicable = 0;
+  for (const f of findings || []) {
+    const s = f?.llmValidationStatus;
+    if (s && Object.prototype.hasOwnProperty.call(counts, s)) counts[s]++;
+    else notApplicable++;
+  }
+  return { counts, notApplicable, total: (findings || []).length };
+}

package/src/mcp/tools.js

@@ -16,12 +16,16 @@ 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 { applyFix as applyFixHistory, fixAcceptanceRate } from '../posture/fix-history.js';
+import { applyFix as applyFixHistory, fixAcceptanceRate, revertEntryById as revertFixEntry } from '../posture/fix-history.js';
+import { applyVerifiedFix } from '../fix/apply-fix-service.js';
+import { classifyFixMaterialRisk } from '../posture/material-change.js';
+import { loadApproverRegistry, verifyApprover, requiredRolesFor, checkSeparationOfDuties } from '../fix/approver-registry.js';
 import { synthesizeDeterministicPatch } from '../posture/deterministic-fix.js';
 import { verifyLastScan } from '../posture/integrity.js';
+import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { analyzeTranscript, formatCacheReport, renderCacheStatusLine } from '../posture/cache-economics.js';
 import { redactString, redactFinding } from './redact.js';
-import { _remediationOf } from '../report/index.js';
+import { _remediationOf, normalizeFindings } from '../report/index.js';
 
 // Lazy-loaded: these transitively pull in npm packages (@babel/core and
 // friends) that aren't available in the plugin-cache install path
@@ -387,26 +391,44 @@ export const scan_diff = {
     // / MAX_TOTAL_SCAN_BYTES, so this does not turn scan_diff into a
     // full-project deep scan).
     const runScan = await getRunScan();
-    const result = await runScan(sessionRoot, { network: false, fileContents, deep: true, deepInCi: true });
+    // FR-704 (assurance-hardening PRD): this tool's own description promises
+    // "runs scan in memory" — without this, runFullScan's own state writers
+    // (dpia.md, ropa.md, privacy-framework.json, threat-model.json, and
+    // others) fire unconditionally on every call, silently mutating the
+    // user's real project on every pre-write self-correction scan. Confirmed
+    // by direct execution before this fix (11 state artifacts written by a
+    // single scan_diff-shaped call).
+    const result = await withStateWritesDisabled(() =>
+      runScan(sessionRoot, { network: false, fileContents, deep: true, deepInCi: true }));
     const wantSet = new Set(Object.keys(fileContents));
     const sevRank = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
     const min = sevRank[severity] ?? 0;
-    // Stage 6 correctness audit: this only ever read result.scan.findings
-    // (the SAST channel) — scan.secrets and scan.logicVulns are separate
-    // arrays on the raw runScan() result (report/index.js's normalizeFindings
-    // is what merges all four channels, and that merge hasn't run yet here).
-    // A file containing a bare hardcoded credential reported findingCount: 0
-    // through a tool whose own description promises "Use BEFORE writing a
-    // Write/Edit to disk so the agent can self-correct". Also reused
-    // _remediationOf so a fix-string detector (the majority of engine.js's
-    // own, ~127 call sites) doesn't silently report an empty `description`
-    // the way reading only `.remediation` did.
-    const findings = [...(result.scan.findings || []), ...(result.scan.secrets || []), ...(result.scan.logicVulns || [])]
+    // Stage 6 correctness audit (historical): this used to only read
+    // result.scan.findings (the SAST channel) — scan.secrets and
+    // scan.logicVulns are separate arrays on the raw runScan() result, and a
+    // hand-rolled 3-channel concat here was a second, divergent copy of the
+    // merge report/index.js's normalizeFindings() already does (four
+    // channels, plus per-channel defaulting and remediation-string
+    // resolution the old concat re-implemented separately and could drift
+    // from). Assurance-hardening PRD FR-105 ("JSON, SARIF, HTML, CSV, JUnit,
+    // and MCP outputs derive from the same validated object"): route through
+    // the same canonical merge every other output format uses.
+    //
+    // This closes the field-mapping/dedup divergence, but does NOT make
+    // scan_diff surface SCA/supply-chain findings end to end: this handler
+    // never builds a `depFileContents` map (everything a caller passes in
+    // `files`, manifests included, lands in `fileContents`), and manifest-
+    // based supply-chain detection in engine.js reads only `depFileContents`
+    // — so `result.scan.supplyChain` is always empty for this tool today
+    // regardless of this fix. That is a separate, real limitation (scan_diff
+    // was designed for pre-write code self-correction, not manifest
+    // scanning), left as-is rather than silently claimed fixed here.
+    const findings = normalizeFindings(result.scan)
       .filter(f => wantSet.has(String(f.file || '').replace(/\\/g, '/')) && (sevRank[f.severity] ?? 0) >= min)
       .map(f => redactFinding({
         id: f.id, severity: f.severity, file: f.file, line: f.line,
-        title: f.title || f.vuln, cwe: f.cwe,
-        description: f.description, remediation: _remediationOf(f),
+        title: f.vuln, cwe: f.cwe,
+        description: f.description, remediation: f.remediation,
       }));
     // Harness-anatomy #1: offload when the result exceeds OFFLOAD_THRESHOLD.
     // The agent gets a head+tail preview plus a path it can page through;
@@ -556,7 +578,7 @@ export const explain_finding = {
 // ─── apply_fix ───────────────────────────────────────────────────────────────
 export const apply_fix = {
   name: 'apply_fix',
-  description: 'Apply a fix for a finding. Two modes: (1) the stored fix.replacement, or (2) a caller-supplied `patch` (a files map) which is RE-VERIFIED inline (rescan-clean + no new ≥medium + lint) before any write — this unblocks findings that ship only a template or description. Refuses if last-scan.json fails its HMAC check, if the finding is shadow-marked, or if a path escapes the session root via lexical traversal OR a symlink. Requires confirm:true. Supports dry_run:true to preview without writing.',
+  description: 'Apply a fix for a finding. Two modes: (1) the stored fix.replacement, or (2) a caller-supplied `patch` (a files map) which is RE-VERIFIED inline (rescan-clean + no new ≥medium + lint) before any write — this unblocks findings that ship only a template or description. Refuses if last-scan.json fails its HMAC check, if the finding is shadow-marked, or if a path escapes the session root via lexical traversal OR a symlink. Requires confirm:true. Supports dry_run:true to preview without writing. On success, `verified:true` means verification passed but `verifiedFull:true` is the honest signal that every required leg (lint when configured, tests when a runner exists) genuinely ran — a false `verifiedFull` with `verified:true` means the pass is real but degraded (see `verify.degradedLegs`), not a full verification.',
   inputSchema: {
     type: 'object',
     additionalProperties: false,
@@ -597,6 +619,27 @@ export const apply_fix = {
               partialSanitization: { type: 'boolean' },
             },
           },
+          // FR-307/FR-1002: this schema had `additionalProperties: false`
+          // and never declared `approval` — the property apply-fix-
+          // service.js's high-impact-change gate has required since FR-307
+          // was built. A real MCP caller supplying fixMeta.approval was
+          // rejected by validate.js at the schema layer before the handler
+          // ever ran, silently making the approval gate (and FR-1002's
+          // identity check layered on it) unreachable from this tool's
+          // only real production entry point. See D-0024.
+          approval: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              approvedBy: { type: 'string', minLength: 1, maxLength: 200 },
+              reason: { type: 'string', minLength: 1, maxLength: 1000 },
+            },
+          },
+          // FR-1003: separation-of-duties. Self-reported the same way
+          // approvedBy is — this tool has no way to determine who actually
+          // wrote a patch, so `author` is a claim, checked against a
+          // configurable policy the same way `approval` is.
+          author: { type: 'string', minLength: 1, maxLength: 200 },
         },
       },
     },
@@ -671,20 +714,78 @@ export const apply_fix = {
           verify: { rescan: verdict.rescan, lint: { runner: verdict.lint?.runner, ok: verdict.lint?.ok }, honesty: verdict.honesty || null },
         };
       }
+      // FR-307/FR-1002/D-0024: this caller-supplied-patch branch writes via
+      // applyFixHistory() directly and never called applyVerifiedFix() — so
+      // the high-impact-change approval gate (auth/authZ/crypto/PII/schema/
+      // infra-privilege/public-API) built for the OTHER apply_fix branch
+      // (stored fix.replacement) never ran here at all, for any input. Since
+      // this is the branch the tool's own description calls the one that
+      // covers "~100% of findings that ship only a template," that gap was
+      // the larger of the two found this cycle. Same before/after content
+      // shape `apply-fix-service.js` already uses — read-first-in-try/catch
+      // (D-0012), never existsSync-then-readFileSync.
+      const filesForMaterialClassification = {};
+      for (const [rel, v] of Object.entries(confinedAbs)) {
+        let before = '';
+        try { before = await fsp.readFile(v.abs, 'utf8'); } catch { /* new file — before stays '' */ }
+        filesForMaterialClassification[rel] = { before, after: v.content };
+      }
+      const materialClassification = classifyFixMaterialRisk(filesForMaterialClassification);
       if (dry_run) {
-        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary };
+        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary, materialClassification };
+      }
+      if (materialClassification.highImpactCategories.length) {
+        const approval = fixMeta && typeof fixMeta === 'object' ? fixMeta.approval : null;
+        const hasApprovalEvidence = !!(approval && typeof approval === 'object' &&
+          typeof approval.approvedBy === 'string' && approval.approvedBy.trim().length > 0 &&
+          typeof approval.reason === 'string' && approval.reason.trim().length > 0);
+        if (!hasApprovalEvidence) {
+          return {
+            _meta: META, applied: false,
+            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) requires approval evidence — pass fixMeta.approval: {approvedBy, reason} — before it can be applied`,
+            materialClassification,
+          };
+        }
+        const approverRegistry = loadApproverRegistry(ctx.sessionRoot);
+        const requiredRoles = requiredRolesFor(approverRegistry, materialClassification.highImpactCategories);
+        const identityCheck = verifyApprover(approverRegistry, approval.approvedBy, requiredRoles);
+        if (!identityCheck.verified) {
+          return {
+            _meta: META, applied: false,
+            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) approval rejected: ${identityCheck.reason}`,
+            materialClassification,
+          };
+        }
+        // FR-1003: separation-of-duties, same no-op-unless-configured gate
+        // as apply-fix-service.js's own copy — see approver-registry.js.
+        const sodCheck = checkSeparationOfDuties(approverRegistry, fixMeta?.author, approval.approvedBy);
+        if (!sodCheck.ok) {
+          return {
+            _meta: META, applied: false,
+            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) approval rejected: ${sodCheck.reason}`,
+            materialClassification,
+          };
+        }
       }
       const written = [];
       try {
         for (const [rel, v] of Object.entries(confinedAbs)) {
-          const originalContent = fs.existsSync(v.abs) ? await fsp.readFile(v.abs, 'utf8') : '';
+          const fileExisted = fs.existsSync(v.abs);
+          const originalContent = fileExisted ? await fsp.readFile(v.abs, 'utf8') : '';
           const entry = await applyFixHistory({
-            scanRoot: ctx.sessionRoot, file: rel, originalContent, newContent: v.content,
+            scanRoot: ctx.sessionRoot, file: rel, originalContent, newContent: v.content, fileExisted,
             findingId: f.id, stableId: f.stableId, ruleId: f.ruleId || f.cwe || f.family || null, vuln: f.vuln || f.title || null,
           });
           written.push({ file: rel, historyId: entry.id, backupPath: entry.backupPath });
         }
       } catch (e) {
+        // FR-306: roll back every file THIS batch already wrote before the
+        // failure — applyFixHistory already restored the one file that just
+        // failed; this covers the rest, so a multi-file patch never leaves
+        // some files patched and others not.
+        for (const w of written) {
+          try { await revertFixEntry(ctx.sessionRoot, w.historyId); } catch { /* best-effort; original error still propagates below */ }
+        }
         if (e && e.name === 'FixAttemptBudgetExceededError') {
           return { _meta: META, applied: false, reason: `budget-exceeded: ${e.message}`, budgetExceeded: true, attempts: e.attempts, maxAttempts: e.max, key: e.key };
         }
@@ -692,7 +793,7 @@ export const apply_fix = {
       }
       let acceptance = null;
       try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* best-effort */ }
-      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary }, acceptance };
+      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary }, acceptance, materialClassification };
     }
 
     if (typeof f.fix?.replacement !== 'string') {
@@ -729,41 +830,47 @@ export const apply_fix = {
       };
     }
 
-    let entry;
-    try {
-      entry = await applyFixHistory({
-        scanRoot: ctx.sessionRoot,
-        file: f.file,
-        originalContent,
-        newContent: f.fix.replacement,
-        findingId: f.id,
-        stableId: f.stableId || null,   // premortem 4R-8
-        ruleId: f.ruleId || f.cwe || f.family || null,
-        vuln: f.vuln || f.title || null,
-      });
-    } catch (e) {
-      // Harness-engineering: step-budget refusal (post-derived). The
-      // deterministic layer enforces at-most-N attempts per stableId. When
-      // exceeded, surface it as a structured `budget-exceeded` outcome the
-      // agent can recognize — not a generic error.
-      if (e && e.name === 'FixAttemptBudgetExceededError') {
-        return {
-          _meta: META,
-          applied: false,
-          reason: `budget-exceeded: ${e.message}`,
-          budgetExceeded: true,
-          attempts: e.attempts,
-          maxAttempts: e.max,
-          key: e.key,
-        };
+    // FR-301/A-08 (assurance-hardening PRD): this branch used to write
+    // f.fix.replacement straight to disk with NO fresh verification — no
+    // rescan, no lint, nothing confirming the stored replacement actually
+    // closes the finding it claims to fix. The caller-patch branch above
+    // already required this; there is no reason a STORED fix should be
+    // trusted more than a caller-supplied one just because it shipped with
+    // the finding. Routed through the same applyVerifiedFix() service the
+    // CLI's `fix --apply` now also uses (src/fix/apply-fix-service.js) —
+    // confinement/reserved-path are re-checked there too (harmless
+    // redundancy with the dry_run preview above, kept for that preview's
+    // size-diff shape) but the load-bearing addition is the verification
+    // gate before the write.
+    if (!f.stableId) {
+      return { _meta: META, applied: false, reason: 'finding has no stableId — cannot verify a stored fix against it' };
+    }
+    const result = await applyVerifiedFix({
+      scanRoot: ctx.sessionRoot,
+      finding: f,
+      files: { [f.file]: f.fix.replacement },
+      fixMeta,
+    });
+    if (!result.ok) {
+      if (result.budgetExceeded) {
+        return { _meta: META, applied: false, reason: result.reason, budgetExceeded: true, attempts: result.attempts, maxAttempts: result.maxAttempts, key: result.key };
       }
-      throw e;
+      return { _meta: META, applied: false, reason: result.reason, verify: result.verify || null };
     }
     // R25 (PRD §5): surface the running auto-fix acceptance rate after each
     // applied fix, so the closed loop reports its own success metric.
     let acceptance = null;
     try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* metric is best-effort */ }
-    return { _meta: META, applied: true, historyId: entry.id, file: f.file, backupPath: entry.backupPath, integrity: status, attemptOrdinal: entry.attemptOrdinal, acceptance };
+    const entry = result.written[0];
+    return {
+      // FR-305: verifiedFull distinguishes "every required leg (lint, tests)
+      // genuinely ran and passed" from "passed, but a required leg was
+      // skipped or unavailable" — verified:true alone conflates them.
+      _meta: META, applied: true, verified: true, verifiedFull: result.verifiedFull,
+      historyId: entry.historyId, file: entry.file, backupPath: entry.backupPath,
+      integrity: status, attemptOrdinal: entry.attemptOrdinal, acceptance,
+      verify: result.verify,
+    };
   },
 };
 

package/src/pipeline/analyzer-supervisor.js

@@ -0,0 +1,93 @@
+// Real, preemptive deadline enforcement via worker_threads (assurance-
+// hardening PRD FR-202, D-0046 phase 1).
+//
+// FR-201's runDetector (detector-runner.js) catches a THROWN exception —
+// it does nothing for a detector that hangs (infinite loop, catastrophic
+// regex backtracking), because JavaScript is single-threaded: nothing
+// running in the same event loop as a synchronous hang can preempt it. The
+// existing _perFileTimeoutMs (engine.js) and AGENTIC_SECURITY_DEEP_TIMEOUT_MS
+// (dataflow/engine.js) are both COOPERATIVE — they measure elapsed time
+// after work already finished, or poll the clock between iterations of an
+// already-bounded loop. Neither can stop a genuinely hung synchronous call.
+//
+// runWithDeadline is the one piece that can: it races a worker_thread
+// against a real timer and calls worker.terminate() — an OS-level
+// preemptive kill — if the timer wins. This is phase 1 of D-0046's 4-phase
+// plan: a proven, isolated primitive, not yet wired into engine.js's real
+// scan loop (phase 3). See D-0046 for the full plan and why per-file
+// (not per-detector) granularity is the eventual wiring target.
+
+import { Worker } from 'node:worker_threads';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_WORKER_SCRIPT = path.join(HERE, 'analyzer-worker.js');
+
+// PRD FR-202: "the configured deadline plus a documented grace period."
+// The grace period exists so a worker that finishes essentially on time
+// (message already in flight) isn't killed by scheduler jitter.
+export const DEFAULT_GRACE_MS = 500;
+
+/**
+ * Run `exportName` from `modulePath`, called with `args`, inside a worker
+ * thread, with a real preemptive deadline.
+ *
+ * @param {object} spec
+ * @param {string} spec.modulePath - absolute path to the module to import inside the worker.
+ * @param {string} spec.exportName - the named export to call.
+ * @param {Array} [spec.args] - plain, structured-clone-safe arguments.
+ * @param {object} [opts]
+ * @param {number} opts.timeoutMs - required. The configured deadline.
+ * @param {number} [opts.graceMs] - documented grace period beyond timeoutMs before terminating. Default DEFAULT_GRACE_MS.
+ * @param {string} [opts.workerScript] - override for testing.
+ * @returns {Promise<{ok:true, result:*} | {ok:false, timedOut?:true, error?:string}>}
+ */
+export function runWithDeadline(spec, opts = {}) {
+  const { modulePath, exportName, args = [] } = spec || {};
+  const timeoutMs = opts.timeoutMs;
+  const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+  const workerScript = opts.workerScript || DEFAULT_WORKER_SCRIPT;
+
+  if (!modulePath || !exportName) {
+    return Promise.resolve({ ok: false, error: 'runWithDeadline requires spec.modulePath and spec.exportName' });
+  }
+  if (!(Number.isFinite(timeoutMs) && timeoutMs > 0)) {
+    return Promise.resolve({ ok: false, error: 'runWithDeadline requires opts.timeoutMs > 0' });
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const worker = new Worker(workerScript, { workerData: { modulePath, exportName, args } });
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killTimer);
+      worker.terminate().catch(() => {});
+      resolve(value);
+    };
+
+    // The one preemptive mechanism: a real OS-level Worker.terminate(),
+    // triggered by a real timer, not a cooperative clock-check inside the
+    // work itself. This is what makes this different from the existing
+    // _perFileTimeoutMs / deadlineMs mechanisms.
+    const killTimer = setTimeout(() => {
+      finish({ ok: false, timedOut: true, timeoutMs, graceMs });
+    }, timeoutMs + graceMs);
+    killTimer.unref?.();
+
+    worker.once('message', (msg) => {
+      if (msg && msg.ok) finish({ ok: true, result: msg.result });
+      else finish({ ok: false, error: (msg && msg.error) || 'unknown worker error' });
+    });
+
+    worker.once('error', (err) => {
+      finish({ ok: false, error: String((err && err.message) || err) });
+    });
+
+    worker.once('exit', (code) => {
+      finish({ ok: false, error: `worker exited with code ${code} before reporting a result` });
+    });
+  });
+}