@blamejs/exceptd-skills 0.12.7 → 0.12.9

package/bin/exceptd.js

@@ -378,27 +378,29 @@ function main() {
     process.exit(0);
   }
 
+  // v0.12.8: emit the deprecation banner BEFORE branching on PLAYBOOK_VERBS
+  // so that legacy aliases routed through STANDALONE_VERBS or the orchestrator
+  // (scan, dispatch, currency, verify, validate-cves, validate-rfcs,
+  // watchlist, prefetch, build-indexes) also surface the rename.
+  // Previously the banner only fired for PLAYBOOK_VERBS-resident aliases
+  // (plan, govern, direct, look, ingest, reattest, list-attestations).
+  if (LEGACY_VERB_REPLACEMENTS[cmd] && !process.env.EXCEPTD_DEPRECATION_SHOWN) {
+    const ver = readPkgVersion();
+    const haveBrief = ver !== "unknown" && ver.match(/^(\d+)\.(\d+)/) && (parseInt(RegExp.$1, 10) > 0 || parseInt(RegExp.$2, 10) >= 11);
+    process.stderr.write(
+      `[exceptd] DEPRECATION: \`${cmd}\` is a v0.10.x verb. ` +
+      (haveBrief
+        ? `Prefer \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (available in this install, v${ver}). `
+        : `Upgrade to v0.11.0+ then use \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (currently installed: v${ver}). `) +
+      `Legacy verbs remain functional through this release; they will be removed in v0.13. ` +
+      `Suppress: export EXCEPTD_DEPRECATION_SHOWN=1.\n`
+    );
+    process.env.EXCEPTD_DEPRECATION_SHOWN = "1";
+  }
+
   // Seven-phase playbook verbs run in-process — they emit JSON to stdout
   // rather than dispatch to a script.
   if (PLAYBOOK_VERBS.has(cmd)) {
-    // One-time deprecation banner per process when a legacy verb is invoked.
-    if (LEGACY_VERB_REPLACEMENTS[cmd] && !process.env.EXCEPTD_DEPRECATION_SHOWN) {
-      // Mention the installed version explicitly so an operator on v0.10.x
-      // who reads "Prefer brief..." doesn't go looking for a verb that
-      // doesn't exist in their install. v0.11.0+ has the replacement; v0.10.x
-      // users see this with the explicit "upgrade to v0.11.0 first" note.
-      const ver = readPkgVersion();
-      const haveBrief = ver !== "unknown" && ver.match(/^(\d+)\.(\d+)/) && (parseInt(RegExp.$1, 10) > 0 || parseInt(RegExp.$2, 10) >= 11);
-      process.stderr.write(
-        `[exceptd] DEPRECATION: \`${cmd}\` is a v0.10.x verb. ` +
-        (haveBrief
-          ? `Prefer \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (available in this install, v${ver}). `
-          : `Upgrade to v0.11.0+ then use \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (currently installed: v${ver}). `) +
-        `Legacy verbs remain functional through this release; they will be removed in v0.13. ` +
-        `Suppress: export EXCEPTD_DEPRECATION_SHOWN=1.\n`
-      );
-      process.env.EXCEPTD_DEPRECATION_SHOWN = "1";
-    }
     dispatchPlaybook(cmd, rest);
     return;
   }
@@ -579,7 +581,12 @@ 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",
-            "json-stdout-only", "fix", "human", "json", "strict-preconditions"],
+            "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
+            // were already accepted; explicit registration removes the silent
+            // "unknown bool flag" surface in parseArgs.
+            "shipped-tarball", "registry-check", "signatures", "currency", "cves", "rfcs"],
     multi: ["playbook", "format"],
   });
   // v0.11.2 bug #60: flip defaults to human-readable. JSON via explicit --json
