@blamejs/exceptd-skills 0.12.20 → 0.12.22

package/lib/playbook-runner.js

@@ -287,13 +287,137 @@ function lockFilePath(playbookId) {
   catch { return null; }
 }
 
+// PP P1-1: same-PID stale-lockfile reclaim threshold. A same-process orphan
+// (e.g. an earlier run() that crashed without unlinking, or a try/catch that
+// swallowed the release) older than this is presumed dead and reclaimed.
+// 30s mirrors lib/refresh-external.js and lib/prefetch.js; long enough that
+// no legitimate playbook hold reaches it (govern/look/run phases complete
+// well inside one second per playbook), short enough that a wedged process
+// recovers within one CI step rather than the rest of its lifetime.
+const STALE_LOCK_MS = 30_000;
+
 function acquireLock(playbookId) {
   const p = lockFilePath(playbookId);
   if (!p) return null;
+  const writePayload = () => fs.writeFileSync(
+    p,
+    JSON.stringify({ pid: process.pid, started_at: new Date().toISOString(), playbook: playbookId }, null, 2),
+    { flag: 'wx' }
+  );
   try {
-    fs.writeFileSync(p, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString(), playbook: playbookId }, null, 2), { flag: 'wx' });
+    writePayload();
     return p;
-  } catch { return null; /* already locked or unwritable */ }
+  } catch (e) {
+    // DD P1-3: stale-PID reclaim. Pre-fix the EEXIST path returned null
+    // and callers proceeded UNLOCKED — a process that crashed mid-run
+    // left its lockfile behind and every subsequent invocation silently
+    // ran without mutex protection. Mirror withCatalogLock's pattern:
+    // parse the recorded pid, probe with `process.kill(pid, 0)`. ESRCH
+    // means the holder is dead — unlink and retry once. EPERM (alive,
+    // different user) or any other condition: leave the lock alone and
+    // return null with a diagnostic so the caller knows acquisition
+    // failed because the lock is genuinely held (not because the FS is
+    // broken or the playbook id is malformed).
+    if (e && (e.code === 'EEXIST' || e.code === 'EPERM')) {
+      try {
+        const raw = fs.readFileSync(p, 'utf8');
+        let pid = null;
+        try { pid = JSON.parse(raw).pid; }
+        catch {
+          const n = Number.parseInt(String(raw).trim(), 10);
+          pid = Number.isInteger(n) && n > 0 ? n : null;
+        }
+        if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && !pidAlive(pid)) {
+          try { fs.unlinkSync(p); } catch {}
+          try { writePayload(); return p; } catch { /* fall through */ }
+        }
+        // PP P1-1: same-PID stale-lockfile reclaim. If the recorded pid is
+        // ours, the only way to escape an orphaned same-process lockfile is
+        // by mtime. Do NOT blindly reclaim same-PID — legitimate reentrancy
+        // (e.g. nested run() within one process) must still return null so
+        // the caller knows the lock is held. A fresh same-PID lockfile is
+        // reentrancy; one older than STALE_LOCK_MS is an orphan from a
+        // crashed prior hold (or a try/catch that swallowed the release)
+        // and must be reclaimed — otherwise the process can never acquire
+        // this lock again for the rest of its lifetime.
+        if (Number.isInteger(pid) && pid === process.pid) {
+          try {
+            const stat = fs.statSync(p);
+            if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+              try { fs.unlinkSync(p); } catch {}
+              try { writePayload(); return p; } catch { /* fall through */ }
+            }
+          } catch { /* stat failed — treat as held */ }
+        }
+      } catch { /* unreadable lockfile — treat as held by a live process */ }
+    }
+    // Lock genuinely held (or filesystem error). Returning null keeps
+    // back-compat with existing call sites that test `if (!lockPath)`.
+    // Callers that want a clearer diagnostic should call
+    // `acquireLockDiagnostic` instead.
+    return null;
+  }
+}
+
+// DD P1-3: callers needing to distinguish "couldn't acquire because the
+// lock is genuinely held by a live process" from "couldn't acquire
+// because of an unexpected error" can use this thin diagnostic wrapper.
+// Returns either { ok: true, path } or { ok: false, reason, lock_path?, holder_pid? }.
+// The bare `acquireLock` keeps its historical null-on-failure contract.
+function acquireLockDiagnostic(playbookId) {
+  const p = lockFilePath(playbookId);
+  if (!p) return { ok: false, reason: 'no_lock_path' };
+  try {
+    fs.writeFileSync(p,
+      JSON.stringify({ pid: process.pid, started_at: new Date().toISOString(), playbook: playbookId }, null, 2),
+      { flag: 'wx' });
+    return { ok: true, path: p };
+  } catch (e) {
+    if (e && (e.code === 'EEXIST' || e.code === 'EPERM')) {
+      let pid = null;
+      try {
+        const raw = fs.readFileSync(p, 'utf8');
+        try { pid = JSON.parse(raw).pid; }
+        catch {
+          const n = Number.parseInt(String(raw).trim(), 10);
+          pid = Number.isInteger(n) && n > 0 ? n : null;
+        }
+      } catch {}
+      if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && !pidAlive(pid)) {
+        try { fs.unlinkSync(p); } catch {}
+        try {
+          fs.writeFileSync(p,
+            JSON.stringify({ pid: process.pid, started_at: new Date().toISOString(), playbook: playbookId }, null, 2),
+            { flag: 'wx' });
+          return { ok: true, path: p, reclaimed_from_pid: pid };
+        } catch (e2) {
+          return { ok: false, reason: 'reclaim_failed', error: e2.message, lock_path: p, holder_pid: pid };
+        }
+      }
+      // PP P1-1: same-PID stale-lockfile reclaim (diagnostic variant). Same
+      // semantics as in acquireLock: a same-process lockfile older than
+      // STALE_LOCK_MS is an orphan and must be reclaimed; a fresher one is
+      // legitimate reentrancy and stays held.
+      if (Number.isInteger(pid) && pid === process.pid) {
+        let mtimeMs = null;
+        try { mtimeMs = fs.statSync(p).mtimeMs; } catch {}
+        if (mtimeMs !== null && (Date.now() - mtimeMs) > STALE_LOCK_MS) {
+          try { fs.unlinkSync(p); } catch {}
+          try {
+            fs.writeFileSync(p,
+              JSON.stringify({ pid: process.pid, started_at: new Date().toISOString(), playbook: playbookId }, null, 2),
+              { flag: 'wx' });
+            return { ok: true, path: p, reclaimed_self_stale_pid: true, prior_mtime_ms: mtimeMs };
+          } catch (e3) {
+            return { ok: false, reason: 'reclaim_failed', error: e3.message, lock_path: p, holder_pid: pid };
+          }
+        }
+        return { ok: false, reason: 'held_by_self', lock_path: p, holder_pid: pid };
+      }
+      return { ok: false, reason: 'held_by_live_pid', lock_path: p, holder_pid: pid };
+    }
+    return { ok: false, reason: 'fs_error', error: e && e.message, lock_path: p };
+  }
 }
 
 function releaseLock(lockPath) {
@@ -453,29 +577,52 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       // '<id>__fp_checks' in signal_overrides; default behavior (no
       // attestation) treats every required FP check as UNSATISFIED.
       if (verdict === 'hit' && Array.isArray(ind.false_positive_checks_required) && ind.false_positive_checks_required.length) {
-        const attestation = overrides[`${ind.id}__fp_checks`];
-        // S P1-A: arrays satisfy `typeof === 'object'` but are NOT a valid
-        // attestation map. A submission like
-        //   signal_overrides: { sig__fp_checks: [true, true] }
-        // would previously have its truthy entries matched via the index
-        // fallback (att['0'] === true), silently bypassing every FP-check
-        // requirement. Reject arrays explicitly so they fall through to the
-        // empty-attestation branch (every required check unsatisfied).
-        const safeAtt = Array.isArray(attestation) ? null : attestation;
-        const att = (safeAtt && typeof safeAtt === 'object') ? safeAtt : {};
-        const unsatisfied = ind.false_positive_checks_required.filter(fpName => {
-          // Match either by exact name string OR by indexed key '0', '1', ...
-          // because false_positive_checks_required entries are free-text
-          // strings, not ids. Operators may attest either by the literal
-          // string or by index. Default: unsatisfied.
-          if (att[fpName] === true) return false;
-          const idx = ind.false_positive_checks_required.indexOf(fpName);
-          if (idx !== -1 && att[String(idx)] === true) return false;
-          return true;
-        });
-        if (unsatisfied.length > 0) {
+        // BB P2-4: a hostile or buggy attestation may be a Proxy whose property
+        // accessors throw. The filter below reads `att[fpName]` for each
+        // required check; an exception inside the read would crash detect()
+        // and abort the entire run. Wrap the FP-check evaluation in a
+        // try/catch: on throw, treat ALL required checks as unsatisfied
+        // (safest default — never silently honor an attestation we couldn't
+        // read) and surface a runtime_error so the operator sees why.
+        try {
+          const attestation = overrides[`${ind.id}__fp_checks`];
+          // S P1-A: arrays satisfy `typeof === 'object'` but are NOT a valid
+          // attestation map. A submission like
+          //   signal_overrides: { sig__fp_checks: [true, true] }
+          // would previously have its truthy entries matched via the index
+          // fallback (att['0'] === true), silently bypassing every FP-check
+          // requirement. Reject arrays explicitly so they fall through to the
+          // empty-attestation branch (every required check unsatisfied).
+          const safeAtt = Array.isArray(attestation) ? null : attestation;
+          const att = (safeAtt && typeof safeAtt === 'object') ? safeAtt : {};
+          const unsatisfied = ind.false_positive_checks_required.filter(fpName => {
+            // Match either by exact name string OR by indexed key '0', '1', ...
+            // because false_positive_checks_required entries are free-text
+            // strings, not ids. Operators may attest either by the literal
+            // string or by index. Default: unsatisfied.
+            if (att[fpName] === true) return false;
+            const idx = ind.false_positive_checks_required.indexOf(fpName);
+            if (idx !== -1 && att[String(idx)] === true) return false;
+            return true;
+          });
+          if (unsatisfied.length > 0) {
+            verdict = 'inconclusive';
+            fpChecksUnsatisfied = unsatisfied;
+          }
+        } catch (e) {
+          // Treat every required check as unsatisfied — we couldn't trust the
+          // attestation map. Surface the throw so operators can chase the
+          // root cause (Proxy with a throwing getter, frozen object that
+          // tripped invariants, etc.).
           verdict = 'inconclusive';
-          fpChecksUnsatisfied = unsatisfied;
+          fpChecksUnsatisfied = ind.false_positive_checks_required.slice();
+          if (runOpts && Array.isArray(runOpts._runErrors)) {
+            runOpts._runErrors.push({
+              kind: 'fp_attestation_threw',
+              indicator_id: ind.id,
+              message: (e && e.message) ? String(e.message) : String(e),
+            });
+          }
         }
       }
     } else {
@@ -515,33 +662,57 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // full false_positive_profile checks and reached an explicit verdict —
   // engine-computed classification can't represent "I saw the indicators and
   // confirmed they're all benign" without this override.
-  const override = (agentSubmission.signals && agentSubmission.signals.detection_classification);
+  const rawOverride = (agentSubmission.signals && agentSubmission.signals.detection_classification);
   const validOverrides = new Set(['detected', 'inconclusive', 'not_detected', 'clean']);
-
-  // S P1-B: block a `detected` agent override when any indicator was
-  // downgraded to inconclusive because its false_positive_checks_required[]
-  // entries were not attested. Without this gate, an agent that submits
-  // `signals.detection_classification: 'detected'` can force the run-level
-  // classification past FP checks the engine just refused to honor — exactly
-  // the contract Hard Rule #6 (compliance theater) forbids. Substitute
-  // 'inconclusive' and surface a runtime_error so the operator sees the
-  // override was refused (not silently ignored).
+  // BB P2-1: any override that's a non-empty string but NOT in the allowlist
+  // (e.g. 'present', 'unknown', '', '  detected  ', 'Detected') must surface
+  // as a runtime_error rather than silently falling through to engine-computed
+  // classification. Operators submitting case variants / whitespace-padded
+  // strings deserve a clear diagnostic, not a quiet downgrade. Treat the
+  // override as absent for classification purposes once recorded.
+  const overrideIsString = typeof rawOverride === 'string';
+  const overrideIsInAllowlist = overrideIsString && validOverrides.has(rawOverride);
+  if (rawOverride !== undefined && rawOverride !== null && !overrideIsInAllowlist) {
+    if (runOpts && Array.isArray(runOpts._runErrors)) {
+      runOpts._runErrors.push({
+        kind: 'classification_override_invalid',
+        supplied: rawOverride,
+        allowed: ['detected', 'inconclusive', 'not_detected', 'clean'],
+        reason: 'signals.detection_classification must be one of the allowlist values exactly (case-sensitive, no surrounding whitespace). Override ignored; engine-computed classification used.',
+      });
+    }
+  }
+  const override = overrideIsInAllowlist ? rawOverride : undefined;
+
+  // BB P1-1 / BB P1-2: extend the v0.12.19 S P1-B gate to refuse ALL
+  // classification overrides (`detected`, `clean`, `not_detected`) when any
+  // indicator was FP-downgraded. A submission that maps to `'not_detected'`
+  // (either by literal `not_detected` OR by `'clean'`, which v0.12.19 mapped
+  // to `'not_detected'` at this site) MUST NOT hide a `verdict: 'hit'`
+  // indicator whose `false_positive_checks_required[]` were unattested —
+  // that's a strictly worse false-negative outcome than allowing 'detected'
+  // through. Substitute 'inconclusive' and emit a runtime_error.
+  // BB P2-2: record indicator IDs and an unsatisfied-checks count ONLY —
+  // never the literal FP-check check-name strings (those are an attestation-
+  // bypass hint for a hostile agent reading the runtime_errors).
   const anyFpDowngrade = indicatorResults.some(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0);
 
   let classification;
-  if (override && validOverrides.has(override)) {
+  if (override) {
     classification = override === 'clean' ? 'not_detected' : override;
-    if (classification === 'detected' && anyFpDowngrade) {
-      classification = 'inconclusive';
+    if (anyFpDowngrade) {
+      const substituted = 'inconclusive';
+      const attempted = override; // record what the operator submitted, not the mapped form
+      classification = substituted;
       if (runOpts && Array.isArray(runOpts._runErrors)) {
         runOpts._runErrors.push({
           kind: 'classification_override_blocked',
-          attempted: 'detected',
-          substituted: 'inconclusive',
-          reason: 'FP-check downgrade: one or more indicators downgraded to inconclusive because false_positive_checks_required entries were not attested. Agent override to `detected` refused.',
+          attempted,
+          substituted,
+          reason: 'FP-check downgrade: one or more indicators downgraded to inconclusive because false_positive_checks_required entries were not attested. Agent classification override refused.',
           indicators_with_unsatisfied_fp_checks: indicatorResults
             .filter(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0)
-            .map(r => ({ id: r.id, fp_checks_unsatisfied: r.fp_checks_unsatisfied })),
+            .map(r => ({ id: r.id, fp_checks_unsatisfied_count: r.fp_checks_unsatisfied.length })),
         });
       }
     }
@@ -580,7 +751,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       from_observation: agentSubmission._signal_origins?.[i.id] || null,
     })),
     indicators_evaluated_count: indicatorResults.length,
-    classification_override_applied: validOverrides.has(override) ? (override === 'clean' ? 'not_detected' : override) : null,
+    classification_override_applied: override ? (override === 'clean' ? 'not_detected' : override) : null,
     submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty'),
     // E9: pass through any flat-shape observation collisions detected at
     // normalize time so analyze() can publish them under
@@ -871,7 +1042,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   }
   // F5: use the first evidence-correlated CVE as the canonical attribute
   // source for factor scaling. If matchedCves is empty there's no per-CVE
-  // evidence to gate on. v0.12.15 (audit N F1): the prior fallback was
+  // evidence to gate on. v0.12.15: the prior fallback was
   // `factorCve = null` → every factor returned 0 → catalog-shape playbooks
   // (secrets, library-author, crypto-codebase, framework, cred-stores,
   // containers, runtime, crypto, ai-api) that detect WITHOUT a per-CVE
@@ -898,7 +1069,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     null);
     if (factorCve) factorCveSource = 'domain';
   }
