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

package/src/mcp/tools.js

@@ -16,12 +16,20 @@ 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';
+// Git-origin provenance (Finding Provenance M0/M1). Distinct from
+// `finding.provenance` (AI-authorship) and from an SCA entry's `provenance`
+// (Sigstore/SLSA attestation) — see report/index.js's import comment.
+import { redactFindingProvenance } from '../posture/provenance/schema.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 +395,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;
@@ -549,6 +575,21 @@ export const explain_finding = {
       epssScore: typeof f.epssScore === 'number' ? f.epssScore : null,
       epssPercentile: typeof f.epssPercentile === 'number' ? f.epssPercentile : null,
       exploitedNow: !!f.exploitedNow,
+      // Which commit introduced this finding. `includeEmail` stays at its
+      // DEFAULT (false) unconditionally — unlike the JSON report there is no
+      // operator-set env escape for it here, because the consumer is an
+      // agent that has no business receiving a committer's email address.
+      // `pseudonymize`, by contrast, IS read back from the same env var
+      // report/index.js's `_normalizedProvenance` reads
+      // (AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS=1 / --pseudonymize-authors) —
+      // fix-round item 4: an operator who set that policy was still getting
+      // raw committer names (and, via providerEnrichment, raw reviewer
+      // logins/CODEOWNERS lines) through this MCP surface because this call
+      // passed no options object at all, silently defeating their policy at
+      // this one output boundary while report/index.js honoured it.
+      findingProvenance: f.findingProvenance ? redactFindingProvenance(f.findingProvenance, {
+        pseudonymize: process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1',
+      }) : null,
     };
   },
 };