@@ -701,17 +708,62 @@ function buildSkillToPlaybookHint(runner, wanted) {
     if (matches.length > 0) {
       return `That is a SKILL (read-only knowledge unit), not a PLAYBOOK (executable). Skill "${wanted}" is loaded by playbook${matches.length === 1 ? "" : "s"}: ${matches.join(", ")}. ` +
              `To execute: \`exceptd run ${matches[0]}\`. To read the skill: \`exceptd skill ${wanted}\`. ` +
-             `Tip: \`exceptd plan\` lists all 13 playbooks; \`exceptd watchlist\` lists skills.`;
+             `Tip: \`exceptd brief --all\` lists all 13 playbooks; \`exceptd watch\` lists skills.`;
     }
     // No matching skill either — provide nearest-playbook suggestions.
-    const near = ids.filter(id => id.includes(wanted) || wanted.includes(id)).slice(0, 3);
+    // v0.12.9 (P3 #9 from production smoke): substring fallback first (cheap),
+    // then edit-distance for typos that don't substring-match (`secrt`,
+    // `kernl`, `cret-stores`). Without the second pass `run secrt` returned
+    // the generic "13 playbooks" message even though `secrets` is one edit
+    // away.
+    const subMatches = ids.filter(id => id.includes(wanted) || wanted.includes(id)).slice(0, 3);
+    const fuzzyMatches = subMatches.length === 0 ? nearestByEditDistance(wanted, ids, 2).slice(0, 3) : [];
+    const near = subMatches.length ? subMatches : fuzzyMatches;
     if (near.length > 0) {
-      return `Did you mean: ${near.join(", ")}? Run \`exceptd plan\` for the full list.`;
+      return `Did you mean: ${near.join(", ")}? Run \`exceptd brief --all\` for the full list.`;
     }
-    return `Run \`exceptd plan\` to list the 13 playbooks.`;
+    return `Run \`exceptd brief --all\` to list the 13 playbooks.`;
   } catch { return null; }
 }
 