-  // v0.12.15 (audit N F1): five shipped playbooks (secrets, library-author,
+  // v0.12.15: five shipped playbooks (secrets, library-author,
   // crypto-codebase, framework, cred-stores, containers, runtime, crypto,
   // ai-api) ship with empty `domain.cve_refs` because their attack class is
   // class-of-vulnerability rather than CVE-specific. For those playbooks
@@ -1393,7 +1564,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   const extraFormats = Array.isArray(agentSignals._bundle_formats)
     ? agentSignals._bundle_formats.filter(f => f !== primaryFormat)
     : [];
-  // audit W P2-B: build every bundle once and reuse, so bundle_body and
+  // B: build every bundle once and reuse, so bundle_body and
   // bundles_by_format[primary] are the same object identity (and hence
   // identical on every nested timestamp). Pre-fix, buildEvidenceBundle was
   // invoked twice for the primary format and each invocation crystallised
@@ -1405,14 +1576,20 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const builtFormats = new Map();
     const buildOnce = (format) => {
       if (!builtFormats.has(format)) {
-        builtFormats.set(format, buildEvidenceBundle(format, playbook, analyzeResult, validateResult, agentSignals, sessionId, issuedAt));
+        builtFormats.set(format, buildEvidenceBundle(format, playbook, analyzeResult, validateResult, agentSignals, sessionId, issuedAt, runOpts));
       }
       return builtFormats.get(format);
     };
     const primaryBody = buildOnce(primaryFormat);
