@blamejs/exceptd-skills 0.12.13 → 0.12.16

package/bin/exceptd.js

@@ -227,7 +227,8 @@ v0.12.0 canonical surface
                                                     for latest published version + days behind
 
   ci                         One-shot CI gate. Exit codes: 0 PASS, 2 detected/escalate,
-                             3 ran-but-no-evidence, 4 blocked (ok:false), 1 framework error.
+                             3 ran-but-no-evidence, 4 blocked (ok:false),
+                             5 jurisdiction clock started, 1 framework error.
                              --all | --scope <type> | (auto-detect)
                              --max-rwep <n>         cap below playbook default
                              --block-on-jurisdiction-clock
@@ -414,8 +415,21 @@ function main() {
   if (cmd === "refresh" && (rest.includes("--no-network") || rest.includes("--prefetch"))) {
     // v0.11.14 (#129): --prefetch is the operator-facing name for the
     // cache-population path. --no-network retained as alias for back-compat.
+    //
+    // v0.12.16: BUT — `refresh --no-network` previously stripped BOTH flags
+    // before invoking prefetch.js, leaving prefetch in network-fetching
+    // (default) mode. The operator's "do not touch the network" intent was
+    // lost in dispatch. Ubuntu CI passed because cached data was warm;
+    // Windows + macOS CI runners with cold caches hit 30s test timeout
+    // attempting 47 real fetches. Preserve `--no-network` when the operator
+    // explicitly supplied it; strip only `--prefetch` (the alias).
     effectiveCmd = "prefetch";
-    effectiveRest = rest.filter(a => a !== "--no-network" && a !== "--prefetch");
+    const wantedNoNetwork = rest.includes("--no-network");
+    effectiveRest = rest.filter(a => a !== "--prefetch");
+    if (wantedNoNetwork && !effectiveRest.includes("--no-network")) {
+      // Already preserved; no-op. But explicit so a future filter regression
+      // is visible.
+    }
   } else if (cmd === "refresh" && rest.includes("--indexes-only")) {
     effectiveCmd = "build-indexes";
     effectiveRest = rest.filter(a => a !== "--indexes-only");
@@ -541,10 +555,16 @@ function emit(obj, pretty, humanRenderer) {
 }
 
 function emitError(msg, extra, pretty) {
+  // v0.12.14 (audit A P1-2): the v0.11.13 emit() fix used exitCode + return
+  // to defend stdout-buffered writes from truncation under piped consumers.
+  // emitError() (stderr) kept process.exit(1), which has the same truncation
+  // class — CLAUDE.md's "fix the class, not the instance." Now: write to
+  // stderr, set exitCode = 1, return. Every caller already uses
+  // `return emitError(...)` so the return-value propagation is clean.
   const body = Object.assign({ ok: false, error: msg }, extra || {});
   const s = pretty ? JSON.stringify(body, null, 2) : JSON.stringify(body);
   process.stderr.write(s + "\n");
-  process.exit(1);
+  process.exitCode = 1;
 }
 
 function readEvidence(evidenceFlag) {
@@ -572,6 +592,55 @@ function loadRunner() {
   return require(path.join(PKG_ROOT, "lib", "playbook-runner.js"));
 }
 
+/**
+ * F5: detect whether a parsed JSON document is plausibly CycloneDX VEX or
+ * OpenVEX. The runner's vexFilterFromDoc returns Set(0) tolerantly for
+ * anything else, which means an operator who passes SARIF / SBOM / CSAF /
+ * advisory JSON by mistake gets zero filter + zero feedback. We pre-validate
+ * at the CLI layer so the operator finds out at flag parse time.
+ *
+ * Returns { ok, detected, top_level_keys[] }. `detected` is one of:
+ *   "cyclonedx-vex" | "openvex" | "not-vex"
+ */
+function detectVexShape(doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return { ok: false, detected: "not-an-object", top_level_keys: [] };
+  }
+  const keys = Object.keys(doc);
+  // CycloneDX VEX: bomFormat==="CycloneDX" + vulnerabilities[] is the
+  // canonical shape; CycloneDX 1.4+ also allows a standalone vulnerabilities
+  // document where entries carry analysis.state. Accept either when the
+  // entries look vex-shaped (have id/bom_ref/analysis).
+  if (Array.isArray(doc.vulnerabilities)) {
+    const isBom = doc.bomFormat === "CycloneDX";
+    const entriesLookVex = doc.vulnerabilities.length === 0
+      || doc.vulnerabilities.some(v => v && typeof v === "object" && (v.id || v["bom-ref"] || v.bom_ref || v.analysis));
+    if (isBom || entriesLookVex) {
+      return { ok: true, detected: "cyclonedx-vex", top_level_keys: keys };
+    }
+  }
+  // OpenVEX: @context starts with https://openvex.dev AND statements[]
+  const ctx = doc["@context"];
+  const ctxStr = Array.isArray(ctx) ? ctx[0] : ctx;
+  if (typeof ctxStr === "string" && ctxStr.startsWith("https://openvex.dev") && Array.isArray(doc.statements)) {
+    return { ok: true, detected: "openvex", top_level_keys: keys };
+  }
+  // Common false-positive shapes — give the operator a hint.
+  if (Array.isArray(doc.runs) && doc.$schema && String(doc.$schema).includes("sarif")) {
+    return { ok: false, detected: "sarif-not-vex", top_level_keys: keys };
+  }
+  if (doc.document && doc.document.category && String(doc.document.category).startsWith("csaf_")) {
+    return { ok: false, detected: "csaf-advisory-not-vex", top_level_keys: keys };
+  }
+  if (doc.bomFormat === "CycloneDX" && !Array.isArray(doc.vulnerabilities)) {
+    return { ok: false, detected: "cyclonedx-sbom-without-vulnerabilities", top_level_keys: keys };
+  }
+  if (Array.isArray(doc.statements) && !ctxStr) {
+    return { ok: false, detected: "statements-array-but-no-openvex-context", top_level_keys: keys };
+  }
+  return { ok: false, detected: "unrecognized", top_level_keys: keys };
+}
+
 function firstDirectiveId(runner, playbookId) {
   const pb = runner.loadPlaybook(playbookId);
   if (!pb.directives || !pb.directives.length) {
@@ -592,6 +661,7 @@ function dispatchPlaybook(cmd, argv) {
     bool:  ["pretty", "air-gap", "force-stale", "all", "flat", "directives",
             "ci", "latest", "diff-from-latest", "explain", "signal-list", "ack",
             "force-overwrite", "no-stream", "block-on-jurisdiction-clock",
+            "force-replay",
             "json-stdout-only", "fix", "human", "json", "strict-preconditions",
             // v0.12.9: doctor --shipped-tarball runs the verify-shipped-tarball
             // gate alongside --signatures. doctor --registry-check + --signatures
@@ -674,8 +744,42 @@ function dispatchPlaybook(cmd, argv) {
   }
   // Multi-operator teams need attestations bound to a specific human or
   // service identity. --operator <name> persists into the attestation file
-  // for audit-trail accountability. Free-form string; no validation.
-  if (args.operator) runOpts.operator = args.operator;
+  // for audit-trail accountability.
+  //
+  // F9: validate the input. Pre-fix the value flowed into runOpts unchanged,
+  // so an operator could inject newlines / control chars / arbitrary length
+  // into attestation export output (multi-line "operator:" key/value pairs
+  // are a forgery surface — a forged second line could look like a separate
+  // attestation field to a naive parser). Now: strip ASCII control chars
+  // (\x00-\x1F + \x7F), cap length at 256, reject if all-whitespace.
+  if (args.operator !== undefined) {
+    if (typeof args.operator !== "string") {
+      return emitError("run: --operator must be a string.", { provided: typeof args.operator }, pretty);
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1F\x7F]/.test(args.operator)) {
+      return emitError(
+        "run: --operator contains ASCII control characters (newline, tab, NUL, etc.). Refusing — these would corrupt attestation export shape and enable forgery via multi-line injection.",
+        { provided_length: args.operator.length },
+        pretty
+      );
+    }
+    if (args.operator.length > 256) {
+      return emitError(
+        `run: --operator too long: ${args.operator.length} chars (limit 256). Use a stable identifier (email, service-account name) — not a free-form description.`,
+        { provided_length: args.operator.length },
+        pretty
+      );
+    }
+    if (args.operator.trim().length === 0) {
+      return emitError(
+        "run: --operator is empty or whitespace-only. Pass a meaningful identifier or omit the flag.",
+        null,
+        pretty
+      );
+    }
+    runOpts.operator = args.operator;
+  }
   // --ack: operator acknowledges the jurisdiction obligations surfaced by
   // govern. Captured in attestation; downstream tooling can check whether
   // consent was explicit vs. implicit. AGENTS.md says the AI should surface
@@ -1071,8 +1175,11 @@ Exit codes:
   3  Ran-but-no-evidence   Every result was inconclusive AND no evidence was
                            submitted (visibility gap — CI should fail loud).
   4  Blocked               Result returned ok:false (preflight halt, missing
-                           preconditions with on_fail=halt, etc.) OR
-                           --block-on-jurisdiction-clock fired.
+                           preconditions with on_fail=halt, etc.).
+  5  CLOCK_STARTED         --block-on-jurisdiction-clock fired: at least one
+                           close.notification_actions entry started a
+                           regulatory clock (NIS2 24h, GDPR 72h, DORA 4h,
+                           etc.) and the operator has not acked.
 
 Output: verb, session_id, playbooks_run, summary{total, detected,
 max_rwep_observed, jurisdiction_clocks_started, verdict, fail_reasons[]},
@@ -1437,7 +1544,26 @@ function cmdPlan(runner, args, runOpts, pretty) {
   emit(plan, pretty);
 }
 
+// v0.12.15 (audit L F1, F2): --scope must validate against the accepted
+// set. The prior shape silently returned [] for any unknown scope, which
+// in `run --scope nonsense` produced `count: 0` + exit 0 (cmd reports
+// "ran 0 playbooks") and in `ci --scope nonsense` silently ran only the
+// cross-cutting set (the union with `framework` produced a false-positive
+// PASS). Both are operator-intent loss patterns CLAUDE.md flags as the
+// "field-present, content-wrong" class.
+const VALID_SCOPES = ["system", "code", "service", "cross-cutting", "all"];
+
+function validateScopeOrThrow(scope) {
+  if (typeof scope !== "string" || !VALID_SCOPES.includes(scope)) {
+    throw new Error(
+      `--scope must be one of ${JSON.stringify(VALID_SCOPES)}; got ${JSON.stringify(scope)}.`
+    );
+  }
+  return scope;
+}
+
 function filterPlaybooksByScope(runner, scope) {
+  validateScopeOrThrow(scope);
   const ids = runner.listPlaybooks();
   return ids.filter(id => {
     try {
@@ -1513,7 +1639,8 @@ function cmdRun(runner, args, runOpts, pretty) {
     if (args.all) {
       ids = runner.listPlaybooks();
     } else {
-      ids = filterPlaybooksByScope(runner, args.scope);
+      try { ids = filterPlaybooksByScope(runner, args.scope); }
+      catch (e) { return emitError(`run: ${e.message}`, { provided_scope: args.scope }, pretty); }
     }
     return cmdRunMulti(runner, ids, args, runOpts, pretty, { trigger: args.all ? "--all" : `--scope ${args.scope}` });
   }
@@ -1619,13 +1746,32 @@ function cmdRun(runner, args, runOpts, pretty) {
   // --vex <file>: load a CycloneDX/OpenVEX document and pass the not_affected
   // CVE ID set through to analyze() so matched_cves drops them.
   if (args.vex) {
+    let vexDoc;
+    try {
+      vexDoc = JSON.parse(fs.readFileSync(args.vex, "utf8"));
+    } catch (e) {
+      return emitError(`run: failed to load --vex ${args.vex}: ${e.message}`, null, pretty);
+    }
+    // F5: validate the VEX shape BEFORE handing to runner.vexFilterFromDoc.
+    // The runner tolerantly returns Set(0) for anything that's not CycloneDX
+    // or OpenVEX shape, so an operator who passes a SARIF / SBOM / CSAF
+    // advisory by mistake got ZERO filter applied and ZERO feedback. Now:
+    // reject with a clear error naming the detected shape.
+    const shape = detectVexShape(vexDoc);
+    if (!shape.ok) {
+      return emitError(
+        `run: --vex file doesn't look like CycloneDX or OpenVEX. Detected shape: ${shape.detected}. ` +
+        `Expected CycloneDX VEX (bomFormat:"CycloneDX" + vulnerabilities[]) or OpenVEX (@context starting "https://openvex.dev" + statements[]).`,
+        { provided_path: args.vex, top_level_keys: shape.top_level_keys },
+        pretty
+      );
+    }
     try {
-      const vexDoc = JSON.parse(fs.readFileSync(args.vex, "utf8"));
       const vexSet = runner.vexFilterFromDoc(vexDoc);
       submission.signals = submission.signals || {};
       submission.signals.vex_filter = [...vexSet];
     } catch (e) {
-      return emitError(`run: failed to load --vex ${args.vex}: ${e.message}`, null, pretty);
+      return emitError(`run: failed to apply --vex ${args.vex}: ${e.message}`, null, pretty);
     }
   }
 
@@ -1693,8 +1839,11 @@ function cmdRun(runner, args, runOpts, pretty) {
         hint: "Pass --force-overwrite to replace, or supply a fresh --session-id (omit the flag for an auto-generated hex).",
         verb: "run",
       };
+      // v0.12.14 (audit A P1-2): exitCode + return instead of process.exit
+      // so the stderr line drains under piped CI consumers.
       process.stderr.write(JSON.stringify(err) + "\n");
-      process.exit(3);
+      process.exitCode = 3;
+      return;
     }
     if (persistResult.prior_session_id) {
       // Force-overwrite happened — surface the prior_session_id in the
@@ -1707,8 +1856,15 @@ function cmdRun(runner, args, runOpts, pretty) {
   }
 
   if (result && result.ok === false) {
+    // F19: align preflight-halt exit code between `run --ci` and `ci`.
+    // Pre-fix `run --ci` exited 1 (FRAMEWORK_ERROR) while `ci` on the same
+    // halt exited 4 (BLOCKED). Now both use 4 when --ci is in effect, so
+    // operators can wire one set of exit-code expectations regardless of
+    // which verb they call. Without --ci the legacy exit 1 is preserved
+    // (ok:false bodies are framework signals when no CI gating is asked for).
     process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
-    process.exit(1);
+    process.exitCode = args.ci ? 4 : 1;
+    return;
   }
 
   // v0.11.6 (#96): --strict-preconditions escalates warn-level preflight
@@ -1757,6 +1913,26 @@ function cmdRun(runner, args, runOpts, pretty) {
     }
   }
 
+  // --block-on-jurisdiction-clock (F3): the flag was registered + documented on
+  // `run --help` but only honored on cmdCi. Pre-fix, `exceptd run mcp
+  // --block-on-jurisdiction-clock` exited 0 even when an NIS2 24h clock had
+  // started. Now: when ANY close.notification_actions entry has a started
+  // clock that the operator hasn't acked, exit 5 (CLOCK_STARTED) with a
+  // stderr line naming the obligations. Mirrors cmdCi semantics.
+  if (args["block-on-jurisdiction-clock"] && result && result.phases) {
+    const startedClocks = (result.phases?.close?.notification_actions || [])
+      .filter(n => n && n.clock_started_at != null && n.clock_pending_ack !== true);
+    if (startedClocks.length > 0) {
+      const refs = startedClocks
+        .map(n => `${n.obligation_ref || n.jurisdiction || "?"}@${n.clock_started_at}`)
+        .join("; ");
+      process.stderr.write(`[exceptd run --block-on-jurisdiction-clock] CLOCK_STARTED: ${startedClocks.length} jurisdiction clock(s) running and unacked: ${refs}. Exit 5.\n`);
+      emit(result, pretty);
+      process.exitCode = 5;
+      return;
+    }
+  }
+
   // --ci: machine-readable verdict for CI gates.
   //
   // The detect phase classification is the host-specific signal — "is THIS
@@ -1893,6 +2069,18 @@ function cmdRun(runner, args, runOpts, pretty) {
     const top = rwep?.threshold?.escalate ?? "n/a";
     const verdictIcon = cls === "detected" ? "[!! DETECTED]" : cls === "inconclusive" ? "[i  INCONCLUSIVE]" : "[ok]";
     lines.push(`\n${verdictIcon}  classification=${cls}  RWEP ${adj}/${top}${adj !== base ? ` (Δ${adj - base} from operator evidence)` : " (catalog baseline)"}  blast_radius=${obj.phases?.analyze?.blast_radius_score ?? "n/a"}/5`);
+    // F11: surface --diff-from-latest verdict in the human renderer. Pre-fix
+    // operators had to add --json to see whether the run drifted from the
+    // previous attestation. Now one summary line follows the classification.
+    if (obj.diff_from_latest) {
+      const dfl = obj.diff_from_latest;
+      if (dfl.status === "no_prior_attestation_for_playbook") {
+        lines.push(`> drift vs prior: (no prior attestation for ${dfl.playbook_id})`);
+      } else {
+        const priorTag = dfl.prior_session_id ? ` (prior ${dfl.prior_session_id}` + (dfl.prior_captured_at ? ` @ ${dfl.prior_captured_at.slice(0, 19)})` : ")") : "";
+        lines.push(`> drift vs prior: ${dfl.status}${priorTag}`);
+      }
+    }
     const cves = obj.phases?.analyze?.matched_cves || [];
     const baseline = obj.phases?.analyze?.catalog_baseline_cves || [];
     if (cves.length) {
@@ -1956,6 +2144,57 @@ function cmdRun(runner, args, runOpts, pretty) {
  * Falls back to running every playbook with empty evidence (engine returns
  * inconclusive findings + visibility gaps) when no --evidence is given.
  */
+/**
+ * F13: collapse per-playbook notification_actions into a deduped rollup.
+ * Multi-playbook runs frequently surface the same jurisdiction clock from
+ * 5-10 contributing playbooks (every EU-touching playbook starts a fresh
+ * NIS2 Art.23 24h clock). Operators were drafting one notification per
+ * entry instead of one per (jurisdiction, regulation, obligation, window).
+ * Key tuple stays additive — every contributor playbook id lands in
+ * `triggered_by_playbooks[]` — and earliest clock_started_at + deadline
+ * win so the strictest deadline is what an operator sees.
+ */
+function buildJurisdictionClockRollup(results) {
+  const m = new Map();
+  for (const r of results || []) {
+    if (!r || !r.phases) continue;
+    const actions = r.phases?.close?.notification_actions || [];
+    for (const n of actions) {
+      if (!n || n.clock_started_at == null) continue;
+      const key = [
+        n.jurisdiction || "?",
+        n.regulation || "?",
+        n.obligation_ref || "?",
+        String(n.window_hours ?? "?"),
+      ].join("::");
+      const existing = m.get(key);
+      if (existing) {
+        if (!existing.triggered_by_playbooks.includes(r.playbook_id)) {
+          existing.triggered_by_playbooks.push(r.playbook_id);
+        }
+        // Strictest (earliest) clock_started_at + deadline win.
+        if ((n.clock_started_at || "") < (existing.clock_started_at || "")) {
+          existing.clock_started_at = n.clock_started_at;
+        }
+        if (n.deadline && (!existing.deadline || n.deadline < existing.deadline)) {
+          existing.deadline = n.deadline;
+        }
+      } else {
+        m.set(key, {
+          jurisdiction: n.jurisdiction || null,
+          regulation: n.regulation || null,
+          obligation_ref: n.obligation_ref || null,
+          window_hours: n.window_hours ?? null,
+          clock_started_at: n.clock_started_at,
+          deadline: n.deadline || null,
+          triggered_by_playbooks: [r.playbook_id],
+        });
+      }
+    }
+  }
+  return [...m.values()];
+}
+
 function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
   const sessionId = runOpts.session_id || require("crypto").randomBytes(8).toString("hex");
   runOpts.session_id = sessionId;
@@ -2040,6 +2279,16 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
     results.push(result);
   }
 
+  // F13: dedupe jurisdiction-clock notification actions across all playbook
+  // results into a single rollup. Pre-fix a 13-playbook multi-run with 8
+  // contributors of "EU NIS2 Art.23 24h" produced 8 separate entries, so
+  // operators drafted 8 NIS2 notifications when one was sufficient. Per-
+  // playbook entries are preserved on individual results; this rollup is
+  // additive — keyed on (jurisdiction, regulation, obligation_ref,
+  // window_hours) — with a triggered_by_playbooks[] list so operators see
+  // which playbooks contributed.
+  const jurisdictionClockRollup = buildJurisdictionClockRollup(results);
+
   emit({
     ok: results.every(r => r.ok !== false),
     session_id: sessionId,
@@ -2053,6 +2302,7 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
       detected: results.filter(r => r.phases?.detect?.classification === "detected").length,
       inconclusive: results.filter(r => r.phases?.detect?.classification === "inconclusive").length,
     },
+    jurisdiction_clock_rollup: jurisdictionClockRollup,
     results,
   }, pretty);
   // v0.11.9 (#100): cmdRunMulti exits non-zero when any individual run
@@ -2068,6 +2318,13 @@ function cmdIngest(runner, args, runOpts, pretty) {
   // `ingest` matches the AGENTS.md ingest contract. The submission JSON may
   // carry playbook_id + directive_id; --domain/--directive flags override.
   let submission = {};
+  // F4: auto-detect piped stdin (parity with cmdRun). Without this,
+  // `echo '{...}' | exceptd ingest` failed with "no playbook resolved"
+  // because args.evidence stayed undefined and the routing JSON never got
+  // read. Mirrors the cmdRun behavior at line 1614.
+  if (!args.evidence && process.stdin.isTTY === false) {
+    args.evidence = "-";
+  }
   if (args.evidence) {
     try {
       submission = readEvidence(args.evidence);
@@ -2347,12 +2604,43 @@ function maybeSignAttestation(filePath) {
  * default root and the legacy cwd-relative root; returns whichever exists.
  * Returns null if neither has the session.
  */
+/**
+ * v0.12.14 (audit A P1-1): session-id validation — applied at every READ
+ * site, not just writes. The write path (persistAttestation) was hardened
+ * in v0.12.12, but the read paths (findSessionDir / cmdAttest / cmdReattest)
+ * accepted arbitrary strings and joined them into path.join(root, id) with
+ * no normalization. Reproducer that exfiltrated $HOME/.claude.json:
+ *   exceptd attest show '../../..'
+ *
+ * Validation regex + root-confinement check matches persistAttestation.
+ */
+function validateSessionIdForRead(sessionId) {
+  if (typeof sessionId !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(sessionId)) {
+    throw new Error(
+      `Invalid session-id: ${JSON.stringify(sessionId).slice(0, 80)}. Must match /^[A-Za-z0-9._-]{1,64}$/.`
+    );
+  }
+  return sessionId;
+}
+
 function findSessionDir(sessionId, runOpts) {
+  // v0.12.14 (audit A P1-1): validate the session-id at every read path.
+  try { validateSessionIdForRead(sessionId); }
+  catch { return null; }
   const candidates = [
     path.join(resolveAttestationRoot(runOpts), sessionId),
     path.join(process.cwd(), ".exceptd", "attestations", sessionId),
   ];
-  for (const c of candidates) if (fs.existsSync(c)) return c;
+  for (const c of candidates) {
+    // Final-resolution check: the resolved candidate must stay strictly
+    // inside its parent root after normalization. Defense in depth on top
+    // of the regex check above — catches anything that survives the
+    // string-level filter.
+    const parent = path.dirname(c);
+    const resolved = path.resolve(c);
+    if (!resolved.startsWith(path.resolve(parent) + path.sep)) continue;
+    if (fs.existsSync(c)) return c;
+  }
   return null;
 }
 
@@ -2397,7 +2685,64 @@ function walkAttestationDir(root, opts, candidates) {
   }
 }
 
+/**
+ * F10: factored Ed25519-sidecar verification used by both `attest verify`
+ * and `reattest`. Returns { file, signed, verified, reason } for a given
+ * attestation file path.
+ *
+ * Pre-fix, cmdReattest read attestation.json via JSON.parse with no
+ * authenticity check. A tampered attestation was silently consumed and the
+ * drift verdict was computed against forged input. Now cmdReattest calls
+ * this and refuses on verify-fail unless --force-replay is set.
+ */
+function verifyAttestationSidecar(attFile) {
+  const crypto = require("crypto");
+  const sigPath = attFile + ".sig";
+  const pubKeyPath = path.join(PKG_ROOT, "keys", "public.pem");
+  const pubKey = fs.existsSync(pubKeyPath) ? fs.readFileSync(pubKeyPath, "utf8") : null;
+  if (!fs.existsSync(sigPath)) {
+    return { file: attFile, signed: false, verified: false, reason: "no .sig sidecar" };
+  }
+  let sigDoc;
+  try { sigDoc = JSON.parse(fs.readFileSync(sigPath, "utf8")); }
+  catch (e) { return { file: attFile, signed: false, verified: false, reason: `sidecar parse error: ${e.message}` }; }
+  if (sigDoc.algorithm === "unsigned") {
+    return { file: attFile, signed: false, verified: false, reason: "attestation explicitly unsigned (no private key when written)" };
+  }
+  if (!pubKey) {
+    return { file: attFile, signed: true, verified: false, reason: "no public key at keys/public.pem to verify against" };
+  }
+  let content;
+  try { content = fs.readFileSync(attFile, "utf8"); }
+  catch (e) { return { file: attFile, signed: true, verified: false, reason: `attestation read error: ${e.message}` }; }
+  try {
+    const ok = crypto.verify(null, Buffer.from(content, "utf8"), {
+      key: pubKey, dsaEncoding: "ieee-p1363",
+    }, Buffer.from(sigDoc.signature_base64, "base64"));
+    return {
+      file: attFile,
+      signed: true,
+      verified: !!ok,
+      reason: ok ? "Ed25519 signature valid" : "Ed25519 signature INVALID — possible post-hoc tampering",
+    };
+  } catch (e) {
+    return { file: attFile, signed: true, verified: false, reason: `verify error: ${e.message}` };
+  }
+}
+
 function cmdReattest(runner, args, runOpts, pretty) {
+  // F29: --since ISO-8601 validation parity with `attest list --since`
+  // (already fixed in v0.12.12). Pre-fix, an invalid date silently passed
+  // through to walkAttestationDir, where the lexical comparison either
+  // matched all or none unpredictably.
+  if (args.since != null) {
+    if (typeof args.since !== "string" || isNaN(Date.parse(args.since))) {
+      return emitError(
+        `reattest: --since must be a parseable ISO-8601 timestamp (e.g. 2026-05-01 or 2026-05-01T00:00:00Z). Got: ${JSON.stringify(String(args.since)).slice(0, 80)}`,
+        null, pretty
+      );
+    }
+  }
   // --latest [--playbook <id>] [--since <ISO>] — find prior attestation
   // without requiring the operator to know the session-id.
   let sessionId = args._[0];
@@ -2417,6 +2762,37 @@ function cmdReattest(runner, args, runOpts, pretty) {
   if (!fs.existsSync(attFile)) {
     return emitError(`reattest: no attestation found at ${attFile}`, { session_id: sessionId }, pretty);
   }
+
+  // F10: verify the .sig sidecar BEFORE consuming the prior attestation.
+  // Pre-fix, a tampered attestation.json was silently parsed and the drift
+  // verdict was computed against forged input. Now: refuse on verify-fail
+  // with exit 6 (TAMPERED) unless --force-replay is explicitly set.
+  // Unsigned attestations (no private key was available at run time) emit
+  // a stderr warning but proceed — that's an operator config issue, not
+  // tampering. `verified === false && signed === true` is the real tamper
+  // signal.
+  const verify = verifyAttestationSidecar(attFile);
+  if (verify.signed && !verify.verified && !args["force-replay"]) {
+    process.stderr.write(`[exceptd reattest] TAMPERED: attestation at ${attFile} failed Ed25519 verification (${verify.reason}). Refusing to replay against forged input. Pass --force-replay to override (the replay output records sidecar_verify so the audit trail captures the override).\n`);
+    const body = {
+      ok: false,
+      error: `reattest: prior attestation failed signature verification — refusing to replay`,
+      verb: "reattest",
+      session_id: sessionId,
+      attestation_file: attFile,
+      sidecar_verify: verify,
+      hint: "If you have inspected the attestation and the divergence is benign (e.g. you re-signed manually), pass --force-replay.",
+    };
+    process.stderr.write(JSON.stringify(body) + "\n");
+    process.exitCode = 6;
+    return;
+  }
+  if (verify.signed && !verify.verified && args["force-replay"]) {
+    process.stderr.write(`[exceptd reattest] WARNING: --force-replay overriding failed signature verification on ${attFile} (${verify.reason}). The replay output records sidecar_verify so the override is audit-visible.\n`);
+  } else if (!verify.signed && verify.reason !== "no .sig sidecar") {
+    process.stderr.write(`[exceptd reattest] NOTE: attestation at ${attFile} has no Ed25519 signature (${verify.reason}). Proceeding — unsigned attestations are an operator config issue, not tamper evidence.\n`);
+  }
+
   let prior;
   try {
     prior = JSON.parse(fs.readFileSync(attFile, "utf8"));
@@ -2482,6 +2858,10 @@ function cmdReattest(runner, args, runOpts, pretty) {
     replayed_at: new Date().toISOString(),
     replay_classification: replay.phases && replay.phases.detect && replay.phases.detect.classification,
     replay_rwep_adjusted: replay.phases && replay.phases.analyze && replay.phases.analyze.rwep && replay.phases.analyze.rwep.adjusted,
+    // F10: persist the sidecar verify result + the force-replay flag so the
+    // audit trail records whether the replay was authenticated input.
+    sidecar_verify: verify,
+    force_replay: !!args["force-replay"],
   }, pretty);
 }
 
@@ -3378,6 +3758,26 @@ function cmdDoctor(runner, args, runOpts, pretty) {
 }
 
 function cmdListAttestations(runner, args, runOpts, pretty) {
+  // v0.12.14 (audit A P2-3): --playbook is registered as `multi:` so
+  // `--playbook a --playbook b` lands as an array. The prior filter used
+  // strict equality (`j.playbook_id !== args.playbook`) — always false for
+  // array, silently producing count: 0. Normalize to a Set up-front.
+  const playbookFilter = (() => {
+    if (args.playbook == null) return null;
+    const list = Array.isArray(args.playbook) ? args.playbook : [args.playbook];
+    return new Set(list.filter(x => typeof x === "string" && x.length > 0));
+  })();
+  // v0.12.14 (audit A P2-6): --since must be a parseable ISO-8601 timestamp.
+  // Prior behavior silently accepted any string and lexically compared to
+  // captured_at, producing 0-result or full-result depending on the string.
+  if (args.since != null) {
+    if (typeof args.since !== "string" || isNaN(Date.parse(args.since))) {
+      return emitError(
+        `attest list: --since must be a parseable ISO-8601 timestamp (e.g. 2026-05-01 or 2026-05-01T00:00:00Z). Got: ${JSON.stringify(String(args.since)).slice(0, 80)}`,
+        null, pretty
+      );
+    }
+  }
   // Enumerate sessions across both v0.11.0 default root and legacy cwd-
   // relative root, so operators with prior attestations still see them.
   const roots = [resolveAttestationRoot(runOpts), path.join(process.cwd(), ".exceptd", "attestations")];
@@ -3395,7 +3795,8 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
       for (const f of files) {
         try {
           const j = JSON.parse(fs.readFileSync(path.join(sdir, f), "utf8"));
-          if (args.playbook && j.playbook_id !== args.playbook) continue;
+          // v0.12.14: normalized array-set filter (see top of fn).
+          if (playbookFilter && !playbookFilter.has(j.playbook_id)) continue;
           if (args.since && (j.captured_at || "") < args.since) continue;
           entries.push({
             session_id: sid,
@@ -3415,7 +3816,7 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     ok: true,
     attestations: entries,
     count: entries.length,
-    filter: { playbook: args.playbook || null, since: args.since || null },
+    filter: { playbook: playbookFilter ? [...playbookFilter] : null, since: args.since || null },
     roots_searched: [...seenRoots],
   }, pretty, (obj) => {
     // v0.11.6 (#95) human renderer for attest list: one row per session.
@@ -3560,6 +3961,36 @@ function cmdAiRun(runner, args, runOpts, pretty) {
       process.exitCode = 1;
       return;
     }
+    // v0.12.14 (audit A P2-1): ai-run --no-stream previously emitted a
+    // session_id but never persisted the attestation, so the AI agent
+    // calling ai-run couldn't chain into `attest show / verify / diff`
+    // or `reattest` with the returned id. Now: same persistAttestation
+    // shape as cmdRun, so AI-facing flow round-trips cleanly.
+    if (result.session_id) {
+      const persistResult = persistAttestation({
+        sessionId: result.session_id,
+        playbookId: result.playbook_id || playbookId,
+        directiveId: result.directive_id || directiveId,
+        evidenceHash: result.evidence_hash,
+        operator: runOpts.operator,
+        operatorConsent: runOpts.operator_consent,
+        submission,
+        runOpts,
+        forceOverwrite: !!args["force-overwrite"],
+        filename: "attestation.json",
+      });
+      if (!persistResult.ok && !args["force-overwrite"]) {
+        // Collision without --force-overwrite. AI agents typically pass
+        // unique session ids each run, so this path is rare but surface
+        // it cleanly via the same JSONL contract.
+        process.stdout.write(JSON.stringify({
+          event: "error", reason: persistResult.error,
+          existing_attestation: persistResult.existingPath,
+        }) + "\n");
+        process.exitCode = 3;
+        return;
+      }
+    }
     // v0.11.8 (#101): unify ai-run --no-stream shape with `run`. Pre-0.11.8
     // ai-run flattened phases to top-level (`govern`, `direct`, `look`, ...),
     // while `run` nested them under `phases.*`. Operators writing JSONPath
@@ -3636,6 +4067,28 @@ function cmdAiRun(runner, args, runOpts, pretty) {
     writeLine({ phase: "analyze", ...result.phases?.analyze });
     writeLine({ phase: "validate", ...result.phases?.validate });
     writeLine({ phase: "close", ...result.phases?.close });
+    // v0.12.14 (audit A P2-1): persist the attestation in streaming mode
+    // too. Without this, the session_id emitted in the `done` frame
+    // can't be resolved by `attest show / verify / diff` or `reattest`.
+    if (result.session_id) {
+      const persistResult = persistAttestation({
+        sessionId: result.session_id,
+        playbookId: result.playbook_id || playbookId,
+        directiveId: result.directive_id || directiveId,
+        evidenceHash: result.evidence_hash,
+        operator: runOpts.operator,
+        operatorConsent: runOpts.operator_consent,
+        submission,
+        runOpts,
+        forceOverwrite: !!args["force-overwrite"],
+        filename: "attestation.json",
+      });
+      if (!persistResult.ok && !args["force-overwrite"]) {
+        writeLine({ event: "error", reason: persistResult.error,
+                    existing_attestation: persistResult.existingPath });
+        return finish(3);
+      }
+    }
     writeLine({ event: "done", ok: true, session_id: result.session_id, evidence_hash: result.evidence_hash });
     return finish(0);
   };
@@ -3854,9 +4307,13 @@ function cmdAsk(runner, args, runOpts, pretty) {
  * `run --all --ci` packaged as a verb so .github/workflows lines are short.
  *
  * Exit codes:
- *   0   PASS  — no detected findings, no rwep ≥ cap, no clock started (when
- *               --block-on-jurisdiction-clock is set).
- *   2   FAIL  — any of the above tripped.
+ *   0   PASS           — no detected findings, no rwep ≥ cap, no clock fired.
+ *   2   FAIL           — detected classification OR rwep ≥ cap.
+ *   3   NO_EVIDENCE    — every result inconclusive AND no --evidence supplied.
+ *   4   BLOCKED        — at least one playbook returned ok:false (preflight halt).
+ *   5   CLOCK_STARTED  — --block-on-jurisdiction-clock fired (F18); separated
+ *                        from FAIL so operators distinguish "detected" from
+ *                        "regulatory notification deadline running."
  */
 function cmdCi(runner, args, runOpts, pretty) {
   const scope = args.scope;
@@ -3879,7 +4336,8 @@ function cmdCi(runner, args, runOpts, pretty) {
   } else if (args.all) {
     ids = runner.listPlaybooks();
   } else if (scope) {
-    ids = filterPlaybooksByScope(runner, scope);
+    try { ids = filterPlaybooksByScope(runner, scope); }
+    catch (e) { return emitError(`ci: ${e.message}`, { provided_scope: scope }, pretty); }
     // Always include cross-cutting playbooks regardless of scope choice.
     const cross = filterPlaybooksByScope(runner, "cross-cutting");
     ids = [...new Set([...ids, ...cross])];
@@ -3927,6 +4385,11 @@ function cmdCi(runner, args, runOpts, pretty) {
   const results = [];
   let fail = false;
   let failReasons = [];
+  // F18: track jurisdiction-clock signals separately from generic FAIL so the
+  // exit code can distinguish "detected/escalated" (2) from "regulatory clock
+  // running, operator must notify" (5). Pre-fix the two collapsed into exit 2.
+  let clockStartedFail = false;
+  let clockStartedReasons = [];
 
   for (const id of ids) {
     let pb;
@@ -3978,8 +4441,13 @@ function cmdCi(runner, args, runOpts, pretty) {
       failReasons.push(`${id}: rwep_delta=${rwepAdj - rwepBase} >= cap=${cap} (classification=inconclusive; operator evidence raised the score)`);
     }
     if (blockOnClock && clockStarted) {
-      fail = true;
-      failReasons.push(`${id}: jurisdiction clock started`);
+      // F18: separate "clock started" from generic FAIL. Pre-fix this collapsed
+      // into exit 2 (FAIL), so operators couldn't distinguish "playbook
+      // detected" from "regulatory clock running." Tracked separately and
+      // exit 5 (CLOCK_STARTED) is selected below, taking precedence over
+      // FAIL but not BLOCKED.
+      clockStartedFail = true;
+      clockStartedReasons.push(`${id}: jurisdiction clock started`);
     }
   }
 
@@ -3997,13 +4465,22 @@ function cmdCi(runner, args, runOpts, pretty) {
   const inconclusiveCount = results.filter(r => r.phases?.detect?.classification === "inconclusive").length;
   const totalForVerdict = results.length;
   const noEvidenceAllInconclusive = !suppliedEvidenceForVerdict && totalForVerdict > 0 && inconclusiveCount === totalForVerdict;
+  // F18: precedence — BLOCKED > CLOCK_STARTED > FAIL > NO_EVIDENCE > PASS.
+  // CLOCK_STARTED outranks FAIL because the operator explicitly opted into
+  // the clock gate (--block-on-jurisdiction-clock); when that gate fires,
+  // they want the regulatory-deadline signal even if a detected finding
+  // also surfaces. (A detected finding is still in the body for the
+  // operator to act on; the exit-code dimension just answers "what's the
+  // top-line reason this gate failed.")
   const computedVerdict = blockedCount > 0
     ? "BLOCKED"
-    : fail
-      ? "FAIL"
-      : noEvidenceAllInconclusive
-        ? "NO_EVIDENCE"
-        : "PASS";
+    : clockStartedFail
+      ? "CLOCK_STARTED"
+      : fail
+        ? "FAIL"
+        : noEvidenceAllInconclusive
+          ? "NO_EVIDENCE"
+          : "PASS";
 
   // v0.12.9 (P2 #8 from production smoke): roll up per-playbook framework_gap
   // mappings to the ci top-level. Phase 7 of the seven-phase contract surfaces
@@ -4044,8 +4521,15 @@ function cmdCi(runner, args, runOpts, pretty) {
       .filter(n => n && n.clock_started_at != null).length,
     framework_gap_rollup: frameworkGapRollup,
     framework_gap_count: frameworkGapRollup.length,
+    // F13: dedupe jurisdiction-clock notifications across playbooks; see
+    // buildJurisdictionClockRollup. Multi-playbook ci runs were producing
+    // one notification entry per contributing playbook (often 8+) when a
+    // single notification per (jurisdiction, regulation, obligation,
+    // window) was the right shape.
+    jurisdiction_clock_rollup: buildJurisdictionClockRollup(results),
     verdict: computedVerdict,
     fail_reasons: failReasons,
+    clock_started_reasons: clockStartedReasons,
   };
 
   // v0.11.4 (#72): ci --format <fmt> previously emitted the full bundle
@@ -4076,8 +4560,10 @@ function cmdCi(runner, args, runOpts, pretty) {
     emit({ verb: "ci", session_id: sessionId, format: fmt, bundles_count: bundles.length, bundles }, pretty);
   } else if (fmt && fmt !== "json") {
     // v0.11.4 (#76): garbage format rejected with structured error, not silent empty stdout.
+    // v0.12.14: exitCode + return; matches the emitError class fix.
     process.stderr.write(JSON.stringify({ ok: false, error: `ci: --format "${fmt}" not in accepted set ["summary","markdown","csaf-2.0","sarif","openvex","json"].`, verb: "ci" }) + "\n");
-    process.exit(2);
+    process.exitCode = 2;
+    return;
   } else {
     emit({ verb: "ci", session_id: sessionId, playbooks_run: ids, summary, results }, pretty);
   }
@@ -4103,6 +4589,15 @@ function cmdCi(runner, args, runOpts, pretty) {
     process.exitCode = 4;
     return;
   }
+  // F18: precedence BLOCKED > CLOCK_STARTED > FAIL. The operator opted into
+  // --block-on-jurisdiction-clock; when a clock fires, that's the gate
+  // result they want to see at the exit-code layer. Per-playbook detected
+  // findings remain in the body for them to investigate.
+  if (clockStartedFail) {
+    process.stderr.write(`[exceptd ci] CLOCK_STARTED: ${clockStartedReasons.join("; ")}. Exit 5.\n`);
+    process.exitCode = 5;
+    return;
+  }
   if (fail) {
     process.stderr.write(`[exceptd ci] FAIL: ${failReasons.join("; ")}\n`);
     // v0.11.11: exitCode + return so emit()'s stdout flushes.