+/**
+ * Cheap Levenshtein distance, used to surface "Did you mean X?" suggestions
+ * for misspelled playbook ids in the `run <typo>` error path. Returns ids
+ * whose distance from `wanted` is ≤ `maxDistance`, sorted by closest first.
+ * Bounded by the candidate set size (13 playbooks), so the O(n*m) cost is
+ * negligible.
+ */
+function nearestByEditDistance(wanted, ids, maxDistance) {
+  if (!wanted || !Array.isArray(ids)) return [];
+  const w = String(wanted).toLowerCase();
+  const scored = [];
+  for (const id of ids) {
+    const d = editDistance(w, id.toLowerCase());
+    if (d <= maxDistance) scored.push({ id, d });
+  }
+  scored.sort((a, b) => a.d - b.d);
+  return scored.map(s => s.id);
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const prev = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let cur = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const next = Math.min(prev[j] + 1, cur + 1, prev[j - 1] + cost);
+      prev[j - 1] = cur;
+      cur = next;
+    }
+    prev[b.length] = cur;
+  }
+  return prev[b.length];
+}
+
 function printPlaybookVerbHelp(verb) {
   const cmds = {
     plan: `plan — list playbooks + directives, grouped by scope.
@@ -798,10 +850,24 @@ Flags:
                           (code 2) when phases.detect.classification === 'detected'
                           OR phases.analyze.rwep.adjusted >= rwep_threshold.escalate.
                           Logs PASS/FAIL reason to stderr.
-  --session-id <id>       Reuse a specific session ID.
+  --upstream-check        (v0.11.14) Opt-in: query npm registry for the latest
+                          published @blamejs/exceptd-skills version before
+                          detect. Warns to stderr (no exit-code change) when
+                          the local install is behind, so an operator using a
+                          stale catalog finds out before the run completes.
+  --strict-preconditions  Escalate warn-level precondition failures to halt.
+                          Without this flag, only on_fail=halt preconditions
+                          block; warn-level surface in stderr but the run
+                          proceeds. With it, any precondition_check returning
+                          false fails the run and exits non-zero.
+  --session-id <id>       Reuse a specific session ID. Collisions refused
+                          unless --force-overwrite is also passed.
+  --force-overwrite       Override the session-id collision refusal.
   --session-key <hex>     HMAC sign the evidence_package with this key.
+                          Output carries an 'hmac' field the verifier can check.
   --force-stale           Override the threat_currency_score < 50 hard-block.
-  --air-gap               Honor air_gap_alternative paths.
+  --air-gap               Honor air_gap_alternative paths in look.artifacts[]
+                          and skip the network-touching collection variants.
   --pretty                Indented JSON output.
 
 Attestation is persisted to .exceptd/attestations/<session_id>/ on every
@@ -835,12 +901,22 @@ newest-first, with truncated evidence_hash + capture timestamp + file path.`,
 
 Subverbs:
   attest show <sid>       Emit the full (unredacted) attestation.
+  attest list             Inventory every prior attestation under
+                          ~/.exceptd/attestations/ (or EXCEPTD_HOME when set).
+                          Filter with --playbook <id> or --since <ISO>. Newest
+                          first; truncated evidence_hash + capture timestamp +
+                          path per entry.
   attest export <sid>     Emit redacted JSON suitable for audit submission.
                           Strips raw artifact values; preserves evidence_hash,
                           signature, classification, RWEP, remediation choice.
-                          --format csaf wraps the export in a CSAF envelope.
+                          --format <csaf|sarif|openvex> wraps the export in the
+                          named envelope (default: redacted JSON).
   attest verify <sid>     Verify .sig sidecar against keys/public.pem.
                           Reports tamper status per attestation file.
+  attest diff <sid>       Diff <sid> against the most-recent prior attestation
+                          for the same playbook, or against --against <other-sid>
+                          for an explicit pair. Reports unchanged | drifted |
+                          resolved per evidence_hash + classification deltas.
 
 All subverbs honor --pretty for indented JSON output.`,
     discover: `discover — context-aware playbook recommender (v0.11.0).
@@ -867,7 +943,20 @@ Subchecks:
   --currency              Skill currency report (last_threat_review).
   --cves                  CVE catalog validation (offline view).
   --rfcs                  RFC catalog validation (offline view).
-  (no flag)               All four, plus signing-status (private key presence).
+  --registry-check        (v0.11.14) Opt-in: query the npm registry for the
+                          latest published version + days-since-publish.
+                          Surfaces under checks.registry.{local_version,
+                          published_version, same, behind, days_since_latest_publish}.
+                          Off by default — keeps doctor offline-clean unless
+                          asked.
+  --fix                   (v0.12.5) Attempt to auto-remediate detected gaps.
+                          Currently scoped to: regenerate the local Ed25519
+                          private key when keys/public.pem exists but
+                          .keys/private.pem is absent. Does NOT modify any
+                          file outside .keys/.
+  (no flag)               All four subchecks above (sans --registry-check
+                          unless explicitly requested), plus signing-status
+                          (private key presence under .keys/).
 
 Flags:
   --json                  Emit JSON (default is human-readable text).
@@ -914,6 +1003,9 @@ exit-code contract designed for one-line .github/workflows entries.
 Flags:
   --all                   Run every playbook.
   --scope <type>          Filter: system | code | service | cross-cutting.
+  --required <ids>        Comma-separated playbook ids that MUST run, even if
+                          scope-detection would exclude them. Fails if a
+                          required id is unknown.
   (no flag)               Auto-detect scopes from cwd (same logic as run).
   --evidence <file>       Submission bundle (multi-playbook shape).
   --evidence-dir <dir>    Read <playbook-id>.json files from a directory.
@@ -921,11 +1013,77 @@ Flags:
   --block-on-jurisdiction-clock
                           Fail when any close.notification_actions started a
                           regulatory clock (GDPR 72h, HIPAA breach, etc.).
-  --pretty                Indented JSON output.
+  --format <fmt>          Output shape. Supported: json (default, single-line),
+                          summary (5-field digest), markdown (human digest).
+                          Bundles (csaf-2.0/sarif/openvex) live on per-run
+                          attestations, not the aggregate ci verdict.
+  --json                  Force single-line JSON (overrides any TTY heuristics).
+  --pretty                Indented JSON output (implies --json).
+
+Exit codes:
+  0  PASS                  All scoped playbooks ran and verdict is clean.
+  1  Framework error       Runner threw, unreadable evidence, etc.
+  2  FAIL (detected)       At least one playbook returned
+                           classification=detected, OR rwep ≥ escalate, OR
+                           --max-rwep cap exceeded.
+  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.
 
-Exit codes: 0 PASS, 2 FAIL (detected | rwep ≥ cap | clock started w/ block flag).
 Output: verb, session_id, playbooks_run, summary{total, detected,
-max_rwep_observed, jurisdiction_clocks_started, verdict}, results[].`,
+max_rwep_observed, jurisdiction_clocks_started, verdict, fail_reasons[]},
+results[].`,
+    brief: `brief [playbook] — unified info doc (v0.11.0).
+
+Collapses the three info-only phases plan + govern + direct + look into a
+single document. Phases 1-3 of the seven-phase contract are entirely
+informational; brief reads them in one CLI invocation instead of three.
+
+Modes:
+  brief                   Auto-detect playbooks for the cwd. Returns a list.
+  brief <playbook>        Single-playbook brief with jurisdiction obligations
+                          + threat context + preconditions + artifacts +
+                          indicators.
+  brief --all             Every shipped playbook.
+  brief --scope <type>    Filter: system | code | service | cross-cutting.
+  brief <pb> --phase <p>  Emit only the named phase (govern | direct | look).
+                          Compat for legacy callers.
+
+Flags:
+  --directives            Expand directive metadata per playbook.
+  --pretty                Indented JSON output.
+  --json                  Force single-line JSON.
+
+Output (single-playbook): playbook_id, directives[], jurisdiction_obligations[],
+threat_context, preconditions[], artifacts[], indicators[].`,
+    lint: `lint <playbook> <evidence-file> — pre-flight check submission shape.
+
+Validates the submission JSON against the playbook's expected indicators /
+preconditions / artifacts WITHOUT executing detect/analyze/validate/close.
+Lets the AI iterate on its evidence before going through phases 4-7.
+
+Args / flags:
+  <playbook>              Playbook id. Required.
+  <evidence-file>         Submission JSON path. Required.
+  --pretty                Indented JSON output.
+
+Output categories: ok, missing_required, missing_required_artifact,
+unknown_keys, type_mismatch, suggestions.`,
+    "verify-attestation": `verify-attestation <session-id> — alias for \`attest verify\`.
+
+See \`exceptd attest --help\` for the full attest verb. This alias matches
+the historical verify-attestation entry-point name used by some downstream
+consumers.
+
+Flags: --pretty.`,
+    "run-all": `run-all — alias for \`run --all\`.
+
+Identical exit-code and output contract as \`run --all\`. Maintained for
+operators who script the verb form rather than the flag.
+
+See \`exceptd run --help\` for the full flag list.`,
   };
   process.stdout.write((cmds[verb] || `${verb} — no per-verb help available; see \`exceptd help\` for the full list.`) + "\n");
 }