@@ -556,7 +597,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 +638,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 +733,79 @@ 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,
+            findingProvenance: f.findingProvenance || 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 +813,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 +850,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` });
+    });
+  });
+}

package/src/pipeline/analyzer-worker.js

@@ -0,0 +1,26 @@
+// Worker-thread entry point for analyzer-supervisor.js (assurance-hardening
+// PRD FR-202, D-0046 phase 1).
+//
+// Generic by design: workerData names a module and an export to call with a
+// list of plain arguments, so this file has no knowledge of what analyzer it
+// is running. The supervisor is the only caller; this file is not meant to
+// be imported directly.
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+async function run() {
+  try {
+    const { modulePath, exportName, args } = workerData;
+    const mod = await import(modulePath);
+    const fn = mod[exportName];
+    if (typeof fn !== 'function') {
+      throw new Error(`export "${exportName}" is not a function in ${modulePath}`);
+    }
+    const result = await fn(...(args || []));
+    parentPort.postMessage({ ok: true, result });
+  } catch (e) {
+    parentPort.postMessage({ ok: false, error: String((e && e.message) || e) });
+  }
+}
+
+run();

package/src/pipeline/annotator-runner.js

@@ -0,0 +1,33 @@
+// Annotator runner (assurance-hardening PRD, Milestone 0/1, FR-106).
+//
+// Extracted from engine.js's local `_runAnnotator` closure so the Promise-
+// aware error-capture contract can be fault-injection tested directly,
+// without needing a real annotator to actually throw (this codebase's
+// annotators are deliberately built never to — see posture/CLAUDE.md's "no
+// throwing" convention — which is good for production but means there was
+// no natural way to prove the capture path works end-to-end before this
+// module existed). engine.js's `_runAnnotator` is now a thin wrapper that
+// closes over its local `_annotatorErrors` array and delegates here; this
+// module has no engine.js-specific state, so it takes the errors array as a
+// parameter instead of a closure.
+//
+// Contract: a rejection or thrown error from `fn()` — sync or async — is
+// captured as a structured entry, never left to become an unhandled
+// rejection or to race ahead of the caller. The caller MUST `await` this
+// function for the second half of that contract (capture-before-return) to
+// hold; see engine.js's call sites, all of which now do.
+
+/**
+ * @param {Array<{phase:string, err:string}>} annotatorErrors - mutated in place (push only)
+ * @param {string} phase - name recorded on a captured error
+ * @param {() => any} fn - sync or async callback
+ * @returns {Promise<any>} fn()'s resolved value, or undefined if it threw/rejected
+ */
+export async function runAnnotatorAsync(annotatorErrors, phase, fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    annotatorErrors.push({ phase, err: String((e && e.message) || e) });
+    return undefined;
+  }
+}

package/src/pipeline/assurance-mode.js

@@ -0,0 +1,154 @@
+// Assurance modes (assurance-hardening PRD FR-204).
+//
+// "Add assurance modes: advisory, standard, and strict | Strict mode fails
+// when a required analyzer fails, times out, is unavailable, or is
+// silently skipped." Section 12.1 names the CLI surface:
+// `--assurance advisory|standard|strict`.
+//
+// Built directly on FR-203's coverage ledger (pipeline/coverage-ledger.js)
+// and FR-206's scan-health.js -- this module adds no new signal collection
+// of its own, only a POLICY over signals that already exist. That is
+// deliberate: assurance modes decide how strict to be about incomplete
+// analysis; they must never be the thing that DEFINES what "incomplete"
+// means, or the two concepts would drift out of sync.
+//
+// THREE MODES:
+//   advisory — never fails the gate over scan health, regardless of what
+//     scanHealth reports. Purely informational (surfaced in scanHealth /
+//     toShipVerdict / `ci`'s stderr, per FR-206's fix -- this mode does not
+//     suppress that, it just does not ADD a build-failing consequence).
+//   standard (the DEFAULT, matching this codebase's behavior before and
+//     after FR-204) — same as advisory for gate purposes: an incomplete
+//     scan is surfaced, never silently hidden, but does not itself fail a
+//     build independent of the ordinary --fail-on severity threshold. The
+//     distinction from advisory is one of INTENT/reporting emphasis, not
+//     mechanism -- see the module-level note below on why this codebase
+//     does not invent a mechanical difference the PRD text does not ask
+//     for.
+//   strict — an incomplete scan (any analyzer failed, timed out, or was
+//     skipped by policy -- the ledger's own three non-"completed" outcomes)
+//     is a HARD FAILURE, independent of and IN ADDITION TO --fail-on,
+//     mirroring cmdCi's own existing precedent for its --policy gate
+//     ("Policy runs ALONGSIDE the --fail-on threshold; either gate can
+//     fail the build").
+//
+// WHY ADVISORY AND STANDARD ARE MECHANICALLY IDENTICAL HERE: the PRD's own
+// one-line acceptance criterion only specifies STRICT mode's behavior in
+// full ("fails when..."); it does not name a distinct mechanical
+// consequence for standard beyond "the default, not strict." Inventing an
+// intermediate failure condition neither named in the PRD nor requested
+// would be exactly the kind of unrequested scope-widening this codebase's
+// own conventions warn against. If a future requirement needs standard
+// mode to behave differently from advisory, that is a deliberate, separate
+// decision -- not something to guess at here.
+
+import { isProvenanceHealthy } from '../posture/provenance/schema.js';
+
+export const ASSURANCE_MODES = Object.freeze(['advisory', 'standard', 'strict']);
+export const DEFAULT_ASSURANCE_MODE = 'standard';
+
+function _isValidMode(mode) {
+  return ASSURANCE_MODES.includes(mode);
+}
+
+/**
+ * @param {string} mode - one of ASSURANCE_MODES; invalid/missing degrades to the default.
+ * @param {object|null} scanHealth - the engine's computed scan.scanHealth (FR-206).
+ * @returns {{ok: boolean, mode: string, reason: string|null, conditions: string[]}}
+ *   ok:false only ever happens in strict mode; advisory/standard always ok:true
+ *   (they report, they do not gate).
+ */
+export function evaluateAssuranceMode(mode, scanHealth, findings = []) {
+  const effectiveMode = _isValidMode(mode) ? mode : DEFAULT_ASSURANCE_MODE;
+  const conditions = Array.isArray(scanHealth?.conditions) ? scanHealth.conditions : [];
+
+  if (effectiveMode !== 'strict') {
+    return { ok: true, mode: effectiveMode, reason: null, conditions };
+  }
+
+  // Strict: any of the ledger's three non-"completed" analyzer outcomes,
+  // OR an annotator error / deep-mode failure (scanHealth's OTHER,
+  // non-analyzer conditions) -- "a required analyzer... is unavailable, or
+  // is silently skipped" covers more than just coverage-ledger.js's own
+  // per-detector accounting; a scan whose ANY known-good signal degraded
+  // is not "complete" under strict's own definition.
+  const status = scanHealth?.status;
+  if (!scanHealth || status !== 'complete') {
+    const a = scanHealth?.analyzers;
+    const parts = [];
+    if (a?.failed > 0) parts.push(`${a.failed} analyzer(s) failed`);
+    if (a?.timedOut > 0) parts.push(`${a.timedOut} analyzer(s) timed out`);
+    if (a?.skippedByPolicy > 0) parts.push(`${a.skippedByPolicy} analyzer(s) silently skipped by policy`);
+    const analyzerSummary = parts.length ? ` (${parts.join(', ')})` : '';
+    return {
+      ok: false,
+      mode: 'strict',
+      reason: `strict mode requires a fully complete scan; scanHealth.status is '${status ?? 'unknown'}'${analyzerSummary}`,
+      conditions,
+    };
+  }
+
+  // M2 §2.5: strict cares about overall scan completeness, which now
+  // explicitly includes PROVENANCE completeness, not just detector/analyzer
+  // completeness. A finding whose findingProvenance status is outside
+  // ['complete','uncommitted'] — including a finding with NO
+  // findingProvenance at all, e.g. --no-provenance was used — means strict
+  // cannot vouch for this scan's provenance the same way it already refuses
+  // to vouch for a scan with a failed analyzer.
+  //
+  // KNOWN INTERACTION: scan.secrets/scan.logicVulns are unconditionally
+  // stamped not_available today (M0+M1 deliberately deferred real origin
+  // resolution for those two channels — see the M2/M3/M4 design spec's
+  // §2.6). Any real secret or logic finding therefore fails strict mode
+  // until that resolution work lands. This is the literal, intended
+  // consequence of "never false certainty" applied to strict's own
+  // definition, not an oversight — a strict-mode operator with secrets
+  // findings should expect this until M3+ closes that gap.
+  //
+  // This list is INCOMPLETE without scan.supplyChain, and the omission
+  // matters more than the secrets/logic one above because it hits nearly
+  // every real project. engine.js stamps every supplyChain entry
+  // not_available too (see the loop over `supplyChain` right after the
+  // `annotateGitProvenance` calls), and that bucket covers three distinct
+  // populations, not one:
+  //
+  //  - transitive `vulnerable_dep` findings: a genuine, if currently
+  //    unresolved, DEFERRAL — same shape as secrets/logicVulns above. The
+  //    vulnerable version was never declared in this repo's own manifests,
+  //    so there is no local commit to walk yet, but one could exist to
+  //    resolve in a later phase.
+  //  - `unpinned_dep` / `no_lockfile` findings: a CATEGORY ERROR, not a
+  //    deferral. These describe an ABSENT state (a version range with no
+  //    pin, a manifest with no lockfile) — there is no "commit that
+  //    introduced a missing lockfile" for any future resolver to find,
+  //    because the finding is about the absence of an event, not an event
+  //    itself. No amount of future engineering work makes these resolvable.
+  //
+  // Direct `vulnerable_dep` findings DO go through real origin resolution
+  // (`resolveDirectSCAOrigin`, gated on `isDirect`) and are not part of this
+  // limitation.
+  //
+  // Net effect: because `unpinned_dep`/`no_lockfile` findings are a category
+  // error rather than a deferral, `--assurance strict` will fail on nearly
+  // any real project that has a `package.json` (or equivalent manifest)
+  // today — an unpinned or unlocked dependency is common, and this check has
+  // no way to ever resolve one. This is a known, disclosed limitation of the
+  // current implementation, not a bug, and it is not something this check
+  // should route around: exempting these finding types from the strict-mode
+  // gate was considered and deliberately deferred to a future milestone
+  // rather than done here, so strict mode keeps refusing to vouch for
+  // provenance it cannot actually speak to.
+  const badProvenance = (Array.isArray(findings) ? findings : []).filter((f) => !isProvenanceHealthy(f?.findingProvenance));
+  if (badProvenance.length > 0) {
+    return {
+      ok: false,
+      mode: 'strict',
+      reason: `strict mode requires complete finding provenance; ${badProvenance.length} finding(s) have status outside [complete, uncommitted]`,
+      conditions,
+    };
+  }
+
+  return { ok: true, mode: 'strict', reason: null, conditions };
+}
+
+export const _internals = { _isValidMode };