-    const byFormat = extraFormats.length
-      ? Object.fromEntries([primaryFormat, ...extraFormats].map(f => [f, buildOnce(f)]))
-      : null;
+    // bundles_by_format must always be an object keyed by the
+    // primary format, even when no extra formats were requested. Pre-fix it
+    // was null in the single-format case, forcing downstream tooling into a
+    // `bundles_by_format ?? { [primaryFormat]: bundle_body }` shim in every
+    // consumer. Now the field is canonically present so iteration is
+    // uniform across single- and multi-format emissions.
+    const byFormat = Object.fromEntries(
+      [primaryFormat, ...extraFormats].map(f => [f, buildOnce(f)])
+    );
     return {
       bundle_format: primaryFormat,
       contents: c.evidence_package.contents || [],
@@ -1592,7 +1769,7 @@ function buildProductBinding(playbook, sessionId) {
 // surface at least one candidate when any is known. Returns null when no
 // candidate exists — caller MUST omit `locations` rather than emit empty.
 //
-// audit W P2-A: source segments are heterogeneous — many playbook artifacts
+// A: source segments are heterogeneous — many playbook artifacts
 // describe a shell-command capture (`uname -r`) or human prose, not a real
 // file or URI. SARIF `artifactLocation.uri` is defined as a URI reference
 // (RFC 3986); shell-command text + prose breaks downstream consumers
@@ -1634,10 +1811,67 @@ function sarifLocationsForIndicator(playbook, indicator) {
   return [{ physicalLocation: { artifactLocation: { uri: candidates[0] } } }];
 }
 
-function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals, sessionId, issuedAt) {
+// Resolve the package version once per process so CSAF tracking.generator
+// can name the engine that emitted the advisory. Best-effort read — bundle
+// emission must not crash if package.json is missing (e.g. exotic install).
+let _CACHED_PKG_VERSION = null;
+function getEngineVersion() {
+  if (_CACHED_PKG_VERSION != null) return _CACHED_PKG_VERSION;
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    _CACHED_PKG_VERSION = (pkg && typeof pkg.version === 'string') ? pkg.version : 'unknown';
+  } catch {
+    _CACHED_PKG_VERSION = 'unknown';
+  }
+  return _CACHED_PKG_VERSION;
+}
+
+// 3 / P1-4: operator-supplied identity strings (--operator) and
+// publisher namespace URLs (--publisher-namespace) flow into operator-facing
+// CSAF surfaces. Strip ASCII control characters as a defence-in-depth pass —
+// bin/exceptd.js already validates the inputs, but the runner is also called
+// from library consumers that may bypass the CLI surface.
+//
+// MM P1-D: extend the strip to Unicode bidi / format / control / surrogate /
+// private-use / unassigned categories (\p{C} under the `u` regex flag) so
+// direct library callers of buildEvidenceBundle cannot smuggle a U+202E
+// "RTL OVERRIDE" or zero-width joiner past the sanitiser the way the CLI
+// already refuses (--operator validation in bin/exceptd.js). NFC-normalise
+// first so a decomposed sequence can't combine past the codepoint check;
+// cap the result at 256 codepoints (NOT UTF-16 code units) so a string of
+// astral-plane codepoints can't smuggle a longer-than-256-display string
+// past the cap by exploiting JavaScript's surrogate-pair string length.
+// Returns null on rejection (empty after strip, or NFC normalise threw);
+// callers (the publisher-namespace + contact_details + tracking.generator
+// sites) treat null as "operator-unclaimed" and route through the existing
+// fallback (publisher.namespace = urn:exceptd:operator:unknown +
+// bundle_publisher_unclaimed runtime warning).
+function sanitizeOperatorText(s) {
+  if (typeof s !== 'string') return null;
+  // NFC first: a Cf codepoint may be expressed as a base + combining mark
+  // that recomposes into the format category under NFC. Normalise so the
+  // strip catches it.
+  let normalised;
+  try { normalised = s.normalize('NFC'); }
+  catch { return null; }
+  // Strip every Unicode codepoint matching General Category C
+  // (Cc, Cf, Cs, Co, Cn). \p{C} under the `u` flag matches all five.
+  const stripped = normalised.replace(/\p{C}/gu, '');
+  const trimmed = stripped.trim();
+  if (trimmed.length === 0) return null;
+  // Cap at 256 codepoints (Array.from counts codepoints, not UTF-16 code
+  // units, so a 256-codepoint astral-plane string isn't silently extended
+  // past the cap by surrogate-pair encoding).
+  const cps = Array.from(trimmed);
+  if (cps.length <= 256) return cps.join('');
+  return cps.slice(0, 256).join('');
+}
+
+function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals, sessionId, issuedAt, runOpts) {
+  runOpts = runOpts || {};
   const playbookSlug = urnSlug(playbook._meta.id);
   const { productId, productPurl, productName } = buildProductBinding(playbook, sessionId);
-  // audit W P2-B: pin one `now` value per bundle build (and accept an
+  // B: pin one `now` value per bundle build (and accept an
   // upstream-provided issuedAt) so multi-format emit produces identical
   // tracking timestamps across CSAF / OpenVEX / SARIF when close() is
   // building several formats from the same run. Without the parameter,
@@ -1661,7 +1895,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       name: productName,
       product_identification_helper: { purl: productPurl }
     }];