@@ -1080,6 +1238,18 @@ function cmdBrief(runner, args, runOpts, pretty) {
   const playbookId = args._[0];
   const onlyPhase = args.phase || null;
 
+  // v0.12.9 (P2 #7 from production smoke): refuse garbage values to --phase.
+  // Pre-v0.12.9 `brief secrets --phase foo` silently accepted any string and
+  // emitted the full brief — operators got no signal the flag was misused.
+  // The legacy-compat surface is exactly the three v0.10.x verb names
+  // (govern | direct | look); anything else is a typo or a misunderstanding.
+  if (onlyPhase != null) {
+    const ACCEPTED_PHASES = ["govern", "direct", "look"];
+    if (!ACCEPTED_PHASES.includes(onlyPhase)) {
+      return emitError(`brief: --phase "${onlyPhase}" not in accepted set ${JSON.stringify(ACCEPTED_PHASES)}.`, { verb: "brief", provided: onlyPhase }, pretty);
+    }
+  }
+
   if (!playbookId || args.all) {
     // Multi-playbook brief (replaces `plan`). Reuses cmdPlan output shape.
     return cmdPlan(runner, args, runOpts, pretty);
@@ -1562,13 +1732,20 @@ function cmdRun(runner, args, runOpts, pretty) {
 
     emit(result, pretty);
 
+    // v0.12.8: use process.exitCode + return instead of process.exit() so
+    // buffered async stdout (which `emit` writes to) is allowed to drain
+    // before the event loop ends. v0.11.10 (#100) is the canonical class:
+    // process.exit(N) immediately after a stdout write can truncate output
+    // under piped consumers (CI runners, jq, test harnesses).
     if (classification === "detected") {
       process.stderr.write(`[exceptd run --ci] FAIL: classification=detected rwep=${adjusted} threshold=${threshold}\n`);
-      process.exit(2);
+      process.exitCode = 2;
+      return;
     }
     if (classification === "inconclusive" && escalate) {
       process.stderr.write(`[exceptd run --ci] FAIL: classification=inconclusive AND rwep=${adjusted} >= threshold=${threshold}\n`);
-      process.exit(2);
+      process.exitCode = 2;
+      return;
     }
     if (classification === "inconclusive") {
       process.stderr.write(`[exceptd run --ci] PASS+WARN: classification=inconclusive rwep=${adjusted} < threshold=${threshold} (visibility gap)\n`);
@@ -1667,10 +1844,19 @@ function cmdRun(runner, args, runOpts, pretty) {
     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`);
     const cves = obj.phases?.analyze?.matched_cves || [];
+    const baseline = obj.phases?.analyze?.catalog_baseline_cves || [];
     if (cves.length) {
       lines.push(`\nMatched CVEs (${cves.length}):`);
-      for (const c of cves.slice(0, 6)) lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev}  ${c.active_exploitation || ""}`);
+      for (const c of cves.slice(0, 6)) {
+        const via = Array.isArray(c.correlated_via) && c.correlated_via.length ? `  via ${c.correlated_via[0]}${c.correlated_via.length > 1 ? ` (+${c.correlated_via.length - 1})` : ""}` : "";
+        lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev}  ${c.active_exploitation || ""}${via}`);
+      }
       if (cves.length > 6) lines.push(`  … ${cves.length - 6} more`);
+    } else if (baseline.length) {
+      // No evidence correlated to any CVE — clarify rather than implying the
+      // operator is affected by the catalog enumeration. Pre-fix output read
+      // like a hit list; explicit zero + scan-coverage callout fixes that.
+      lines.push(`\nNo CVEs correlated to your evidence. Playbook catalog (informational): ${baseline.length} CVE(s) this playbook scans for.`);
     }
     const indicators = obj.phases?.detect?.indicators || [];
     const hits = indicators.filter(i => i.verdict === "hit");
@@ -1693,7 +1879,16 @@ function cmdRun(runner, args, runOpts, pretty) {
     const issues = obj.preflight_issues || [];
     if (issues.length) {
       lines.push(`\nPreflight warnings (${issues.length}):`);
-      for (const i of issues) lines.push(`  [${i.on_fail}] ${i.id}: ${i.check || ""}`);
+      // v0.12.9 (P3 #12 from production smoke): handle preconditions without
+      // an `on_fail` field (precondition.check was satisfied trivially or the
+      // playbook omits the field). Pre-v0.12.9 these rendered as `[undefined]
+      // <id>:`. Now: omit the bracket when on_fail is absent, and fall back
+      // to the description if `check` is missing too.
+      for (const i of issues) {
+        const tag = i.on_fail ? `[${i.on_fail}] ` : "";
+        const detail = i.check || i.description || i.reason || "(no detail)";
+        lines.push(`  ${tag}${i.id}: ${detail}`);
+      }
     }
     lines.push(`\nFull structured result: --json (or --pretty for indented).`);
     return lines.join("\n");
@@ -1798,9 +1993,10 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
   // v0.11.9 (#100): cmdRunMulti exits non-zero when any individual run
   // returned ok:false. Pre-0.11.9 the aggregate result had {ok:false} in
   // the body but exit code stayed 0 — CI gates couldn't distinguish "ran
-  // clean" from "blocked." Now matches cmdRun's single-playbook contract.
+  // clean" from "blocked." v0.12.8: use exitCode (not process.exit()) so
+  // the aggregate JSON emitted above is allowed to fully drain.
   const anyBlocked = results.some(r => r.ok === false);
-  if (anyBlocked) process.exit(1);
+  if (anyBlocked) { process.exitCode = 1; return; }
 }
 
 function cmdIngest(runner, args, runOpts, pretty) {
@@ -1835,28 +2031,38 @@ function cmdIngest(runner, args, runOpts, pretty) {
 
   const result = runner.run(playbookId, directiveId, cleanedSubmission, runOpts);
 
+  // v0.12.8: route ingest's attestation persistence through persistAttestation
+  // — the same path cmdRun + cmdRunMulti use — so the session-id collision
+  // refusal AND the Ed25519 sidecar signing both apply. Pre-v0.12.8 ingest
+  // had its own inline writeFileSync with neither check, meaning two ingest
+  // calls with the same session-id silently clobbered the audit trail and no
+  // .sig sidecar was written.
   if (result && result.ok && result.session_id) {
-    try {
-      const dir = path.join(resolveAttestationRoot(runOpts), result.session_id);
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(
-        path.join(dir, "attestation.json"),
-        JSON.stringify({
-          session_id: result.session_id,
-          playbook_id: result.playbook_id,
-          directive_id: result.directive_id,
-          evidence_hash: result.evidence_hash,
-          submission: cleanedSubmission,
-          run_opts: { airGap: runOpts.airGap, forceStale: runOpts.forceStale, mode: runOpts.mode },
-          captured_at: new Date().toISOString(),
-        }, null, 2)
-      );
-    } catch { /* non-fatal */ }
+    const persisted = persistAttestation({
+      sessionId: result.session_id,
+      playbookId: result.playbook_id,
+      directiveId: result.directive_id,
+      evidenceHash: result.evidence_hash,
+      operator: runOpts.operator,
+      operatorConsent: runOpts.operator_consent,
+      submission: cleanedSubmission,
+      runOpts,
+      forceOverwrite: !!args["force-overwrite"],
+      filename: "attestation.json",
+    });
+    if (!persisted.ok) {
+      // Surface the collision; do not silently clobber.
+      return emitError(persisted.error, { session_id: result.session_id, existing_path: persisted.existingPath }, pretty);
+    }
+    if (persisted.prior_session_id) {
+      result.attestation_persist = { ok: true, prior_session_id: persisted.prior_session_id, overwrote_at: persisted.overwrote_at };
+    }
   }
 
   if (result && result.ok === false) {
     process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   emit(result, pretty);
 }
@@ -1981,6 +2187,15 @@ function persistAttestation(args) {
 function maybeSignAttestation(filePath) {
   const crypto = require("crypto");
   const sigPath = filePath + ".sig";
+  // v0.12.9 (P2 #3 from production smoke + codex P1 PR #4 review): keep the
+  // sign key aligned with the VERIFY key. `attest verify` checks signatures
+  // against PKG_ROOT/keys/public.pem; if we sign with cwd/.keys/private.pem
+  // (e.g. the maintainer's repo-local keypair) the resulting `.sig` will
+  // verify INVALID and report a false tamper signal on every freshly-written
+  // attestation. PKG_ROOT-only resolution is the right answer; the original
+  // smoke report's "doctor finds key, run does not" gap is fixed in `doctor`
+  // (reporting only PKG_ROOT now), not by making `run` follow a cwd key the
+  // verifier doesn't trust.
   const privKeyPath = path.join(PKG_ROOT, ".keys", "private.pem");
   const content = fs.readFileSync(filePath, "utf8");
   // One-time-per-process unsigned warning so cron jobs don't spam stderr.
@@ -2714,6 +2929,46 @@ function cmdDoctor(runner, args, runOpts, pretty) {
         ...(ok ? {} : { exit_code: res.status, raw: text.slice(0, 500) }),
       };
       if (!ok) issues.push("signatures");
+
+      // v0.12.9 (P3 #10 from production smoke): also run the shipped-tarball
+      // round-trip gate (sign + pack + extract + verify) when the operator
+      // opts in via --shipped-tarball. This is the v0.12.3 verify-as-shipped
+      // gate that closed the v0.11.x → v0.12.4 signature regression class
+      // (source-tree verify passed; shipped-tarball verify failed). It's
+      // opt-in because npm pack adds ~5-10s and creates tempdir churn —
+      // routine `doctor --signatures` stays fast.
+      if (args["shipped-tarball"]) {
+        try {
+          const tarballScript = path.join(PKG_ROOT, "scripts", "verify-shipped-tarball.js");
+          if (fs.existsSync(tarballScript)) {
+            const tRes = spawnSync(process.execPath, [tarballScript], {
+              encoding: "utf8",
+              cwd: PKG_ROOT,
+              timeout: 120000,
+            });
+            const tText = (tRes.stdout || "") + (tRes.stderr || "");
+            const tOk = tRes.status === 0;
+            const tMatch = tText.match(/(\d+)\/(\d+)\s+pass,\s+(\d+)\s+fail/i);
+            checks.signatures.shipped_tarball = {
+              ok: tOk,
+              skills_passed: tMatch ? Number(tMatch[1]) : null,
+              skills_total: tMatch ? Number(tMatch[2]) : null,
+              skills_failed: tMatch ? Number(tMatch[3]) : null,
+              ...(tOk ? {} : { exit_code: tRes.status, raw: tText.slice(-500) }),
+            };
+            if (!tOk) issues.push("signatures.shipped_tarball");
+          } else {
+            checks.signatures.shipped_tarball = {
+              ok: null,
+              skipped: true,
+              reason: "scripts/verify-shipped-tarball.js not present (likely an installed package, not a source checkout). The tarball-verify gate runs at release time; routine integrity is covered by `--signatures`.",
+            };
+          }
+        } catch (e) {
+          checks.signatures.shipped_tarball = { ok: false, error: e.message };
+          issues.push("signatures.shipped_tarball");
+        }
+      }
     } catch (e) {
       checks.signatures = { ok: false, error: e.message };
       issues.push("signatures");
@@ -2815,9 +3070,14 @@ function cmdDoctor(runner, args, runOpts, pretty) {
 
   if (runSigning) {
     try {
-      const keyPath = path.join(process.cwd(), ".keys", "private.pem");
-      const fallback = path.join(PKG_ROOT, ".keys", "private.pem");
-      const present = fs.existsSync(keyPath) || fs.existsSync(fallback);
+      // v0.12.9 codex P1 (PR #4): report only PKG_ROOT — that's the path
+      // maybeSignAttestation() and `attest verify` actually use. Pre-v0.12.9
+      // doctor also reported cwd-resident keys as present, which gave a
+      // false-positive "signing enabled" signal when the operator's cwd
+      // key was misaligned with the PKG_ROOT-resident public key used at
+      // verify time.
+      const keyPath = path.join(PKG_ROOT, ".keys", "private.pem");
+      const present = fs.existsSync(keyPath);
       // Bug #61 (v0.11.2): signing-status missing key is a real WARNING. The
       // attestation pipeline writes unsigned files when this is absent, which
       // operators reading the attestation later cannot verify for authenticity.
@@ -2902,10 +3162,9 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     });
     if (r.status === 0) {
       // Re-verify the private key is now present so the JSON output reflects
-      // the fix.
-      const keyPath = path.join(process.cwd(), ".keys", "private.pem");
-      const fallback = path.join(PKG_ROOT, ".keys", "private.pem");
-      const present = fs.existsSync(keyPath) || fs.existsSync(fallback);
+      // the fix. v0.12.9 codex P1: PKG_ROOT-only (sign + verify use this path).
+      const keyPath = path.join(PKG_ROOT, ".keys", "private.pem");
+      const present = fs.existsSync(keyPath);
       checks.signing = { ok: present, severity: present ? "info" : "warn", private_key_present: present, can_sign_attestations: present };
       out.checks = checks;
       out.summary.fix_applied = "ed25519_keypair_generated";
@@ -2954,6 +3213,35 @@ function cmdDoctor(runner, args, runOpts, pretty) {
       ? `RFC catalog: ${c.total ?? "?"} entries, drift ${c.drift ?? 0}`
       : `RFC catalog FAILED (exit=${c.exit_code ?? "?"})`
   );
+  // v0.12.9 (P3 #11 from production smoke): render registry-check in text mode.
+  // Pre-v0.12.9 --registry-check populated checks.registry only in the JSON
+  // output; operators in text mode had to add --json to see if the flag did
+  // anything. Now the line surfaces in the human checklist.
+  mark(checks.registry, c => {
+    if (c.skipped) return `npm registry check: skipped (${c.reason || "unknown reason"})`;
+    if (!c.ok && !c.same && c.behind) {
+      const days = c.days_since_latest_publish != null ? `${c.days_since_latest_publish}d` : "?";
+      return `npm registry: local v${c.local_version ?? "?"} BEHIND published v${c.published_version ?? "?"} (${days})`;
+    }
+    if (c.same) {
+      return `npm registry: local v${c.local_version ?? "?"} == published v${c.published_version ?? "?"} (current)`;
+    }
+    if (c.ahead) {
+      return `npm registry: local v${c.local_version ?? "?"} AHEAD of published v${c.published_version ?? "?"} (unreleased / dev install)`;
+    }
+    return `npm registry: check returned no comparison (raw exit=${c.exit_code ?? "?"})`;
+  });
+  // v0.12.9 (P3 #10): surface shipped_tarball sub-check when --shipped-tarball was used.
+  if (checks.signatures?.shipped_tarball) {
+    const st = checks.signatures.shipped_tarball;
+    if (st.skipped) {
+      lines.push(`  [info] shipped tarball verify: skipped (${st.reason})`);
+    } else if (st.ok) {
+      lines.push(`  [ok] shipped tarball verify: ${st.skills_passed ?? "?"}/${st.skills_total ?? "?"} skills pass on extracted tarball`);
+    } else {
+      lines.push(`  [!!] shipped tarball verify FAILED: ${st.skills_failed ?? "?"}/${st.skills_total ?? "?"} skills fail (exit=${st.exit_code ?? "?"})`);
+    }
+  }
   if (checks.signing) {
     if (checks.signing.private_key_present) {
       lines.push(`  [ok] attestation signing: private key present (.keys/private.pem)`);
@@ -3196,13 +3484,22 @@ function cmdAiRun(runner, args, runOpts, pretty) {
   let handled = false;
   let buf = "";
 
+  // v0.12.8: every writeLine() in this handler writes to stdout. Replacing
+  // process.exit() with exitCode + closing stdin lets the JSONL frames
+  // drain before the event loop ends. `handled` plus process.stdin.pause()
+  // prevents further callbacks from re-entering the handler.
+  const finish = (code) => {
+    process.exitCode = code;
+    try { process.stdin.pause(); } catch { /* non-fatal */ }
+  };
   const handleLine = (line) => {
     if (handled) return;
     let parsed;
     try { parsed = JSON.parse(line); }
     catch (e) {
+      handled = true;
       writeLine({ event: "error", reason: `invalid JSON on stdin: ${e.message}`, line_preview: line.slice(0, 120) });
-      process.exit(1);
+      return finish(1);
     }
     if (!parsed || parsed.event !== "evidence" || !parsed.payload) {
       // Ignore non-evidence chatter so the host AI can interleave its own
@@ -3216,18 +3513,18 @@ function cmdAiRun(runner, args, runOpts, pretty) {
       result = runner.run(playbookId, directiveId, submission, runOpts);
     } catch (e) {
       writeLine({ event: "error", reason: `runner threw: ${e.message}` });
-      process.exit(1);
+      return finish(1);
     }
     if (!result || result.ok === false) {
       writeLine({ event: "error", reason: result?.reason || "runner returned ok:false", result });
-      process.exit(1);
+      return finish(1);
     }
     writeLine({ phase: "detect", ...result.phases?.detect });
     writeLine({ phase: "analyze", ...result.phases?.analyze });
     writeLine({ phase: "validate", ...result.phases?.validate });
     writeLine({ phase: "close", ...result.phases?.close });
     writeLine({ event: "done", ok: true, session_id: result.session_id, evidence_hash: result.evidence_hash });
-    process.exit(0);
+    return finish(0);
   };
 
   // Handle empty/closed stdin: emit a hint then exit cleanly so AI agents
@@ -3235,7 +3532,8 @@ function cmdAiRun(runner, args, runOpts, pretty) {
   // a hung process.
   if (process.stdin.isTTY) {
     writeLine({ event: "error", reason: "ai-run streaming mode requires evidence on stdin; pipe {\"event\":\"evidence\",\"payload\":{...}} or use --no-stream." });
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 
   process.stdin.on("data", (chunk) => {
@@ -3270,7 +3568,8 @@ function cmdAiRun(runner, args, runOpts, pretty) {
         } catch { /* fall through to error */ }
       }
       writeLine({ event: "error", reason: "stdin closed without an evidence event. Pipe `{\"event\":\"evidence\",\"payload\":{...}}` for streaming mode, or pass --no-stream + --evidence <file> for single-shot." });
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   });
 
@@ -3574,17 +3873,65 @@ function cmdCi(runner, args, runOpts, pretty) {
   const rwepValues = results.map(r => r.phases?.analyze?.rwep?.adjusted ?? 0);
   const maxRwepObserved = rwepValues.length ? Math.max(...rwepValues) : 0;
 
+  // v0.12.9 (P1 #2 from production smoke): reconcile verdict with exit code.
+  // Pre-v0.12.9 the no-evidence-all-inconclusive path emitted verdict="PASS"
+  // but the process exited 3 ("ran but no evidence"). CI consumers reading
+  // exit code only failed a PASS run; consumers reading verdict only passed
+  // a no-data run. Now compute the verdict up-front to match the exit-code
+  // matrix (BLOCKED > FAIL > NO_EVIDENCE > PASS) so both surfaces agree.
+  const suppliedEvidenceForVerdict = args.evidence || args["evidence-dir"];
+  const blockedCount = results.filter(r => r && r.ok === false).length;
+  const inconclusiveCount = results.filter(r => r.phases?.detect?.classification === "inconclusive").length;
+  const totalForVerdict = results.length;
+  const noEvidenceAllInconclusive = !suppliedEvidenceForVerdict && totalForVerdict > 0 && inconclusiveCount === totalForVerdict;
+  const computedVerdict = blockedCount > 0
+    ? "BLOCKED"
+    : 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
+  // framework_gap_mapping per result; pre-v0.12.9 ci never aggregated them,
+  // so operators got individual-playbook results only. Now: top-level
+  // framework_gap_rollup lists each {framework, claimed_control} once with
+  // the set of playbooks that flagged it — single-glance "what gaps did this
+  // gate uncover across the scoped playbooks."
+  const gapRollupMap = new Map();
+  for (const r of results) {
+    const gaps = r.phases?.analyze?.framework_gap_mapping || [];
+    for (const g of gaps) {
+      const key = `${g.framework || "unknown"}::${g.claimed_control || "unspecified"}`;
+      const existing = gapRollupMap.get(key);
+      if (existing) {
+        if (!existing.playbooks.includes(r.playbook_id)) existing.playbooks.push(r.playbook_id);
+      } else {
+        gapRollupMap.set(key, {
+          framework: g.framework || null,
+          claimed_control: g.claimed_control || null,
+          why_insufficient: g.why_insufficient || null,
+          playbooks: [r.playbook_id],
+        });
+      }
+    }
+  }
+  const frameworkGapRollup = [...gapRollupMap.values()];
+
   const summary = {
     total: results.length,
     detected: results.filter(r => r.phases?.detect?.classification === "detected").length,
-    inconclusive: results.filter(r => r.phases?.detect?.classification === "inconclusive").length,
+    inconclusive: inconclusiveCount,
     not_detected: results.filter(r => ["not_detected", "clean"].includes(r.phases?.detect?.classification)).length,
-    blocked: results.filter(r => r && r.ok === false).length,
+    blocked: blockedCount,
     max_rwep_observed: maxRwepObserved,
     jurisdiction_clocks_started: results
       .flatMap(r => r.phases?.close?.notification_actions || [])
       .filter(n => n && n.clock_started_at != null).length,
-    verdict: fail ? "FAIL" : "PASS",
+    framework_gap_rollup: frameworkGapRollup,
+    framework_gap_count: frameworkGapRollup.length,
+    verdict: computedVerdict,
     fail_reasons: failReasons,
   };