@blamejs/exceptd-skills 0.12.11 → 0.12.13

package/lib/playbook-runner.js

@@ -72,6 +72,10 @@ function loadPlaybook(playbookId) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
+// E12: per-run playbook cache. Each phase function reads runOpts._playbookCache
+// before falling back to loadPlaybook(). run() sets _playbookCache once at
+// entry so seven phases share one disk read + JSON parse instead of seven.
+
 function findDirective(playbook, directiveId) {
   const d = playbook.directives.find(x => x.id === directiveId);
   if (!d) throw new Error(`Directive not found: ${directiveId} in playbook ${playbook._meta.id}`);
@@ -100,9 +104,34 @@ function deepMerge(a, b) {
 
 // --- pre-flight: currency + preconditions + mutex ---
 
+/**
+ * Pre-flight gate. Three concerns:
+ *
+ *   1. Currency. threat_currency_score < 50 hard-blocks unless
+ *      runOpts.forceStale=true. < 70 emits a warning issue.
+ *   2. Preconditions. _meta.preconditions[] entries with on_fail in
+ *      {halt, warn, skip_phase} are evaluated against
+ *      runOpts.precondition_checks[id]. Missing values → precondition_unverified
+ *      issue (plus halt if on_fail=halt). False values → precondition_warn or
+ *      precondition_skip per on_fail.
+ *   3. Mutex. _meta.mutex[] intersect with the in-process active runs set
+ *      AND with the filesystem lockfile dir blocks the run.
+ *
+ * E5: when runOpts.strictPreconditions === true, warn-level outcomes
+ * (precondition_warn, precondition_unverified with on_fail=warn or
+ * skip_phase) are ESCALATED to halts. The function returns ok:false with
+ * blocked_by='precondition' and an issues array containing
+ * precondition_halt entries. Callers wanting "CI gate: any unverified
+ * precondition is a failure" pass strictPreconditions=true.
+ *
+ * E6: when a precondition with on_fail='skip_phase' fails, the issue carries
+ * skip_phase: 'detect' (default) so run() can route to a skipped-phase
+ * placeholder rather than executing detect against a missing prerequisite.
+ */
 function preflight(playbook, runOpts = {}) {
   const issues = [];
   const meta = playbook._meta;
+  const strict = runOpts.strictPreconditions === true;
 
   // 1. Currency gate
   const score = meta.threat_currency_score;
@@ -123,6 +152,18 @@ function preflight(playbook, runOpts = {}) {
     const submitted = runOpts.precondition_checks?.[pc.id];
     if (submitted === undefined) {
       const submission_hint = `Submit precondition_checks in your evidence JSON, e.g. { "precondition_checks": { "${pc.id}": true } }. The runner lifts this into runOpts before the gate evaluates.`;
+      if (strict) {
+        // E5: strictPreconditions promotes unverified to halt regardless of
+        // declared on_fail.
+        issues.push({ kind: 'precondition_halt', id: pc.id, check: pc.check, on_fail: pc.on_fail, submission_hint, escalated_from: 'precondition_unverified' });
+        return {
+          ok: false,
+          blocked_by: 'precondition',
+          reason: `Precondition ${pc.id} (${pc.check}) not verified by host AI; strict-preconditions enabled.`,
+          remediation: submission_hint,
+          issues
+        };
+      }
       issues.push({ kind: 'precondition_unverified', id: pc.id, check: pc.check, on_fail: pc.on_fail, submission_hint });
       if (pc.on_fail === 'halt') {
         return {
@@ -139,7 +180,25 @@ function preflight(playbook, runOpts = {}) {
       if (pc.on_fail === 'halt') {
         return { ok: false, blocked_by: 'precondition', reason: `Precondition ${pc.id} failed: ${pc.description}`, issues };
       }
-      issues.push({ kind: pc.on_fail === 'skip_phase' ? 'precondition_skip' : 'precondition_warn', id: pc.id, message: pc.description });
+      if (strict) {
+        // E5: warn-level + skip_phase outcomes escalate to halt under strict.
+        issues.push({ kind: 'precondition_halt', id: pc.id, message: pc.description, escalated_from: pc.on_fail === 'skip_phase' ? 'precondition_skip' : 'precondition_warn' });
+        return {
+          ok: false,
+          blocked_by: 'precondition',
+          reason: `Precondition ${pc.id} (${pc.check}) failed; strict-preconditions enabled.`,
+          issues
+        };
+      }
+      if (pc.on_fail === 'skip_phase') {
+        // E6: emit a skip_phase field so run() can route to a skipped-phase
+        // placeholder. Default target phase is 'detect' (the most common
+        // skip target — preconditions typically gate host-side detection).
+        // Playbooks may override via pc.skip_phase.
+        issues.push({ kind: 'precondition_skip', id: pc.id, message: pc.description, skip_phase: pc.skip_phase || 'detect' });
+      } else {
+        issues.push({ kind: 'precondition_warn', id: pc.id, message: pc.description });
+      }
     }
   }
 
@@ -214,7 +273,7 @@ function pidAlive(pid) {
  * fingerprints, framework gap summary, and skills to preload.
  */
 function govern(playbookId, directiveId, runOpts = {}) {
-  const playbook = loadPlaybook(playbookId);
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const g = resolvedPhase(playbook, directiveId, 'govern');
   return {
     phase: 'govern',
@@ -238,8 +297,8 @@ function govern(playbookId, directiveId, runOpts = {}) {
 
 // --- phase 2: direct ---
 
-function direct(playbookId, directiveId) {
-  const playbook = loadPlaybook(playbookId);
+function direct(playbookId, directiveId, runOpts = {}) {
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const d = resolvedPhase(playbook, directiveId, 'direct');
   return {
     phase: 'direct',
@@ -256,7 +315,7 @@ function direct(playbookId, directiveId) {
 // --- phase 3: look (engine emits, agent executes) ---
 
 function look(playbookId, directiveId, runOpts = {}) {
-  const playbook = loadPlaybook(playbookId);
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const l = resolvedPhase(playbook, directiveId, 'look');
   const airGap = !!playbook._meta.air_gap_mode || !!runOpts.airGap;
   return {
@@ -303,8 +362,8 @@ function look(playbookId, directiveId, runOpts = {}) {
  * and (optionally) `signal_overrides` as { indicator_id: 'hit'|'miss'|'inconclusive' } to
  * record an indicator outcome the agent computed using its own pattern matching.
  */
-function detect(playbookId, directiveId, agentSubmission = {}) {
-  const playbook = loadPlaybook(playbookId);
+function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const det = resolvedPhase(playbook, directiveId, 'detect');
   const artifacts = agentSubmission.artifacts || {};
   const overrides = agentSubmission.signal_overrides || {};
@@ -323,24 +382,61 @@ function detect(playbookId, directiveId, agentSubmission = {}) {
     return null; // truly unknown — fall through
   };
 
+  // E1: per-indicator FP-check attestation map. Operators submit
+  //   signal_overrides: { '<indicator-id>__fp_checks': { '<fp-check-name>': true } }
+  // to declare which named false_positive_checks_required[] entries on the
+  // indicator have been satisfied. An unverified FP check downgrades the
+  // verdict from 'hit' to 'inconclusive' and surfaces fp_checks_unsatisfied
+  // on the per-indicator result. See AGENTS.md Hard Rule #6 (compliance
+  // theater) and AGENTS.md §"detect (AI)" — a `hit` without its FP checks
+  // is not yet a `detected` classification.
   const indicatorResults = (det.indicators || []).map(ind => {
     const rawOverride = overrides[ind.id];
     const override = canonicalize(rawOverride);
     let verdict;
+    let fpChecksUnsatisfied = null;
     if (override === 'hit' || override === 'miss' || override === 'inconclusive') {
       verdict = override;
+      // E1: gate 'hit' verdict on per-indicator false_positive_checks_required
+      // satisfaction. The FP-check attestation arrives as a sibling key
+      // '<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`];
+        const att = (attestation && typeof attestation === 'object') ? attestation : {};
+        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;
+        }
+      }
     } else {
       // Without an explicit override, treat any captured artifact as evidence
-      // the indicator could be evaluated. Mark inconclusive if no related
-      // artifact was captured — engine doesn't pattern-match raw artifact
-      // content; the host AI is responsible for that.
+      // the indicator could be evaluated. Mark inconclusive if any artifact
+      // was captured (engine doesn't pattern-match raw artifact content; the
+      // host AI is responsible for that). With NO captured artifacts, this is
+      // a clean empty submission — emit 'miss' so the run can reach
+      // classification:'not_detected' rather than getting stuck inconclusive.
+      // E2: pre-fix both arms emitted 'inconclusive', so a clean empty run
+      // could never reach not_detected and theater_verdict stayed
+      // 'pending_agent_run' forever.
       const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
-      verdict = anyCaptured ? 'inconclusive' : 'inconclusive';
+      verdict = anyCaptured ? 'inconclusive' : 'miss';
     }
     return {
       id: ind.id, type: ind.type, confidence: ind.confidence,
       deterministic: ind.deterministic, atlas_ref: ind.atlas_ref || null,
-      attack_ref: ind.attack_ref || null, verdict
+      attack_ref: ind.attack_ref || null, verdict,
+      ...(fpChecksUnsatisfied ? { fp_checks_unsatisfied: fpChecksUnsatisfied } : {})
     };
   });
 
@@ -402,7 +498,11 @@ function detect(playbookId, directiveId, agentSubmission = {}) {
     })),
     indicators_evaluated_count: indicatorResults.length,
     classification_override_applied: validOverrides.has(override) ? (override === 'clean' ? 'not_detected' : override) : null,
-    submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty')
+    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
+    // analyze.signal_origins_with_collisions.
+    _signal_origins_collisions: Array.isArray(agentSubmission._signal_origins_collisions) ? agentSubmission._signal_origins_collisions.slice() : []
   };
 }
 
@@ -413,8 +513,8 @@ function detect(playbookId, directiveId, agentSubmission = {}) {
  * mapping + escalation evaluation. Inputs are the detect result + any
  * agent-submitted signal_values (e.g. blast_radius classification).
  */
-function analyze(playbookId, directiveId, detectResult, agentSignals = {}) {
-  const playbook = loadPlaybook(playbookId);
+function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOpts = {}) {
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const an = resolvedPhase(playbook, directiveId, 'analyze');
   const directive = findDirective(playbook, directiveId);
 
@@ -572,8 +672,10 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}) {
 
   // escalation criteria
   const escalations = [];
+  const runtimeErrors = []; // E3: collect regex-eval errors during analyze
+  const evalCtxRoot = { _runErrors: runOpts._runErrors || runtimeErrors };
   for (const ec of an.escalation_criteria || []) {
-    if (evalCondition(ec.condition, { rwep: adjustedRwep, blast_radius_score: blastRadiusScore, theater_verdict: theaterVerdict, ...agentSignals }, playbook)) {
+    if (evalCondition(ec.condition, { rwep: adjustedRwep, blast_radius_score: blastRadiusScore, theater_verdict: theaterVerdict, ...agentSignals, ...evalCtxRoot }, playbook)) {
       escalations.push({ condition: ec.condition, action: ec.action, target_playbook: ec.target_playbook || null });
     }
   }
@@ -625,7 +727,18 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}) {
       note: vexDropped.length
         ? `${vexDropped.length} CVE(s) dropped from analyze because the operator-supplied VEX statement marks them not_affected / resolved / false_positive. They remain in cve-catalog.json; the disposition lives in the VEX file.`
         : "VEX filter supplied; zero matches dropped (no CVEs in domain.cve_refs matched the VEX not-affected set)."
-    } : null
+    } : null,
+    // E3: regex-eval failures surfaced here so operators can see WHICH
+    // condition expression crashed without the runner dying. Only present
+    // when at least one evalCondition() call hit a regex exception during
+    // this analyze pass; runOpts._runErrors is the same accumulator
+    // populated by run() across all phases, so callers reading this field
+    // see every regex problem in the run.
+    runtime_errors: (runOpts._runErrors && runOpts._runErrors.length) ? runOpts._runErrors.slice() : (runtimeErrors.length ? runtimeErrors.slice() : []),
+    // E9: collisions when two flat-shape observations targeted the same
+    // indicator id. Empty when there were no collisions or no flat-shape
+    // observations submitted.
+    signal_origins_with_collisions: Array.isArray(agentSignals?._signal_origins_collisions) ? agentSignals._signal_origins_collisions.slice() : (Array.isArray(detectResult?._signal_origins_collisions) ? detectResult._signal_origins_collisions.slice() : [])
   };
 }
 
@@ -657,8 +770,11 @@ function vexFilterFromDoc(doc) {
 
 // --- phase 6: validate ---
 
-function validate(playbookId, directiveId, analyzeResult, agentSignals = {}) {
-  const playbook = loadPlaybook(playbookId);
+function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, runOpts = {}) {
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
+  // E3: surface evalCondition regex errors raised here into the same
+  // run-wide accumulator that analyze() reads.
+  const evalCtx = runOpts._runErrors ? { ...agentSignals, _runErrors: runOpts._runErrors } : agentSignals;
   const v = resolvedPhase(playbook, directiveId, 'validate');
 
   // Pick the highest-priority remediation_path whose preconditions are all
@@ -669,7 +785,7 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}) {
   for (const p of paths) {
     const pcResult = (p.preconditions || []).map(expr => ({
       expr,
-      satisfied: evalCondition(expr, agentSignals, playbook),
+      satisfied: evalCondition(expr, evalCtx, playbook),
       submitted: agentSignals[expressionKey(expr)] !== undefined
     }));
     const allSatisfied = pcResult.every(x => x.satisfied);
@@ -723,7 +839,7 @@ function computeRegressionNextRun(triggers) {
  *   - feeds_into chaining suggestions
  */
 function close(playbookId, directiveId, analyzeResult, validateResult, agentSignals = {}, runOpts = {}) {
-  const playbook = loadPlaybook(playbookId);
+  const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const c = resolvedPhase(playbook, directiveId, 'close');
   const g = resolvedPhase(playbook, directiveId, 'govern');
   const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
@@ -741,7 +857,16 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
     );
-    const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals) : null;
+    // E7: thread runOpts through so computeClockStart can check
+    // operator_consent.explicit before auto-stamping detect_confirmed.
+    const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals, runOpts) : null;
+    // E7: when the clock event is detect_confirmed AND the classification
+    // matched AND the operator did NOT pass --ack, surface clock_pending_ack
+    // so the notification record is visibly waiting on acknowledgement.
+    const clockPendingAck = !clockStart
+      && obligation?.clock_starts === 'detect_confirmed'
+      && agentSignals?.detection_classification === 'detected'
+      && !(runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true);
     const deadline = obligation && clockStart
       ? new Date(clockStart.getTime() + obligation.window_hours * 3600 * 1000).toISOString()
       : 'pending_clock_start_event';
@@ -756,6 +881,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       window_hours: obligation?.window_hours ?? null,
       clock_start_event: obligation?.clock_starts || null,
       clock_started_at: clockStart?.toISOString() || null,
+      ...(clockPendingAck ? { clock_pending_ack: true } : {}),
       deadline,
       // Alias matching compliance-team vocabulary.
       notification_deadline: deadline,
@@ -769,7 +895,8 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   // exception_generation — evaluate trigger.
   let exception = null;
   if (c.exception_generation) {
-    const triggered = evalCondition(c.exception_generation.trigger_condition, agentSignals, playbook);
+    const closeEvalCtx = runOpts._runErrors ? { ...agentSignals, _runErrors: runOpts._runErrors } : agentSignals;
+    const triggered = evalCondition(c.exception_generation.trigger_condition, closeEvalCtx, playbook);
     if (triggered) {
       const t = c.exception_generation.exception_template;
       exception = {
@@ -803,9 +930,9 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     contents: c.evidence_package.contents || [],
     destination: c.evidence_package.destination || 'local_only',
     signed: c.evidence_package.signed !== false,
-    bundle_body: buildEvidenceBundle(primaryFormat, playbook, analyzeResult, validateResult, agentSignals),
+    bundle_body: buildEvidenceBundle(primaryFormat, playbook, analyzeResult, validateResult, agentSignals, sessionId),
     bundles_by_format: extraFormats.length ? Object.fromEntries(
-      [primaryFormat, ...extraFormats].map(f => [f, buildEvidenceBundle(f, playbook, analyzeResult, validateResult, agentSignals)])
+      [primaryFormat, ...extraFormats].map(f => [f, buildEvidenceBundle(f, playbook, analyzeResult, validateResult, agentSignals, sessionId)])
     ) : null,
   } : null;
 
@@ -847,7 +974,11 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     analyze: analyzeResult,
     validate: validateResult,
     finding: analyzeFindingShape(analyzeResult),
-    ...agentSignals
+    ...agentSignals,
+    // E3: surface evalCondition regex failures from the feeds_into chain
+    // into the same accumulator. Without this the regex failure happens but
+    // analyze.runtime_errors[] never sees it.
+    ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
   };
   const feeds = (playbook._meta.feeds_into || [])
     .filter(f => evalCondition(f.condition, feedsCtx, playbook))
@@ -873,12 +1004,34 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   };
 }
 
+// E8: severity ladder for active_exploitation. The worst-of reduction lets
+// analyzeFindingShape report the most-exploited CVE in the matched set, not
+// the first-encountered one. Higher index = worse.
+const ACTIVE_EXPLOITATION_RANK = { none: 0, unknown: 1, suspected: 2, confirmed: 3 };
+
+function worstActiveExploitation(matchedCves) {
+  let worst = null;
+  let worstRank = -1;
+  for (const c of (matchedCves || [])) {
+    const v = c && c.active_exploitation;
+    if (!v) continue;
+    const rank = ACTIVE_EXPLOITATION_RANK[v] ?? -1;
+    if (rank > worstRank) { worst = v; worstRank = rank; }
+  }
+  return worst || 'unknown';
+}
+
 function analyzeFindingShape(a) {
   return {
     matched_cve_ids: (a.matched_cves || []).map(c => c.cve_id).join(', '),
     matched_cve_count: (a.matched_cves || []).length,
     kev_listed_count: (a.matched_cves || []).filter(c => c.cisa_kev).length,
-    active_exploitation: (a.matched_cves || []).find(c => c.active_exploitation)?.active_exploitation || 'unknown',
+    // E8: previously this used .find() which returned the first matched CVE
+    // with a truthy active_exploitation. With two CVEs where #1 is
+    // 'suspected' and #2 is 'confirmed', operators saw 'suspected' on
+    // notification drafts — under-stating the threat. Now reduce to the
+    // worst rank across all matched CVEs.
+    active_exploitation: worstActiveExploitation(a.matched_cves),
     rwep_adjusted: a.rwep?.adjusted ?? 0,
     rwep_base: a.rwep?.base ?? 0,
     blast_radius_score: a.blast_radius_score ?? 0,
@@ -887,35 +1040,94 @@ function analyzeFindingShape(a) {
   };
 }
 
-function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals) {
+// Slugify a string into a URN-safe segment ([a-z0-9_-]+ per RFC 8141 NSS).
+// Empty input → 'unknown' so we never emit zero-length segments.
+function urnSlug(s) {
+  if (s == null) return 'unknown';
+  const slug = String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug.length ? slug : 'unknown';
+}
+
+// Build the canonical product binding shared by CSAF + OpenVEX. CSAF's
+// product_tree must declare every product referenced from
+// vulnerabilities[].product_status; OpenVEX statements MUST carry a
+// `products` array per spec §4.3.
+function buildProductBinding(playbook, sessionId) {
+  const playbookSlug = urnSlug(playbook._meta.id);
+  const sessionSlug = urnSlug(sessionId || 'session');
+  const productId = `exceptd-target-${playbookSlug}-${sessionSlug}`;
+  const productPurl = `pkg:exceptd/scan/${sessionSlug}/${playbookSlug}`;
+  return {
+    productId,
+    productPurl,
+    productName: playbook.domain?.name || playbook._meta.id,
+  };
+}
+
+// Best-effort SARIF location list for an indicator hit. Indicator records
+// don't carry a direct artifact reference; we fall back to the playbook's
+// look-phase artifact source paths (the inspected files/processes). GitHub
+// Code Scanning hides results without `artifactLocation.uri`, so we
+// surface at least one candidate when any is known. Returns null when no
+// candidate exists — caller MUST omit `locations` rather than emit empty.
+function sarifLocationsForIndicator(playbook, indicator) {
+  const arts = (playbook.phases?.look?.artifacts) || [];
+  const candidates = arts
+    .map(a => a && (a.source || a.air_gap_alternative))
+    .filter(Boolean)
+    .map(src => String(src).split(/\s+(?:AND|OR)\s+/i)[0].trim())
+    .filter(src => src && !/^https?:/i.test(src));
+  if (!candidates.length) return null;
+  return [{ physicalLocation: { artifactLocation: { uri: candidates[0] } } }];
+}
+
+function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals, sessionId) {
+  const playbookSlug = urnSlug(playbook._meta.id);
+  const { productId, productPurl, productName } = buildProductBinding(playbook, sessionId);
+
   // CSAF-2.0 shape. v0.11.5 (#82): include vulnerabilities for both matched
   // catalogue CVEs AND fired indicators (treated as advisory pseudo-CVEs
   // under `exceptd:` namespace), so playbooks without catalogue CVEs still
   // emit a non-empty bundle.
+  //
+  // v0.12.12 (B5): emit a product_tree so csaf_security_advisory documents
+  // pass NVD/ENISA/Red Hat dashboard validation. Every vulnerability
+  // entry references the product via product_status so the binding is
+  // real, not cosmetic.
   if (format === 'csaf-2.0') {
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
-    const cveVulns = analyze.matched_cves.map(c => ({
-      cve: c.cve_id,
-      scores: [{ products: [], cvss_v3: { base_score: c.cvss_score || 0 } }],
-      threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
-      remediations: [{ category: 'vendor_fix', details: validate.selected_remediation?.description || 'See selected remediation path.' }]
-    }));
+    const fullProductNames = [{
+      product_id: productId,
+      name: productName,
+      product_identification_helper: { purl: productPurl }
+    }];
+    const cveVulns = analyze.matched_cves.map(c => {
+      const isAffected = c.live_patch_available !== true;
+      return {
+        cve: c.cve_id,
+        scores: [{ products: [productId], cvss_v3: { base_score: c.cvss_score || 0 } }],
+        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
+        remediations: [{ category: 'vendor_fix', details: validate.selected_remediation?.description || 'See selected remediation path.', product_ids: [productId] }],
+        product_status: isAffected ? { known_affected: [productId] } : { fixed: [productId] }
+      };
+    });
     const indicatorVulns = indicatorHits.map(i => ({
-      // Pseudo-CVE id for indicator findings (CSAF requires `cve` or `ids`).
       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}.` }],
+      remediations: [{ category: 'mitigation', details: validate.selected_remediation?.description || `Consult playbook brief: exceptd brief ${playbook._meta.id}.`, product_ids: [productId] }],
+      product_status: { known_affected: [productId] }
     }));
-    // v0.11.6 (#91): framework_gap_mapping → CSAF vulnerabilities. Each gap
-    // becomes a vulnerability keyed by the framework + control, with the
-    // gap text as the description and the required_control as the remediation.
     const gapVulns = (analyze.framework_gap_mapping || []).map((g, idx) => ({
       ids: [{ system_name: 'exceptd-framework-gap', text: `${g.framework}:${g.claimed_control || `gap-${idx}`}` }],
       notes: [
         { category: 'description', text: g.actual_gap || `Framework gap in ${g.framework} ${g.claimed_control || ''}` },
         { category: 'general', text: g.claimed_control ? `Claimed control: ${g.claimed_control}` : null },
       ].filter(n => n.text),
-      remediations: g.required_control ? [{ category: 'mitigation', details: g.required_control }] : [],
+      remediations: g.required_control ? [{ category: 'mitigation', details: g.required_control, product_ids: [productId] }] : [],
+      product_status: { under_investigation: [productId] }
     }));
     const now = new Date().toISOString();
     return {
@@ -929,13 +1141,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals)
           status: 'final',
           version: playbook._meta.version,
           initial_release_date: now,
-          // v0.11.6 (#92): CSAF 2.0 §3.2.1.12 requires current_release_date
-          // non-null. Pre-0.11.6 we only set initial_release_date and
-          // downstream validators rejected the bundle.
           current_release_date: now,
           revision_history: [{ number: '1', date: now, summary: 'Initial finding emission' }]
         }
       },
+      product_tree: { full_product_names: fullProductNames },
       vulnerabilities: [...cveVulns, ...indicatorVulns, ...gapVulns],
       exceptd_extension: {
         classification: analyze._detect_classification,
@@ -953,36 +1163,54 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals)
   // SARIF 2.1.0 — GitHub Code Scanning / VS Code SARIF Viewer / Azure DevOps
   // / most static-analysis tooling.
   //
-  // v0.11.5 (#82): emit results from BOTH matched_cves AND fired indicators.
-  // Pre-0.11.5 we emitted only matched_cves, which produced an empty bundle
-  // for playbooks like crypto-codebase / library-author whose domain.cve_refs
-  // is intentionally empty (the playbook checks process/posture, not catalog
-  // CVEs). Indicators that fire (verdict: hit) and framework gaps are now
-  // first-class SARIF results — a clean run still emits a usable bundle.
+  // v0.12.12 (B6): thread artifact source paths through to
+  // result.locations[].physicalLocation.artifactLocation.uri. GitHub Code
+  // Scanning hides results without populated locations, so the heuristic
+  // ensures clean playbook runs still surface findings in the alerts UI.
+  // v0.12.12 (B7): omit null property-bag keys so SARIF viewers don't
+  // render empty fields.
   if (format === 'sarif' || format === 'sarif-2.1.0') {
+    const stripNulls = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v != null));
     const cveResults = analyze.matched_cves.map(c => ({
       ruleId: 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: {
+      properties: stripNulls({
         kind: 'cve_match',
-        rwep: c.rwep, cisa_kev: c.cisa_kev, cisa_kev_due_date: c.cisa_kev_due_date,
-        active_exploitation: c.active_exploitation, ai_discovered: c.ai_discovered,
+        rwep: c.rwep,
+        cisa_kev: c.cisa_kev,
+        cisa_kev_due_date: c.cisa_kev_due_date ?? null,
+        active_exploitation: c.active_exploitation ?? null,
+        ai_discovered: c.ai_discovered ?? null,
         blast_radius_score: analyze.blast_radius_score,
-      }
+      }),
     }));
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
-    const indicatorResults = indicatorHits.map(i => ({
-      ruleId: 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: { kind: 'indicator_hit', confidence: i.confidence, deterministic: i.deterministic, atlas_ref: i.atlas_ref, attack_ref: i.attack_ref },
-    }));
+    const indicatorResults = indicatorHits.map(i => {
+      const locs = sarifLocationsForIndicator(playbook, i);
+      const result = {
+        ruleId: 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({
+          kind: 'indicator_hit',
+          confidence: i.confidence,
+          deterministic: i.deterministic,
+          atlas_ref: i.atlas_ref,
+          attack_ref: i.attack_ref,
+        }),
+      };
+      if (locs) result.locations = locs;
+      return result;
+    });
     const gapResults = (analyze.framework_gap_mapping || []).map((g, idx) => ({
       ruleId: `framework-gap-${idx}`,
+      // Framework gaps are control-design observations, not vulnerabilities —
+      // SARIF §3.27.9 `kind: informational` routes them appropriately.
+      kind: 'informational',
       level: 'note',
       message: { text: `${g.framework}: ${g.claimed_control} — ${g.actual_gap}${g.required_control ? '. Required: ' + g.required_control : ''}` },
-      properties: { kind: 'framework_gap', framework: g.framework, control: g.claimed_control },
+      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 },
@@ -995,11 +1223,6 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals)
       fullDescription: { text: `Indicator from playbook ${playbook._meta.id}. Type: ${i.type}. Confidence: ${i.confidence}.` },
       defaultConfiguration: { level: i.deterministic ? 'error' : (i.confidence === 'high' ? 'warning' : 'note') },
     }));
-    // v0.11.6 (#93): SARIF spec §3.27.3 — every referenced ruleId SHOULD have
-    // a corresponding rule definition in tool.driver.rules. Pre-0.11.6 we
-    // referenced framework-gap-N ids without defining them; GitHub Code
-    // Scanning + VS Code SARIF Viewer + Azure DevOps would warn or fail to
-    // display rule context. Now we emit one rule per framework gap.
     const gapRules = (analyze.framework_gap_mapping || []).map((g, idx) => ({
       id: `framework-gap-${idx}`,
       shortDescription: { text: `${g.framework}: ${g.claimed_control || `gap-${idx}`}` },
@@ -1025,42 +1248,86 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals)
     };
   }
 
-  // OpenVEX 0.2.0 — supply-chain VEX statements. v0.11.5 (#82): also include
-  // statements derived from fired indicators (treated as advisory findings)
-  // so playbooks with empty cve_refs still emit a meaningful bundle.
+  // OpenVEX 0.2.0 — supply-chain VEX statements.
+  //
+  // v0.12.12 (B1-B4): correctness sweep against the OpenVEX 0.2.0 spec.
+  //  - B1: every statement now carries a `products` array (spec MUST).
+  //  - B2: `status` derives from the verdict + confidence rather than being
+  //        hard-coded to `under_investigation`. Hits emit `affected` with
+  //        an action_statement; misses emit `not_affected` with a
+  //        justification; inconclusive findings keep `under_investigation`.
+  //  - B3: framework gaps are control-design observations, not
+  //        vulnerabilities — they are removed from the VEX emit path. They
+  //        remain in CSAF (informational notes) and SARIF (kind:
+  //        informational rules).
+  //  - B4: vulnerability `@id` values switch to the registered URN namespace
+  //        `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') {
     const issued = new Date().toISOString();
-    const cveStatements = analyze.matched_cves.map(c => ({
-      vulnerability: { '@id': c.cve_id, name: c.cve_id },
-      status: c.active_exploitation === 'confirmed' ? 'under_investigation' : (c.live_patch_available ? 'fixed' : 'affected'),
-      timestamp: issued,
-      action_statement: validate.selected_remediation?.description || null,
-      impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`
-    }));
-    const indicatorStatements = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit').map(i => ({
-      vulnerability: { '@id': `exceptd:${playbook._meta.id}:${i.id}`, name: i.id },
-      status: 'under_investigation',
-      timestamp: issued,
-      action_statement: validate.selected_remediation?.description || `Run \`exceptd brief ${playbook._meta.id}\` for context.`,
-      impact_statement: `Indicator ${i.id} fired (${i.confidence}${i.deterministic ? '/deterministic' : ''}) in playbook ${playbook._meta.id}.`,
-    }));
-    // v0.11.6 (#91): framework gaps → OpenVEX statements. Each gap becomes
-    // a statement with a pseudo-CVE id under the exceptd:framework-gap
-    // namespace so VEX downstreams ingest them cleanly.
-    const gapStatements = (analyze.framework_gap_mapping || []).map((g, idx) => ({
-      vulnerability: { '@id': `exceptd:framework-gap:${g.framework}:${g.claimed_control || idx}`, name: `${g.framework} ${g.claimed_control || `gap-${idx}`}` },
-      status: 'under_investigation',
-      timestamp: issued,
-      action_statement: g.required_control || null,
-      impact_statement: g.actual_gap || `Framework gap in ${g.framework}.`,
-    }));
+    const productEntry = {
+      '@id': productPurl,
+      subcomponents: [{ '@id': productPurl }],
+    };
+    const remediationId = validate.selected_remediation?.id || (validate.remediation_paths?.[0]?.id) || null;
+    const remediationDescription = validate.selected_remediation?.description || null;
+    const actionStatementFor = (fallback) => {
+      if (remediationId && remediationDescription) {
+        return `Apply remediation from validate phase: ${remediationId}. ${remediationDescription}`;
+      }
+      if (remediationId) return `Apply remediation from validate phase: ${remediationId}`;
+      if (remediationDescription) return `Apply remediation from validate phase: ${remediationDescription}`;
+      return fallback;
+    };
+    const cveStatements = analyze.matched_cves.map(c => {
+      const stmt = {
+        vulnerability: { '@id': `urn:cve:${urnSlug(c.cve_id)}`, name: c.cve_id },
+        products: [productEntry],
+        timestamp: issued,
+        impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`,
+      };
+      if (c.live_patch_available) {
+        stmt.status = 'fixed';
+      } else {
+        stmt.status = 'affected';
+        stmt.action_statement = actionStatementFor('Apply remediation from validate phase.');
+      }
+      return stmt;
+    });
+    const indicatorStatements = (analyze._detect_indicators || [])
+      .filter(i => i.verdict === 'hit' || i.verdict === 'miss' || i.verdict === 'inconclusive')
+      .map(i => {
+        const stmt = {
+          vulnerability: {
+            '@id': `urn:exceptd:indicator:${playbookSlug}:${urnSlug(i.id)}`,
+            name: i.id,
+          },
+          products: [productEntry],
+          timestamp: issued,
+          impact_statement: `Indicator ${i.id} (${i.verdict}; ${i.confidence}${i.deterministic ? '/deterministic' : ''}) in playbook ${playbook._meta.id}.`,
+        };
+        if (i.verdict === 'hit') {
+          // Deterministic and high-confidence hits both map to `affected`.
+          // The `deterministic` flag describes regex specificity, not
+          // operator-evidence confidence — neither warrants
+          // under_investigation when the indicator actually fired.
+          stmt.status = 'affected';
+          stmt.action_statement = actionStatementFor(`Run \`exceptd brief ${playbook._meta.id}\` for context.`);
+        } else if (i.verdict === 'miss') {
+          stmt.status = 'not_affected';
+          stmt.justification = 'vulnerable_code_not_present';
+        } else {
+          stmt.status = 'under_investigation';
+        }
+        return stmt;
+      });
     return {
       '@context': 'https://openvex.dev/ns/v0.2.0',
-      '@id': `https://exceptd.com/vex/${playbook._meta.id}/${Date.now()}`,
+      '@id': `https://exceptd.com/vex/${playbookSlug}/${Date.now()}`,
       author: 'exceptd',
       timestamp: issued,
       version: 1,
-      statements: [...cveStatements, ...indicatorStatements, ...gapStatements],
+      statements: [...cveStatements, ...indicatorStatements],
     };
   }
 
@@ -1160,7 +1427,12 @@ function normalizeSubmission(submission, playbook) {
   // v0.11.5 (#85): track which observation produced each signal_override so
   // detect can emit `from_observation` on each indicator result. Diagnostic
   // value for operators chasing "which observation drove this verdict".
+  //
+  // E9: when two observations target the same indicator id, last-write-wins
+  // silently. Track discards in _signal_origins_collisions so analyze can
+  // surface analyze.signal_origins_with_collisions for batch evidence runs.
   out._signal_origins = out._signal_origins || {};
+  out._signal_origins_collisions = out._signal_origins_collisions || [];
   for (const [key, val] of Object.entries(submission.observations || {})) {
     if (knownPreconditions.has(key)) {
       out.precondition_checks[key] = val === "ok" || val === true || val === "true";
@@ -1170,7 +1442,20 @@ function normalizeSubmission(submission, playbook) {
       const aid = knownArtifacts.has(key) ? key : (val.artifact || key);
       out.artifacts[aid] = { value: val.value, captured: val.captured !== false };
       if (val.indicator && val.result !== undefined) {
-        out.signal_overrides[val.indicator] = canonicalizeOutcome(val.result);
+        const newVerdict = canonicalizeOutcome(val.result);
+        if (out.signal_overrides[val.indicator] !== undefined && out._signal_origins[val.indicator] !== undefined) {
+          // Collision: a prior observation already set this indicator.
+          // Record the prior (which is now discarded) into the collision
+          // log, then overwrite with the new one (last-write-wins).
+          out._signal_origins_collisions.push({
+            indicator_id: val.indicator,
+            source_observation_key: out._signal_origins[val.indicator],
+            verdict: out.signal_overrides[val.indicator],
+            discarded: true,
+            replaced_by: key
+          });
+        }
+        out.signal_overrides[val.indicator] = newVerdict;
         out._signal_origins[val.indicator] = key;
       }
     }
@@ -1244,16 +1529,70 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // Cross-process mutex lock for this run. preflight verified no other lock
   // exists; we acquire ours and release in the finally block.
   const lockPath = acquireLock(playbookId);
+  // E12: parse the playbook once at run() entry and thread the parsed object
+  // through each phase via runOpts._playbookCache. Each phase otherwise calls
+  // loadPlaybook() independently; for a single run that's seven reads + parses
+  // of the same file. Cached version saves the redundant I/O + JSON parses.
+  const cachedRunOpts = { ...runOpts, _playbookCache: playbook };
+  // E3: run-time error accumulator for evalCondition regex failures and other
+  // non-fatal anomalies surfaced into analyze.runtime_errors[].
+  const runErrors = [];
+  cachedRunOpts._runErrors = runErrors;
+  // E6: phases the runner should SKIP execution for, based on skip_phase
+  // preconditions surfaced in preflight.issues.
+  const skipPhases = new Set();
+  for (const issue of (pre.issues || [])) {
+    if (issue.kind === 'precondition_skip' && issue.skip_phase) {
+      skipPhases.add(issue.skip_phase);
+    }
+  }
   try {
     const phases = {
-      govern:   govern(playbookId, directiveId, runOpts),
-      direct:   direct(playbookId, directiveId),
-      look:     look(playbookId, directiveId, runOpts),
-      detect:   detect(playbookId, directiveId, agentSubmission),
+      govern:   govern(playbookId, directiveId, cachedRunOpts),
+      direct:   direct(playbookId, directiveId, cachedRunOpts),
+      look:     look(playbookId, directiveId, cachedRunOpts),
     };
-    phases.analyze  = analyze(playbookId, directiveId, phases.detect, agentSubmission.signals || {});
-    phases.validate = validate(playbookId, directiveId, phases.analyze, agentSubmission.signals || {});
-    phases.close    = close(playbookId, directiveId, phases.analyze, phases.validate, agentSubmission.signals || {}, runOpts);
+    if (skipPhases.has('detect')) {
+      const skipIssue = (pre.issues || []).find(i => i.kind === 'precondition_skip' && i.skip_phase === 'detect');
+      phases.detect = {
+        phase: 'detect',
+        playbook_id: playbookId,
+        directive_id: directiveId,
+        skipped: true,
+        reason: skipIssue ? skipIssue.id : 'precondition_skip',
+        classification: 'skipped',
+        indicators: [],
+        false_positive_checks_required: [],
+        indicators_evaluated: [],
+        indicators_evaluated_count: 0,
+        observations_received: [],
+        signals_received: []
+      };
+      // analyze() must still run, but with an empty submission so it doesn't
+      // resolve indicator hits against a non-existent detect result.
+      phases.analyze  = analyze(playbookId, directiveId, phases.detect, {}, cachedRunOpts);
+      // Annotate analyze with the skip vocabulary so consumers can branch.
+      phases.analyze.classification = 'skipped';
+    } else {
+      phases.detect   = detect(playbookId, directiveId, agentSubmission, cachedRunOpts);
+      phases.analyze  = analyze(playbookId, directiveId, phases.detect, agentSubmission.signals || {}, cachedRunOpts);
+    }
+    phases.validate = validate(playbookId, directiveId, phases.analyze, agentSubmission.signals || {}, cachedRunOpts);
+    phases.close    = close(playbookId, directiveId, phases.analyze, phases.validate, agentSubmission.signals || {}, cachedRunOpts);
+
+    // E3: analyze() already sliced runOpts._runErrors into
+    // phases.analyze.runtime_errors at return time. Validate + close may
+    // have pushed additional regex errors AFTER analyze returned; surface
+    // those onto phases.analyze.runtime_errors so the field reflects every
+    // regex failure in the run. De-dupe by JSON shape so the analyze-time
+    // snapshot doesn't double-count.
+    if (runErrors.length && phases.analyze) {
+      const existing = new Set((phases.analyze.runtime_errors || []).map(e => JSON.stringify(e)));
+      const additions = runErrors.filter(e => !existing.has(JSON.stringify(e)));
+      if (additions.length) {
+        phases.analyze.runtime_errors = (phases.analyze.runtime_errors || []).concat(additions);
+      }
+    }
 
     const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
     const evidenceHash = crypto.createHash('sha256')
@@ -1340,7 +1679,23 @@ function evalCondition(expr, ctx, playbook) {
   if (m) {
     const val = resolvePath(ctx, m[1]);
     if (typeof val !== 'string') return false;
-    return new RegExp(m[2], 'i').test(val);
+    // E3: an operator-supplied or playbook-supplied regex with a syntax bug
+    // (or pathological backtracking) must NOT crash the engine mid-analyze.
+    // Catch construction + test exceptions, return false, and push a
+    // structured _regex_eval_error into ctx._runErrors (when present) so
+    // analyze() can surface analyze.runtime_errors[] without losing the
+    // diagnostic.
+    try {
+      return new RegExp(m[2], 'i').test(val);
+    } catch (e) {
+      const errorRec = { _regex_eval_error: { source: m[1], expr: m[2], message: e && e.message ? String(e.message) : String(e) } };
+      // Two sites where ctx may carry an accumulator: runOpts._runErrors
+      // (threaded from run()) or ctx._runErrors directly. Prefer the runOpts
+      // form; fall back to ctx.
+      if (ctx && Array.isArray(ctx._runErrors)) ctx._runErrors.push(errorRec);
+      else if (playbook && Array.isArray(playbook._runErrors)) playbook._runErrors.push(errorRec);
+      return false;
+    }
   }
 
   if (process.env.EXCEPTD_DEBUG) console.warn(`[runner] unknown condition: ${expr}`);
@@ -1398,13 +1753,35 @@ function stripOuterParens(expr) {
   return expr;
 }
 
-function computeClockStart(eventName, agentSignals) {
+/**
+ * Compute the start instant for a jurisdictional clock event. The agent
+ * submits clock_started_at_<event> ISO strings as it progresses through
+ * incident-response milestones.
+ *
+ * E7: per AGENTS.md Phase 7, the legal contract is that the clock starts
+ * from OPERATOR AWARENESS — not from the moment the engine emits a
+ * `detected` classification. Pre-fix, this auto-stamped Date.now() on
+ * detect_confirmed whenever the engine classified as detected, which is
+ * incorrect: the operator may not have seen the result yet. The corrected
+ * semantics:
+ *
+ *   - If the agent explicitly submits clock_started_at_<event>: use it.
+ *   - Otherwise, for 'detect_confirmed' with classification='detected':
+ *     stamp `now` ONLY if runOpts.operator_consent?.explicit === true
+ *     (i.e. the operator passed --ack). Without --ack, return null and
+ *     the caller (close()) surfaces clock_pending_ack: true on the
+ *     notification_actions entry so the operator sees that the clock is
+ *     waiting on acknowledgement.
+ *   - All other events without an explicit timestamp: return null.
+ */
+function computeClockStart(eventName, agentSignals, runOpts = {}) {
   // The agent submits clock_started_at_<event> ISO strings as it progresses.
   const key = `clock_started_at_${eventName}`;
-  if (agentSignals[key]) return new Date(agentSignals[key]);
-  // Fallback: use the standard 'detect_confirmed' default of "now" for the
-  // most common case so notification deadlines aren't always pending.
-  if (eventName === 'detect_confirmed' && agentSignals.detection_classification === 'detected') {
+  if (agentSignals && agentSignals[key]) return new Date(agentSignals[key]);
+  // For detect_confirmed: only auto-stamp when the operator has explicitly
+  // acknowledged the result via --ack. Otherwise leave the clock pending.
+  if (eventName === 'detect_confirmed' && agentSignals?.detection_classification === 'detected'
+      && runOpts && runOpts.operator_consent && runOpts.operator_consent.explicit === true) {
     return new Date();
   }
   return null;