-    // audit W P1-A: `fixed` product_status MUST reflect operator-supplied VEX
+    // A: `fixed` product_status MUST reflect operator-supplied VEX
     // disposition (vex_status === 'fixed' — see analyze() F17), not the
     // catalog's global `live_patch_available` flag. The catalog flag means
     // "vendor publishes a live-patch in the world", not "operator deployed
@@ -1671,6 +1905,60 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     // that lied to downstream NVD / Red Hat dashboards. When
     // live_patch_available is the only signal, status stays known_affected
     // and the live-patch route is surfaced as a `vendor_fix` remediation.
+    // CSAF §3.2.1.2 restricts the `cve` field to the CVE-id
+    // regex `^CVE-[0-9]{4}-[0-9]{4,}$`. The catalog also keys non-CVE
+    // identifiers off `cve_id` (MAL-2026-3083, GHSA-…, OSV-…); strict
+    // validators (BSI CSAF validator, ENISA dashboard) refuse documents that
+    // place non-CVE values in `cve`. Branch by prefix and route non-CVE ids
+    // to the `ids[]` array with a real `system_name`.
+    //
+    // CSAF §3.2.1.5 requires `cvss_v3.vectorString` when a
+    // cvss_v3 score block is emitted. Drop the entire score block when the
+    // catalog has no CVSS data (score AND vector both unset); otherwise
+    // include version + baseScore + vectorString + baseSeverity from the
+    // catalog entry.
+    const csafCvssSeverity = (score) => {
+      if (typeof score !== 'number') return null;
+      if (score >= 9.0) return 'CRITICAL';
+      if (score >= 7.0) return 'HIGH';
+      if (score >= 4.0) return 'MEDIUM';
+      if (score > 0.0)  return 'LOW';
+      return 'NONE';
+    };
+    const csafCvssVersionFromVector = (vec) => {
+      if (typeof vec !== 'string') return '3.1';
+      const m = vec.match(/^CVSS:(\d+\.\d+)\//);
+      if (!m) return '3.1';
+      // Returns the declared version verbatim. The CALLER is responsible for
+      // gating cvss_v3 emission to 3.0 / 3.1 per CSAF 2.0 schema. 2.0 and
+      // 4.0 vectors are tagged here for diagnostic clarity but never reach
+      // the cvss_v3 block downstream.
+      return m[1];
+    };
+    const csafIdsFor = (id) => {
+      // B: null / undefined / non-string id MUST NOT emit literal
+      // "null" / "undefined" text into the vulnerabilities[] entry. Pre-fix
+      // String(id) coerced both to those literals — strict validators then
+      // rejected the document, and operators saw a phantom "null" CVE in
+      // dashboards. Return null so the caller can skip the entry entirely
+      // and surface a runtime_error for the missing id.
+      if (typeof id !== 'string' || !id) return null;
+      if (id.startsWith('GHSA-'))    return { system_name: 'GHSA', text: id };
+      if (id.startsWith('MAL-'))     return { system_name: 'Malicious-Package', text: id };
+      if (id.startsWith('OSV-'))     return { system_name: 'OSV', text: id };
+      if (id.startsWith('SNYK-'))    return { system_name: 'Snyk', text: id };
+      // A: RUSTSEC advisories carry their own tracking authority
+      // (https://rustsec.org); mis-routing them to system_name 'OSV' loses
+      // the upstream provenance link and confuses downstream ingesters that
+      // resolve by (system_name, text) pair.
+      if (id.startsWith('RUSTSEC-')) return { system_name: 'RUSTSEC', text: id };
+      // B: genuinely-unknown prefix surfaces as `exceptd-unknown`
+      // so downstream ingesters know the authority wasn't recognized — pre-fix
+      // every unknown id was misattributed to OSV.
+      return { system_name: 'exceptd-unknown', text: id };
+    };
+    const CSAF_CVE_RE = /^CVE-\d{4}-\d{4,}$/;
+
     const cveVulns = analyze.matched_cves.map(c => {
       const isFixed = c.vex_status === 'fixed';
       const remediations = [{
@@ -1679,21 +1967,87 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           || (c.live_patch_available ? 'Vendor publishes a live-patch — see CVE catalog `live_patch_tools` for the operator-side step.' : 'See selected remediation path.'),
         product_ids: [productId],
       }];
-      return {
-        cve: c.cve_id,
-        scores: [{ products: [productId], cvss_v3: { base_score: c.cvss_score || 0 } }],
+      // B: catalog entries with a missing / non-string cve_id
+      // pre-fix produced literal `text: "null"` / `text: "undefined"` entries
+      // under ids[]. Skip the vulnerability entry entirely and surface a
+      // runtime_error so the catalog gap is visible to operators / CI gates.
+      const idIsCve = typeof c.cve_id === 'string' && CSAF_CVE_RE.test(c.cve_id);
+      let idEntry = null;
+      if (!idIsCve) {
+        idEntry = csafIdsFor(c.cve_id);
+        if (idEntry == null) {
+          if (Array.isArray(runOpts._runErrors)) {
+            const alreadyMissing = runOpts._runErrors.some(e => e && e.kind === 'bundle_cve_id_missing');
+            if (!alreadyMissing) {
+              runOpts._runErrors.push({
+                kind: 'bundle_cve_id_missing',
+                reason: 'A matched_cves[] entry has no string cve_id (null / undefined / non-string). The CSAF vulnerability entry was omitted to avoid emitting literal "null" / "undefined" text under vulnerabilities[].ids[].',
+                remediation: 'Inspect the CVE catalog feed that produced this match; the upstream record is missing its identifier and should be refreshed or excluded.'
+              });
+            }
+          }
+          return null;
+        }
+      }
+      // only emit cvss_v3 score block when we have a real
+      // vector string AND a numeric score. Pre-fix every vuln carried
+      // `cvss_v3: { base_score: 0 }` even when the catalog had no CVSS
+      // signal — strict validators reject the truncated block, and
+      // `base_score: 0` was a downstream-misleading default that suggested
+      // an authoritative "informational" score where there was simply no
+      // data.
+      //
+      // C: CSAF 2.0 `cvss_v3` ONLY accepts version 3.0 / 3.1.
+      // Catalog vectors prefixed CVSS:2.0/ or CVSS:4.0/ would pre-fix emit a
+      // cvss_v3 block with version: '2.0' / '4.0', which strict validators
+      // (BSI CSAF Validator) reject outright. Drop the block for non-3.x
+      // vectors and surface a runtime_error so operators can see why their
+      // CVSS data didn't make it through.
+      const hasCvss = typeof c.cvss_score === 'number' && typeof c.cvss_vector === 'string' && c.cvss_vector.length > 0;
+      const vectorVersion = hasCvss ? csafCvssVersionFromVector(c.cvss_vector) : null;
+      const cvssV3Eligible = hasCvss && (vectorVersion === '3.0' || vectorVersion === '3.1');
+      if (hasCvss && !cvssV3Eligible && Array.isArray(runOpts._runErrors)) {
+        const alreadyUnsup = runOpts._runErrors.some(e => e && e.kind === 'bundle_cvss_v3_version_unsupported');
+        if (!alreadyUnsup) {
+          runOpts._runErrors.push({
+            kind: 'bundle_cvss_v3_version_unsupported',
+            reason: `Catalog entry carries CVSS vector with version ${vectorVersion}; CSAF 2.0 cvss_v3 block only accepts versions 3.0 / 3.1. The score block was omitted from this vulnerability to keep the document valid against strict CSAF validators.`,
+            remediation: 'Backfill a CVSS 3.1 vector against this CVE in the catalog, or wait for CSAF 2.1 (cvss_v4 support) — exceptd targets CSAF 2.0 today.'
+          });
+        }
+      }
+      const scores = cvssV3Eligible ? [{
+        products: [productId],
+        cvss_v3: {
+          version: vectorVersion,
+          baseScore: c.cvss_score,
+          vectorString: c.cvss_vector,
+          baseSeverity: csafCvssSeverity(c.cvss_score),
+        }
+      }] : [];
+      const base = {
+        scores,
         threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
         remediations,
         product_status: isFixed ? { fixed: [productId] } : { known_affected: [productId] }
       };
-    });
+      // route by id shape.
+      if (idIsCve) {
+        return { cve: c.cve_id, ...base };
+      }
+      return { ids: [idEntry], ...base };
+    }).filter(v => v != null);
     const indicatorVulns = indicatorHits.map(i => ({
+      // CSAF `system_name` values land in operator-facing validators; the
+      // "exceptd-indicator" pseudo-authority is namespaced enough that NVD /
+      // Red Hat / ENISA dashboards render it as a non-CVE finding without
+      // misattributing to a real registry (CVE, GHSA, OSV).
       ids: [{ system_name: 'exceptd-indicator', text: `${playbook._meta.id}:${i.id}` }],
       notes: [{ category: 'description', text: `Indicator ${i.id} fired (${i.confidence}${i.deterministic ? ' / deterministic' : ''}) in playbook ${playbook._meta.id}.` }],
       remediations: [{ category: 'mitigation', details: validate.selected_remediation?.description || `Consult playbook brief: exceptd brief ${playbook._meta.id}.`, product_ids: [productId] }],
       product_status: { known_affected: [productId] }
     }));
