@blamejs/exceptd-skills 0.12.40 → 0.13.0

package/data/zeroday-lessons.json

@@ -2,6 +2,7 @@
   "_meta": {
     "schema_version": "1.1.0",
     "last_updated": "2026-05-15",
+    "last_threat_review": "2026-05-17",
     "purpose": "Zero-day learning loop output. Each entry maps a CVE to: attack vector, defense chain analysis, framework coverage, new control requirements generated, and exposure scoring. v1.1.0 (2026-05-15): every entry now carries ai_discovered_zeroday boolean + ai_discovery_source enum + ai_discovery_date + ai_assist_factor ladder, per AGENTS.md Hard Rule #7.",
     "note": "Never delete entries. Closed gaps are marked status: closed. History is data.",
     "tlp": "CLEAR",

package/lib/cross-ref-api.js

@@ -37,56 +37,76 @@ const _cache = new Map();
 // can inspect.
 const _loadErrors = [];
 
-function _statMtime(p) {
-  try { return fs.statSync(p).mtimeMs; }
-  catch { return null; }
+/**
+ * v0.13.0: cache invalidation is keyed on (mtimeMs, size). Pre-v0.13 it
+ * was mtime-only, but on filesystems with 1-2s mtime granularity
+ * (FAT32, HFS+ pre-APFS, NFSv3, Docker bind-mounts that proxy mtime)
+ * a rapid refresh-then-reload within the same second served stale
+ * cached data. Adding `size` catches every content change that affects
+ * byte count; mtimeMs catches in-place rewrites that preserve byte
+ * count. Together they cover every realistic catalog-mutation path
+ * without the cost of a per-load SHA computation. SHA-based tier is
+ * available via _statContentHash() when callers want full invalidation
+ * (e.g. long-running daemons against append-only catalogs).
+ */
+function _statSignature(p) {
+  try {
+    const s = fs.statSync(p);
+    return { mtime: s.mtimeMs, size: s.size };
+  } catch { return null; }
+}
+
+function _signatureEquals(a, b) {
+  if (a === null && b === null) return true;
+  if (a === null || b === null) return false;
+  return a.mtime === b.mtime && a.size === b.size;
 }
 
 function loadCatalog(filename) {
   const full = path.join(DATA_DIR, filename);
-  const mtime = _statMtime(full);
+  const sig = _statSignature(full);
   const cached = _cache.get(filename);
-  if (cached && (mtime === null || cached.mtime === mtime)) {
+  if (cached && (sig === null || _signatureEquals(cached.sig, sig))) {
     return cached.value;
   }
   if (!fs.existsSync(full)) {
-    _cache.set(filename, { value: {}, mtime });
+    _cache.set(filename, { value: {}, sig });
     return {};
   }
   try {
     const parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
-    _cache.set(filename, { value: parsed, mtime });
+    _cache.set(filename, { value: parsed, sig });
     return parsed;
   } catch (e) {
     _loadErrors.push({ kind: 'catalog', file: filename, error: e.message });
     const stub = {};
     Object.defineProperty(stub, '_loadError', { value: e.message, enumerable: false });
-    _cache.set(filename, { value: stub, mtime });
+    _cache.set(filename, { value: stub, sig });
     return stub;
   }
 }
 
 function loadIndex(filename) {
   const full = path.join(INDEX_DIR, filename);
-  const mtime = _statMtime(full);
+  const sig = _statSignature(full);
   const key = 'idx:' + filename;
   const cached = _cache.get(key);
-  if (cached && (mtime === null || cached.mtime === mtime)) {
+  if (cached && (sig === null || _signatureEquals(cached.sig, sig))) {
     return cached.value;
   }
   if (!fs.existsSync(full)) {
-    _cache.set(key, { value: {}, mtime });
+    _cache.set(key, { value: {}, sig });
     return {};
   }
   try {
     const parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
-    _cache.set(key, { value: parsed, mtime });
+    _cache.set(key, { value: parsed, sig });
     return parsed;
   } catch (e) {
     _loadErrors.push({ kind: 'index', file: filename, error: e.message });
     const stub = {};
     Object.defineProperty(stub, '_loadError', { value: e.message, enumerable: false });
-    _cache.set(key, { value: stub, mtime });
+    _cache.set(key, { value: stub, sig });
     return stub;
   }
 }

package/lib/cve-curation.js

@@ -637,7 +637,18 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
 
 function writeJsonAtomic(p, obj) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  // v0.13.0: fsync the tmp file before rename so a power loss between
+  // write and rename leaves the durable destination intact. Without
+  // fsync the data sits in the OS page cache and the rename succeeds
+  // atomically, but the renamed file may be zero-length / partial on
+  // crash. Open + write + fsync + close + rename is the durable idiom.
+  const fd = fs.openSync(tmpPath, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
   try {
     fs.renameSync(tmpPath, p);
   } catch (err) {

package/lib/exit-codes.js

@@ -66,9 +66,38 @@ function listExitCodes() {
   }));
 }
 
+/**
+ * Set the process exit code WITHOUT calling process.exit(). Returns to the
+ * caller so any pending stdout/stderr writes drain on natural event-loop
+ * shutdown.
+ *
+ * `process.exit(N)` terminates the process synchronously, which truncates
+ * buffered async stdout when stdout is piped (CI, test harnesses, --json
+ * consumers). The v0.11.10 CI #100 fix established the exitCode-then-return
+ * idiom for that reason; every subsequent regression that re-introduced
+ * bare process.exit() in the dispatch surface was the same class of bug.
+ *
+ * Callers SHOULD prefer this helper for any exit-after-stdout-write path.
+ * Long-running daemons / tests that need synchronous termination can still
+ * use process.exit() directly — that's intentional and not what this guards.
+ *
+ * @param {number} code Exit code (use the EXIT_CODES constants)
+ * @returns {void}
+ */
+function safeExit(code) {
+  // Only override exitCode when it isn't already set to a non-zero value —
+  // matches the emit() ok:false fallback contract so a caller that already
+  // set BLOCKED (4) before emit() doesn't get overwritten by a later
+  // GENERIC_FAILURE (1).
+  if (!process.exitCode || process.exitCode === 0) {
+    process.exitCode = code;
+  }
+}
+
 module.exports = {
   EXIT_CODES,
   EXIT_CODE_DESCRIPTIONS,
   exitCodeName,
   listExitCodes,
+  safeExit,
 };

package/lib/lint-skills.js

@@ -243,6 +243,11 @@ function extractFrontmatterBlock(content) {
 /* Validate frontmatter object against the codified schema rules. */
 function validateFrontmatter(fm, skillName) {
   const errors = [];
+  // v0.13.0: validateFrontmatter now ALSO surfaces warnings (e.g. the
+  // last_threat_review 180-day soft cap). Return signature changes from
+  // `string[]` to `{ errors: string[], warnings: string[] }` — callers
+  // updated accordingly.
+  const warnings = [];
 
   for (const key of Object.keys(fm)) {
     if (!ALL_KNOWN_FIELDS.has(key)) {
@@ -351,10 +356,25 @@ function validateFrontmatter(fm, skillName) {
       errors.push(
         `frontmatter.last_threat_review "${fm.last_threat_review}" is not an ISO date (YYYY-MM-DD)`,
       );
+    } else {
+      // v0.13.0: Hard Rule #8 forcing function — refuse skills whose
+      // last_threat_review is older than the staleness threshold.
+      // 180-day soft cap (warn), 365-day hard cap (fail). Operators on
+      // older releases who don't refresh fall off the supported window.
+      const days = Math.floor((Date.now() - Date.parse(fm.last_threat_review + 'T00:00:00Z')) / (24 * 60 * 60 * 1000));
+      if (days > 365) {
+        errors.push(
+          `frontmatter.last_threat_review "${fm.last_threat_review}" is ${days} days old — Hard Rule #8 staleness gate (hard fail at >365 days). Refresh the threat review against current intel and bump the date.`,
+        );
+      } else if (days > 180) {
+        warnings.push(
+          `frontmatter.last_threat_review "${fm.last_threat_review}" is ${days} days old — Hard Rule #8 staleness warning (warn at >180 days, hard fail at >365). Schedule a review.`,
+        );
+      }
     }
   }
 
-  return errors;
+  return { errors, warnings };
 }
 
 /* L1 — Heading-anchored section detection.
@@ -460,7 +480,9 @@ function lintSkill(entry, ctx) {
     return { name: entry.name, errors: skillErrors, warnings: skillWarnings };
   }
 
-  skillErrors.push(...validateFrontmatter(fm, entry.name));
+  const fmResult = validateFrontmatter(fm, entry.name);
+  skillErrors.push(...fmResult.errors);
+  skillWarnings.push(...fmResult.warnings);
 
   if (Array.isArray(fm.data_deps)) {
     for (const dep of fm.data_deps) {
@@ -759,7 +781,7 @@ function main() {
     for (const o of orphans) {
       console.log(`FAIL  <orphan>`);
       console.log(`        - skill.md exists on disk but not in manifest: ${o}`);
-      console.log(`          fix: re-run \`node lib/sign.js sign-all\` after adding it to manifest.json, OR delete the orphan directory`);
+      console.log(`          fix: re-run sign-all (\`node $(exceptd path)/lib/sign.js sign-all\` from a contributor checkout) after adding it to manifest.json, OR delete the orphan directory`);
     }
     // P4 — air-gap completeness lint over data/playbooks/*.json.
     airGapWarnings = lintPlaybookAirGap();

package/lib/playbook-runner.js

@@ -1679,7 +1679,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     evidencePackage.signature_algorithm = 'HMAC-SHA256-session-key';
   } else if (evidencePackage && evidencePackage.signed) {
     evidencePackage.signature = null;
-    evidencePackage.signature_pending = 'No session_key provided. Sign with Ed25519 via `node lib/sign.js sign-evidence <bundle.json>` post-emit.';
+    evidencePackage.signature_pending = 'No session_key provided. Sign with Ed25519 via `node $(exceptd path)/lib/sign.js sign-evidence <bundle.json>` post-emit (contributor checkout) or `exceptd doctor --fix` to enable signing.';
   }
 
   // learning_loop lesson
@@ -2830,13 +2830,17 @@ function normalizeSubmission(submission, playbook) {
   // which confuses detect()'s indicator-id lookup. Strip and log instead.
   if (submission.signal_overrides !== undefined && submission.signal_overrides !== null
       && (typeof submission.signal_overrides !== 'object' || Array.isArray(submission.signal_overrides))) {
-    if (!submission._runErrors) submission._runErrors = [];
-    pushRunError(submission._runErrors, {
+    // Clone before mutating _runErrors so a frozen / shared input
+    // submission isn't modified in place. Pre-fix a caller passing a
+    // frozen submission (Object.freeze for safety, or a shared reference
+    // across parallel runs) threw uncaught on the _runErrors push.
+    const carry = Array.isArray(submission._runErrors) ? submission._runErrors.slice() : [];
+    pushRunError(carry, {
       kind: 'signal_overrides_invalid',
       supplied_type: Array.isArray(submission.signal_overrides) ? 'array' : typeof submission.signal_overrides,
       reason: 'signal_overrides must be a plain object mapping indicator-id → verdict.'
     }, { dedupeKey: e => String(e.supplied_type) });
-    submission = { ...submission, signal_overrides: {} };
+    submission = { ...submission, signal_overrides: {}, _runErrors: carry };
   }
 
   // v0.11.3 #71 fix: the CLI may inject `signals._bundle_formats` before

package/lib/refresh-external.js

@@ -1066,7 +1066,16 @@ function loadCtx(opts) {
 // worker threads) never collide on the same scratch path.
 function writeJsonAtomic(p, obj) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  // v0.13.0: fsync the tmp file before rename so a power loss between
+  // write and rename leaves the durable destination intact. See the
+  // matching helper in lib/cve-curation.js for the rationale.
+  const fd = fs.openSync(tmpPath, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
   try {
     fs.renameSync(tmpPath, p);
   } catch (err) {

package/lib/scoring.js

@@ -300,7 +300,15 @@ function compare(cveId, catalog, opts) {
   // SLA is insufficient. ±10 is the tightest classifier that still treats
   // ordinary CVSS rounding noise as alignment.
   let explanation = '';
-  if (delta > 10) {
+  // Surface the "no scoring signal" case distinctly from "broadly
+  // aligned". Pre-fix a CVE with rwep_score: 0 AND cvss_score: 0 (e.g.
+  // catalog entry created before scoring backfill) printed "broadly
+  // aligned" — coincidence-passing per the field-present-not-populated
+  // pitfall. Now the operator sees a specific signal pointing at the
+  // catalog gap rather than a false sense of alignment.
+  if ((rwep == null || rwep === 0) && (cvss == null || cvss === 0)) {
+    explanation = 'No scoring signal — both RWEP and CVSS are zero/null. Investigate the catalog entry; this CVE has no usable risk score.';
+  } else if (delta > 10) {
     explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
     const driving = [];
     if (entry.cisa_kev) driving.push('CISA KEV (+25)');
@@ -338,6 +346,54 @@ function compare(cveId, catalog, opts) {
   return out;
 }
 
+/**
+ * v0.13.0: detect rwep_factors shape. The catalog historically stored
+ * factors in two distinct shapes that look identical at the field level:
+ *
+ *   Shape A (raw):    `{ cisa_kev: true, blast_radius: 30, ... }`
+ *     - booleans + integers in their natural form
+ *     - score derives from `scoreCustom(factors)` which applies weights
+ *
+ *   Shape B (post-weight): `{ cisa_kev: 25, blast_radius: 30, ... }`
+ *     - integers in their post-weight contribution (cisa_kev: 25 not true)
+ *     - score = sum of values; no second weight pass
+ *
+ * Mixing shapes inside ONE entry silently breaks the sum invariant —
+ * a CVE with `cisa_kev: true, blast_radius: 30` reports rwep 30 (just
+ * blast_radius summed) when the operator-intended score is 55 (KEV + br).
+ * Until v0.13 nothing caught this; v0.13 adds shape detection that fires
+ * an error when the entry mixes booleans with non-trivial numeric weights.
+ *
+ * Returns 'A' for raw, 'B' for post-weight, 'unknown' for empty/edge
+ * cases, or 'mixed' for the violating case.
+ */
+function detectFactorShape(factors) {
+  if (!factors || typeof factors !== 'object') return 'unknown';
+  const boolFields = ['cisa_kev', 'poc_available', 'ai_assisted_weaponization', 'ai_discovered', 'active_exploitation', 'patch_available', 'live_patch_available', 'patch_required_reboot'];
+  let sawBool = false;
+  let sawWeightedInt = false;
+  for (const [k, v] of Object.entries(factors)) {
+    if (k === 'blast_radius') continue; // always integer in both shapes
+    if (typeof v === 'boolean' || v === null) {
+      sawBool = true;
+    } else if (typeof v === 'number' && Math.abs(v) >= 5 && boolFields.includes(k)) {
+      // Field that's nominally boolean carrying a numeric weight (e.g. 25,
+      // 20, 15) — Shape B signature.
+      sawWeightedInt = true;
+    } else if (typeof v === 'number' && (v === 0 || v === 1) && boolFields.includes(k)) {
+      // 0/1 on a boolean-named field could be either shape; ambiguous, ignore.
+      continue;
+    } else if (typeof v === 'string' && boolFields.includes(k)) {
+      // String values (e.g. active_exploitation: 'confirmed') are Shape A.
+      sawBool = true;
+    }
+  }
+  if (sawBool && sawWeightedInt) return 'mixed';
+  if (sawWeightedInt) return 'B';
+  if (sawBool) return 'A';
+  return 'unknown';
+}
+
 function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
@@ -363,6 +419,13 @@ function validate(catalog) {
     if (entry.live_patch_available && (!entry.live_patch_tools || entry.live_patch_tools.length === 0)) {
       errors.push(`${cveId}: live_patch_available=true but live_patch_tools is empty`);
     }
+    // v0.13.0: detect Shape A / Shape B / mixed factor shape. A 'mixed'
+    // shape would silently break the sum invariant; refuse it. See
+    // detectFactorShape() doc above for the failure mode.
+    const shape = detectFactorShape(entry.rwep_factors);
+    if (shape === 'mixed') {
+      errors.push(`${cveId}: rwep_factors mixes Shape A (booleans) with Shape B (post-weight integers) — sum invariant cannot hold. Convert factors to a single shape.`);
+    }
     const calculatedRwep = scoreCustom({
       cisa_kev: entry.cisa_kev,
       poc_available: entry.poc_available,

package/lib/sign.js

@@ -101,6 +101,22 @@ function generateKeypair({ rotate = false } = {}) {
     process.exit(1);
   }
 
+  // Refuse to silently overwrite an existing public key when no private key
+  // is present. This is the v0.11.x signature-regression class: a host with
+  // a working pubkey but missing privkey running generate-keypair would
+  // produce a fresh pubkey divergent from every shipped signature. Operators
+  // running `exceptd doctor --fix` on a stock install would replace the
+  // shipped keys/public.pem with one whose private half exists only on
+  // their machine — every subsequent verify against shipped signatures fails.
+  // Force the operator to be explicit via --rotate (which signals intent to
+  // re-sign).
+  if (fs.existsSync(PUBLIC_KEY_PATH) && !rotate) {
+    console.error('[sign] Public key already exists at keys/public.pem but no matching private key.');
+    console.error('[sign] Refusing to overwrite the public key — that would orphan every existing signature.');
+    console.error('[sign] If you are setting up a fresh signing identity, pass --rotate to confirm. After --rotate you must re-sign all skills with sign-all.');
+    process.exit(1);
+  }
+
   fs.mkdirSync(KEYS_DIR, { recursive: true, mode: 0o700 });
   fs.mkdirSync(PUBLIC_KEYS_DIR, { recursive: true });
 
@@ -115,20 +131,35 @@ function generateKeypair({ rotate = false } = {}) {
   // on win32, fs.writeFileSync `mode` does not produce
   // a POSIX-style restrictive ACL. Tighten via icacls so other desktop
   // users on the same workstation / CI runner can't read the key.
-  restrictWindowsAcl(PRIVATE_KEY_PATH);
+  const aclHardened = restrictWindowsAcl(PRIVATE_KEY_PATH);
 
   if (rotate) {
-    console.log('[sign] Keypair rotated. All existing signatures are now invalid — run: node lib/sign.js sign-all');
+    console.log('[sign] Keypair rotated. All existing signatures are now invalid — re-sign with sign-all.');
   } else {
     console.log('[sign] Ed25519 keypair generated.');
     console.log(`  Private key: .keys/private.pem (gitignored — do not commit)`);
     console.log(`  Public key:  keys/public.pem (tracked — commit this)`);
   }
+  if (process.platform === 'win32') {
+    console.log(`  Windows ACL hardened: ${aclHardened ? 'yes' : 'NO — other desktop users on this machine may be able to read the private key'}`);
+  }
 
   console.log('\nNext steps:');
-  console.log('  1. node lib/sign.js sign-all    — sign all current skills');
-  console.log('  2. node lib/verify.js           — confirm all signatures');
-  console.log('  3. git add keys/public.pem && git commit -m "add signing public key"');
+  if (rotate) {
+    // After --rotate the private key IS present, so `doctor --fix`'s
+    // missing-key path won't fire. Tell the operator to re-sign
+    // directly. (doctor --fix v0.12.41+ also detects this case and
+    // chains sign-all, so either path converges.)
+    console.log('  1. exceptd doctor --fix     — detects post-rotate stale signatures and chains sign-all');
+    console.log('     (or: node $(exceptd path)/lib/sign.js sign-all   — re-sign directly)');
+    console.log('  2. exceptd doctor           — confirm signatures verify against the new public key');
+    console.log('  3. git add keys/public.pem && git commit -m "rotate signing public key"');
+  } else {
+    console.log('  1. exceptd doctor --fix     — chains sign-all after first key generation');
+    console.log('  2. exceptd doctor           — confirm signatures verify');
+    console.log('  3. git add keys/public.pem && git commit -m "add signing public key"');
+  }
+  return { aclHardened };
 }
 
 /**
@@ -380,11 +411,11 @@ function signCanonicalManifest(manifest, privateKey) {
  * @param {string} targetPath absolute path of the private key file
  */
 function restrictWindowsAcl(targetPath) {
-  if (process.platform !== 'win32') return;
+  if (process.platform !== 'win32') return true;
   const user = process.env.USERNAME;
   if (!user) {
     console.warn('[sign] WARN: USERNAME env var not set — skipping Windows ACL hardening on ' + targetPath);
-    return;
+    return false;
   }
   try {
     execFileSync('icacls', [
@@ -393,6 +424,7 @@ function restrictWindowsAcl(targetPath) {
       '/grant:r',
       `${user}:F`,
     ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    return true;
   } catch (err) {
     console.warn(
       '[sign] WARN: icacls hardening failed on ' + targetPath + ': ' +
@@ -400,6 +432,7 @@ function restrictWindowsAcl(targetPath) {
       ' — the key was written but ACL inheritance was not stripped. ' +
       'Other desktop users on this machine may be able to read it.'
     );
+    return false;
   }
 }
 

package/lib/verify.js

@@ -87,7 +87,7 @@ const EXPECTED_FINGERPRINT_PATH = path.join(ROOT, 'keys', 'EXPECTED_FINGERPRINT'
 function verifyAll() {
   const publicKey = loadPublicKey();
   if (!publicKey) {
-    console.error('[verify] No public key at keys/public.pem — run: node lib/sign.js generate-keypair');
+    console.error('[verify] No public key at keys/public.pem — run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js generate-keypair` from a contributor checkout)');
     return { valid: [], invalid: [], missing_sig: [], missing_file: [], no_key: true };
   }
 
@@ -128,7 +128,7 @@ function verifyOne(skillName) {
  */
 function signAll() {
   const privateKey = loadPrivateKey();
-  if (!privateKey) throw new Error('No private key at .keys/private.pem — run: node lib/sign.js generate-keypair');
+  if (!privateKey) throw new Error('No private key at .keys/private.pem — run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js generate-keypair` from a contributor checkout)');
 
   // P1-4: load the manifest without the signature gate. We're about to
   // mutate the manifest (re-sign skills + re-sign the manifest itself),
@@ -236,7 +236,7 @@ function validateSkillPath(skillPath) {
 
 function verifySkill(skill, publicKey) {
   if (!skill.signature) {
-    return { status: 'missing_sig', reason: 'No Ed25519 signature in manifest — run: node lib/sign.js sign-all' };
+    return { status: 'missing_sig', reason: 'No Ed25519 signature in manifest — run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js sign-all` from a contributor checkout)' };
   }
 
   const skillPath = path.join(ROOT, skill.path);
@@ -447,7 +447,7 @@ function loadManifestValidated() {
     // console.warn would spam stderr per call. Node's emitWarning() with
     // a stable `code` collapses repeated emissions automatically.
     process.emitWarning(
-      'manifest.json has no top-level manifest_signature field. This tarball predates v0.12.17 manifest signing; skills will still be verified but a coordinated rewrite of manifest.json could go undetected. Re-run `node lib/sign.js sign-all` to add the signature.',
+      'manifest.json has no top-level manifest_signature field. This tarball predates v0.12.17 manifest signing; skills will still be verified but a coordinated rewrite of manifest.json could go undetected. Re-run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js sign-all` from a contributor checkout) to add the signature.',
       { code: 'EXCEPTD_MANIFEST_UNSIGNED' }
     );
   } else if (sigResult.status === 'no-key') {
@@ -693,7 +693,7 @@ if (require.main === module) {
   if (arg === 'check-key') {
     const pub = loadPublicKey();
     if (!pub) {
-      console.error('[verify] No public key — run: node lib/sign.js generate-keypair');
+      console.error('[verify] No public key — run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js generate-keypair` from a contributor checkout)');
       process.exit(1);
     }
     console.log('[verify] Public key present at keys/public.pem');