-    // audit W P2-D: framework-gap entries used to ride in `vulnerabilities[]`
+    // D: framework-gap entries used to ride in `vulnerabilities[]`
     // with `ids: [{ system_name: 'exceptd-framework-gap' }]`. The
     // `system_name` slot is reserved for recognised vulnerability tracking
     // authorities (CVE, GHSA, etc.); exceptd-framework-gap is not one, and
@@ -1715,13 +2069,84 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         text: lines.join('\n'),
       };
     });
+    // CSAF §3.1.7.4 publisher.namespace MUST be the trust
+    // anchor of the entity publishing the advisory — the OPERATOR running the
+    // scan, not the tool vendor. Pre-fix every CSAF emitted by the runner
+    // claimed https://exceptd.com as namespace, falsely attributing
+    // responsibility for advisory accuracy to the tooling provider. Resolve
+    // in priority order: explicit --publisher-namespace > --operator if it
+    // looks URL-shaped > fallback `urn:exceptd:operator:unknown` with a note
+    // documenting the gap.
+    const operatorClean = sanitizeOperatorText(runOpts.operator);
+    const explicitNs = sanitizeOperatorText(runOpts.publisherNamespace);
+    let publisherNamespace;
+    let publisherNamespaceSource;
+    if (explicitNs && /^https?:\/\//i.test(explicitNs)) {
+      publisherNamespace = explicitNs;
+      publisherNamespaceSource = 'runOpts.publisherNamespace';
+    } else if (operatorClean && /^https?:\/\//i.test(operatorClean)) {
+      publisherNamespace = operatorClean;
+      publisherNamespaceSource = 'runOpts.operator';
+    } else {
+      publisherNamespace = 'urn:exceptd:operator:unknown';
+      publisherNamespaceSource = 'fallback';
+    }
+    const namespaceFallbackNote = (publisherNamespaceSource === 'fallback') ? [{
+      category: 'general',
+      title: 'Publisher namespace not supplied',
+      text: 'No --publisher-namespace and no URL-shaped --operator were supplied to this run. CSAF §3.1.7.4 requires the namespace to be the publisher\'s trust anchor — i.e. the OPERATOR running the scan, not the tooling vendor. Re-emit with `--publisher-namespace https://your-org.example` (or a URL-shaped `--operator`) to attribute responsibility for advisory accuracy correctly.'
+    }] : [];
+    // ALSO surface the unclaimed-publisher condition through
+    // the structured runtime_errors[] accumulator so machine-readable
+    // consumers (CI gates, dashboards) can branch on it without parsing
+    // notes[] prose. The orchestrator's post-close pass folds late-pushed
+    // _runErrors into phases.analyze.runtime_errors before the run-level
+    // return, so the warning surfaces alongside other run-time anomalies.
+    // De-dupe: only push once per bundle-build pass (multi-format emit
+    // builds CSAF once via memoization, so this fires at most once per run).
+    if (publisherNamespaceSource === 'fallback' && Array.isArray(runOpts._runErrors)) {
+      const already = runOpts._runErrors.some(e => e && e.kind === 'bundle_publisher_unclaimed');
+      if (!already) {
+        runOpts._runErrors.push({
+          kind: 'bundle_publisher_unclaimed',
+          reason: 'CSAF document.publisher.namespace fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Operator attribution is unclaimed on this advisory.',
+          remediation: 'Re-run with --publisher-namespace <https-url> (or a URL-shaped --operator).'
+        });
+      }
+    }
+
+    // thread the validated --operator name into
+    // tracking.generator (engine identity) AND publisher.contact_details
+    // (operator-of-record). engine.version is read from the package once per
+    // process. contact_details is omitted when no operator was supplied so
+    // the field doesn't carry a misleading null.
+    const publisherBlock = {
+      category: 'vendor',
+      name: 'exceptd',
+      namespace: publisherNamespace,
+    };
+    if (operatorClean) publisherBlock.contact_details = operatorClean;
+
+    // CSAF §3.1.11.3.5.1 defines `final` as an immutable
+    // advisory; subsequent re-emits against the same tracking.id are
+    // refused by strict validators (BSI CSAF Validator). Runtime detection
+    // runs with no operator review loop are inherently revisable, so the
+    // default is `interim`. Operators who have reviewed and are ready to
+    // promote pass `--csaf-status final` (threaded via runOpts.csafStatus);
+    // any other value falls back to `interim` rather than emitting an
+    // unrecognized status word.
+    const allowedCsafStatuses = new Set(['draft', 'interim', 'final']);
+    const csafStatus = allowedCsafStatuses.has(runOpts.csafStatus)
+      ? runOpts.csafStatus
+      : 'interim';
+
     return {
       document: {
         category: 'csaf_security_advisory',
         csaf_version: '2.0',
-        publisher: { category: 'vendor', name: 'exceptd', namespace: 'https://exceptd.com' },
+        publisher: publisherBlock,
         title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} CVE(s), ${indicatorHits.length} indicator hit(s), ${(analyze.framework_gap_mapping || []).length} framework gap(s))`,
-        notes: gapNotes,
+        notes: [...namespaceFallbackNote, ...gapNotes],
         tracking: {
           // F2/F9: CSAF tracking.id binds to the run's session_id (threaded
           // from run() via close()) so attestation file names, OpenVEX
@@ -1730,8 +2155,14 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           // the same millisecond collided and one run's documents
           // referenced ids that didn't match anything else on disk.
           id: `exceptd-${playbook._meta.id}-${sessionId}`,
-          status: 'final',
+          status: csafStatus,
           version: playbook._meta.version,
+          // name the engine that emitted the advisory.
+          // CSAF §3.1.11.3.2 places this under tracking.generator.engine.
+          generator: {
+            engine: { name: 'exceptd', version: getEngineVersion() },
+            date: now,
+          },
           initial_release_date: now,
           current_release_date: now,
           revision_history: [{ number: '1', date: now, summary: 'Initial finding emission' }]
@@ -1748,6 +2179,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         evidence_requirements: validate.evidence_requirements,
         residual_risk_statement: validate.residual_risk_statement,
         indicators_fired: indicatorHits.map(i => ({ id: i.id, confidence: i.confidence, deterministic: i.deterministic })),
+        publisher_namespace_source: publisherNamespaceSource,
       }
     };
   }
@@ -1763,8 +2195,17 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   // render empty fields.
   if (format === 'sarif' || format === 'sarif-2.1.0') {
     const stripNulls = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v != null));
+    // SARIF rule ids are global within a single sarif-log run.
+    // Pre-fix, generic ruleIds like `framework-gap-0` (and shared CVE ids
+    // across playbooks) collided when results from multiple playbook runs
+    // were merged into one SARIF document — GitHub Code Scanning de-dupes
+    // by ruleId, so the second playbook's rule definition silently
+    // overwrote the first. Prefix every ruleId with the playbook slug so
+    // every rule definition is unambiguously attributable to one playbook,
+    // and cross-playbook merges retain all results.
+    const rulePrefix = `${playbookSlug}/`;
     const cveResults = analyze.matched_cves.map(c => ({
-      ruleId: c.cve_id,
+      ruleId: `${rulePrefix}${c.cve_id}`,
       level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
       message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
       properties: stripNulls({
@@ -1781,7 +2222,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     const indicatorResults = indicatorHits.map(i => {
       const locs = sarifLocationsForIndicator(playbook, i);
       const result = {
-        ruleId: i.id,
+        ruleId: `${rulePrefix}${i.id}`,
         level: i.deterministic ? 'error' : (i.confidence === 'high' ? 'warning' : 'note'),
         message: { text: `Indicator ${i.id} fired (${i.confidence}${i.deterministic ? ' / deterministic' : ''}). Playbook: ${playbook._meta.id}.` },
         properties: stripNulls({
@@ -1796,7 +2237,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       return result;
     });
     const gapResults = (analyze.framework_gap_mapping || []).map((g, idx) => ({
-      ruleId: `framework-gap-${idx}`,
+      ruleId: `${rulePrefix}framework-gap-${idx}`,
       // Framework gaps are control-design observations, not vulnerabilities —
       // SARIF §3.27.9 `kind: informational` routes them appropriately.
       kind: 'informational',
@@ -1805,18 +2246,18 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       properties: stripNulls({ kind: 'framework_gap', framework: g.framework, control: g.claimed_control }),
     }));
     const cveRules = analyze.matched_cves.map(c => ({
-      id: c.cve_id, shortDescription: { text: c.cve_id },
+      id: `${rulePrefix}${c.cve_id}`, shortDescription: { text: c.cve_id },
       fullDescription: { text: `RWEP ${c.rwep} · KEV=${c.cisa_kev} · active_exploitation=${c.active_exploitation}` },
       defaultConfiguration: { level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note' },
       helpUri: `https://nvd.nist.gov/vuln/detail/${c.cve_id}`,
     }));
     const indicatorRules = indicatorHits.map(i => ({
-      id: i.id, shortDescription: { text: i.id },
+      id: `${rulePrefix}${i.id}`, shortDescription: { text: i.id },
       fullDescription: { text: `Indicator from playbook ${playbook._meta.id}. Type: ${i.type}. Confidence: ${i.confidence}.` },
       defaultConfiguration: { level: i.deterministic ? 'error' : (i.confidence === 'high' ? 'warning' : 'note') },
     }));
     const gapRules = (analyze.framework_gap_mapping || []).map((g, idx) => ({
-      id: `framework-gap-${idx}`,
+      id: `${rulePrefix}framework-gap-${idx}`,
       shortDescription: { text: `${g.framework}: ${g.claimed_control || `gap-${idx}`}` },
       fullDescription: { text: g.actual_gap || `Framework gap in ${g.framework}` },
       defaultConfiguration: { level: 'note' },
@@ -1832,7 +2273,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         } },
         results: [...cveResults, ...indicatorResults, ...gapResults],
         invocations: [{ executionSuccessful: true, properties: stripNulls({
-          // audit W P3-A: apply the B7 stripNulls contract here too — the
+          // A: apply the B7 stripNulls contract here too — the
           // `remediation` field is null for any run that didn't surface a
           // selected_remediation, and SARIF viewers render null property
           // values as visible empty rows. Same helper as the result
@@ -1861,7 +2302,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   //        `urn:exceptd:indicator:<playbook>:<indicator-id>` (RFC 8141) so
   //        they pass IRI validation in downstream VEX consumers.
   if (format === 'openvex' || format === 'openvex-0.2.0') {
-    // audit W P2-B: reuse the bundle-wide `now` so OpenVEX `timestamp`
+    // B: reuse the bundle-wide `now` so OpenVEX `timestamp`
     // aligns with CSAF `document.tracking.initial_release_date` when both
     // formats are emitted in the same close() pass. Pre-fix each format
     // crystallised its own Date.now() value, and the two bundles in
@@ -1881,7 +2322,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       if (remediationDescription) return `Apply remediation from validate phase: ${remediationDescription}`;
       return fallback;
     };
-    // audit W P1-A: same `vex_status === 'fixed'` correctness rule as the
+    // A: same `vex_status === 'fixed'` correctness rule as the
     // CSAF emitter. The catalog `live_patch_available` flag is a global
     // "vendor publishes a live-patch" signal, not an operator-host
     // disposition. Treating it as `status: fixed` made OpenVEX statements
@@ -2054,6 +2495,16 @@ function normalizeSubmission(submission, playbook) {
     signals: { ...(submission.signals || {}) },
     precondition_checks: { ...(submission.precondition_checks || {}) },
     _original_shape: 'flat (v0.11.0)',
+    // BB P1-4: normalizeSubmission pushes structured errors (e.g.
+    // signal_overrides_invalid) onto submission._runErrors above. If the
+    // submission is flat, the fresh `out` literal built here loses that
+    // accumulator unless we forward it. run()'s harvest at the entry to
+    // detect/analyze reads agentSubmission._runErrors — without this carry,
+    // flat submissions with invalid signal_overrides silently lost the
+    // v0.12.19 U REG-1 contract (errors never reached analyze.runtime_errors).
+    ...(Array.isArray(submission._runErrors) && submission._runErrors.length
+      ? { _runErrors: submission._runErrors.slice() }
+      : {}),
   };
   const knownPreconditions = new Set((playbook?._meta?.preconditions || []).map(p => p.id));
   const knownArtifacts = new Set((playbook?.phases?.look?.artifacts || []).map(a => a.id));
@@ -2672,10 +3123,18 @@ module.exports = {
   vexFilterFromDoc,
   normalizeSubmission,
   autoDetectPreconditions,
+  // MM P1-D: exposed for tests/audit-vv-trust-fixes.test.js so library-side
+  // direct callers (the fallback path the CLI guard cannot reach) can be
+  // exercised without spawning a CLI subprocess.
+  sanitizeOperatorText,
   // internal helpers exposed for tests
   _resolvedPhase: resolvedPhase,
   _deepMerge: deepMerge,
   _evalCondition: evalCondition,
   _interpolate: interpolate,
   _activeRuns: _activeRuns,
+  _acquireLock: acquireLock,
+  _acquireLockDiagnostic: acquireLockDiagnostic,
+  _releaseLock: releaseLock,
+  _lockFilePath: lockFilePath,
 };