@blamejs/exceptd-skills 0.19.34 → 0.19.35

package/lib/collectors/library-author.js

@@ -14,7 +14,6 @@ const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require(
 
 const COLLECTOR_ID = "library-author";
 
-const DEFAULT_MAX_DEPTH = 6;
 // Applied to the vendor-tree walk, so a cache nested under `vendor/` is not
 // mistaken for vendored provenance state.
 const DEFAULT_EXCLUDES = codeExcludeSet();
@@ -96,7 +95,104 @@ function stripYamlComments(content) {
   return content.replace(/#.*$/gm, "");
 }
 
-function scanPublishWorkflow(content, rel) {
+// Splits comment-stripped workflow text into individual shell commands, so a
+// flag on one install cannot vouch for another. A workflow that hash-pins its
+// build requirements and then resolves its runtime ones must still report the
+// unpinned command, which a whole-file flag test would suppress.
+function shellCommands(code) {
+  const out = [];
+  const lines = code.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    // A real `run:` line is never KBs long; skipping overlong ones keeps a
+    // crafted whitespace run from driving regex backtracking.
+    if (lines[i].length > 4096) continue;
+    // A backslash-continued command is ONE command: a `pip install \` whose
+    // `-r` sits on the next line is otherwise two fragments that each match
+    // nothing. The continuation lines are consumed, never re-emitted.
+    const startLine = i + 1;
+    let raw = lines[i];
+    while (/\\[ \t]*$/.test(raw) && i + 1 < lines.length &&
+           lines[i + 1].length <= 4096 && raw.length <= 8192) {
+      raw = `${raw.replace(/\\[ \t]*$/, " ")}${lines[i + 1].trim()}`;
+      i++;
+    }
+    for (const seg of raw.split(/&&|\|\||[;|]/)) {
+      const cmd = seg.trim();
+      // Comment stripping preserves line breaks, so the index still addresses
+      // the line the command STARTS on in the file an operator opens.
+      if (cmd) out.push({ cmd, line: startLine });
+    }
+  }
+  return out;
+}
+
+// Evidence snippets are read in a report, so a pathological one-line script
+// cannot be pasted in whole.
+function snippetOf(cmd, max = 200) {
+  return cmd.length > max ? `${cmd.slice(0, max)}…` : cmd;
+}
+
+// pip enters hash-checking mode as soon as ONE requirement carries a hash, so
+// `pip install -r <file>` against a `pip-compile --generate-hashes` output is
+// already reproducible. Resolves the named file one level only: a nested `-r`
+// include is not followed, and an unreadable path counts as unhashed.
+// pip accepts the requirement file attached (`-rreq.txt`) as well as separated
+// (`-r req.txt`, `--requirement=req.txt`). One definition for both the detection
+// predicate and the hash lookup: two regexes for one flag drift, and the pair
+// that drifts silently is a command examined by neither.
+// `(?:^|\s)-r` rather than `\b-r` so the `-r` inside `--requirement` is not read
+// as the short form with `equirement...` as its filename.
+const PIP_REQUIREMENT_RE = /(?:^|\s)(?:-r\s*=?\s*|--requirement[=\s]*)['"]?([^'"\s]+)/;
+
+function pipRequirementTarget(cmd) {
+  const m = cmd.match(PIP_REQUIREMENT_RE);
+  return m ? m[1] : null;
+}
+
+// `working-directory:`, at job defaults or on a single step, is what a `run:`
+// command resolves its relative paths against. Collected as a set of candidate
+// bases rather than bound to the step that declared it: the scanner is
+// line-based, so attributing one to a specific command would need the step
+// nesting it does not track.
+// Matches the block form and the flow form (`{ run: { working-directory: x } }`)
+// alike. A key-shaped string inside a `run:` command matches too; that only adds
+// a base that does not resolve, and an unresolvable base is skipped.
+function workingDirectories(code) {
+  const dirs = [];
+  for (const m of code.matchAll(/working-directory:\s*['"]?([^'"\n,}]+?)['"]?\s*(?=$|[,}])/gm)) {
+    const d = m[1].trim();
+    if (d && d !== "." && !path.isAbsolute(d)) dirs.push(d);
+  }
+  return dirs;
+}
+
+// True only when every candidate that EXISTS is hash-pinned, and at least one
+// does. Requiring all of them keeps a hashed copy in one working directory from
+// vouching for an unhashed copy in another — over-suppression here reports an
+// unpinned release as reproducible, which is the direction that costs something.
+// A target that resolves nowhere stays unproven, so the caller still reports it.
+function requirementsFileIsHashed(cmd, root, extraBases = []) {
+  if (!root) return false;
+  const target = pipRequirementTarget(cmd);
+  if (!target) return false;
+  if (path.isAbsolute(target)) return false;
+
+  let found = 0;
+  for (const base of [root, ...extraBases.map((d) => path.resolve(root, d))]) {
+    // Never read outside the scanned tree, whatever `../` the workflow names —
+    // for the base itself as well as the target resolved against it.
+    if (base !== root && !base.startsWith(root + path.sep)) continue;
+    const full = path.resolve(base, target);
+    if (full !== root && !full.startsWith(root + path.sep)) continue;
+    const body = readSafe(full);
+    if (body === null) continue;
+    found++;
+    if (!/--hash=/.test(body)) return false;
+  }
+  return found > 0;
+}
+
+function scanPublishWorkflow(content, rel, root) {
   // Whole-content probes read `code`; the `uses:` scan below stays on raw lines.
   const code = stripYamlComments(content);
   const hits = {
@@ -140,11 +236,51 @@ function scanPublishWorkflow(content, rel) {
     }
   }
 
+  // npm alone stays a whole-file test, because its suppressor is a DIFFERENT
+  // command rather than a flag: `npm ci` elsewhere in the workflow is the
+  // frozen install, and the `npm install` line beside it is usually tooling.
   if (/\bnpm\s+install\b/.test(code) && !/\bnpm\s+ci\b/.test(code)) {
     hits["release-workflow-non-frozen-install"].push({ file: rel, line: 0, snippet: "publish workflow uses `npm install` rather than `npm ci` — lockfile is not enforced" });
   }
-  if (/\bcargo\s+(?:build|install)\b/.test(code) && !/--locked\b/.test(code) && !/--frozen\b/.test(code)) {
-    hits["release-workflow-non-frozen-install"].push({ file: rel, line: 0, snippet: "cargo build/install without --locked / --frozen" });
+
+  // Bundler's frozen mode can be set once for the job rather than per command
+  // (`bundle config set frozen/deployment`, or the BUNDLE_ env equivalents), so
+  // that suppressor is genuinely file-scoped; the flags below are not.
+  // The setting has to be turned ON. `bundle config set frozen false` names the
+  // key and disables it, so matching the key alone reads an explicit opt-out as
+  // the protection it opts out of — the env form already required a value.
+  const bundlerFrozenConfig =
+    /\bbundle\s+config\b[^\n]*\b(?:frozen|deployment)\s+['"]?(?:true|1)\b/.test(code) ||
+    /\bBUNDLE_(?:FROZEN|DEPLOYMENT)\s*[:=]\s*['"]?(?:true|1)\b/i.test(code);
+
+  const runBases = workingDirectories(code);
+
+  // Every remaining ecosystem is probed one command at a time. The playbook
+  // indicator names npm / pnpm / pip -r / bundle; cargo is probed on the same
+  // --locked / --frozen predicate.
+  for (const { cmd, line } of shellCommands(code)) {
+    if (/\bcargo\s+(?:build|install)\b/.test(cmd) && !/--locked\b/.test(cmd) && !/--frozen\b/.test(cmd)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `cargo build/install without --locked / --frozen: ${snippetOf(cmd)}` });
+    }
+    // Without --require-hashes the requirement set resolves at release time, so
+    // the artifact is not reproducible — unless the named file is hash-pinned,
+    // which switches pip into hash-checking mode on its own.
+    if (/\b(?:pip3?|python3?\s+-m\s+pip)\s+install\b/.test(cmd) &&
+        pipRequirementTarget(cmd) !== null &&
+        !/--require-hashes\b/.test(cmd) &&
+        !requirementsFileIsHashed(cmd, root, runBases)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `pip install -r without --require-hashes — requirements are resolved at release time: ${snippetOf(cmd)}` });
+    }
+    // pnpm defaults to --frozen-lockfile when CI is set, which GitHub Actions
+    // always sets — so a bare `pnpm install` here is already frozen and only an
+    // explicit opt-out resolves at release time.
+    if (/\bpnpm\s+(?:install|i)\b/.test(cmd) &&
+        /--no-frozen-lockfile\b|--frozen-lockfile[=\s]+false\b/.test(cmd)) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `pnpm install opts out of the frozen lockfile: ${snippetOf(cmd)}` });
+    }
+    if (/\bbundle\s+install\b/.test(cmd) && !/--deployment\b/.test(cmd) && !/--frozen\b/.test(cmd) && !bundlerFrozenConfig) {
+      hits["release-workflow-non-frozen-install"].push({ file: rel, line, snippet: `bundle install without --deployment / --frozen: ${snippetOf(cmd)}` });
+    }
   }
 
   if (/runs-on:\s*['"]?(?:self-hosted|\[?\s*self-hosted)/i.test(code)) {
@@ -193,7 +329,7 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   // OIDC capability is evaluated per publish workflow, never repo-wide: a sibling
   // workflow's `id-token: write` gives nothing to a job using a static token.
   for (const w of publishWorkflows) {
-    const h = scanPublishWorkflow(w.content, w.rel);
+    const h = scanPublishWorkflow(w.content, w.rel, root);
     for (const [id, list] of Object.entries(h)) workflowHits[id].push(...list);
   }
 

package/lib/collectors/sbom.js

@@ -172,13 +172,24 @@ function captureLockfile(p, ecosystem, parser, label) {
       path: p,
       size_bytes: Buffer.byteLength(content, "utf8"),
       ...stats,
+      // A parser that could not decode the structure returns `error`; the read
+      // itself succeeded, so the two failures carry different kinds downstream.
+      ...(stats && stats.error ? { error_kind: "lockfile_parse_failed" } : {}),
     };
   } catch (e) {
-    return { file: label, ecosystem, path: p, error: e.message };
+    return { file: label, ecosystem, path: p, error: e.message, error_kind: "lockfile_read_failed" };
   }
 }
 
-function findLockfiles(cwd) {
+// `errors` is the collector_errors channel: a directory the walk could not read
+// is a scan gap the operator has to see, not a silent zero. Required, not
+// defaulted: a default array would restore the discard-into-the-void behaviour
+// for any caller that forgets it, and neither this function nor
+// findSbomDocuments is exported, so no test could reach that caller.
+function findLockfiles(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findLockfiles: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
   for (const lf of LOCKFILES) {
     const p = path.join(cwd, lf.file);
@@ -196,7 +207,13 @@ function findLockfiles(cwd) {
         }
       }
     }
-  } catch { /* swallow */ }
+  } catch (e) {
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: "readdir_failed",
+      reason: `cwd root: ${e.message} — requirements*.txt variants were not enumerated`,
+    });
+  }
 
   for (const sub of SUBDIR_PROBE_PATHS) {
     const subDir = path.join(cwd, sub);
@@ -204,7 +221,18 @@ function findLockfiles(cwd) {
     try {
       if (!fs.statSync(subDir).isDirectory()) continue;
       entries = fs.readdirSync(subDir, { withFileTypes: true });
-    } catch { continue; }
+    } catch (e) {
+      // An absent probe dir is the normal case, not a gap. A permission or I/O
+      // failure on one that IS there means the subtree went unscanned.
+      if (e.code !== "ENOENT") {
+        errors.push({
+          artifact_id: "lockfile-inventory",
+          kind: "readdir_failed",
+          reason: `${sub}/: ${e.message} — subtree not scanned for lockfiles`,
+        });
+      }
+      continue;
+    }
     for (const e of entries) {
       if (e.isDirectory()) {
         // packages/* gets one more level for monorepo workspaces, no deeper.
@@ -242,7 +270,11 @@ function findLockfiles(cwd) {
   return found;
 }
 
-function findSbomDocuments(cwd) {
+// `errors` is required for the same reason it is on findLockfiles above.
+function findSbomDocuments(cwd, errors) {
+  if (!Array.isArray(errors)) {
+    throw new TypeError("findSbomDocuments: `errors` must be the collector_errors array — scan gaps have nowhere else to go");
+  }
   const found = [];
   for (const s of SBOM_FORMATS) {
     const p = path.join(cwd, s.file);
@@ -250,24 +282,41 @@ function findSbomDocuments(cwd) {
     // Open once and fstat the descriptor rather than existsSync→statSync→read:
     // ENOENT still skips, and there is no TOCTOU window.
     try { fd = fs.openSync(p, "r"); }
-    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message }); continue; }
+    catch (e) { if (e.code === "ENOENT") continue; found.push({ file: s.file, format: s.format, error: e.message, error_kind: "open_failed" }); continue; }
     try {
       const stat = fs.fstatSync(fd);
       let content;
       // Read from the open descriptor, never by path again. readFileSync(fd) loops
       // to EOF; a single readSync can return short on a network or FUSE mount,
       // NUL-padding the buffer and truncating otherwise-valid JSON.
-      try { content = fs.readFileSync(fd, "utf8"); } catch { content = null; }
+      try { content = fs.readFileSync(fd, "utf8"); } catch (e) {
+        content = null;
+        errors.push({
+          artifact_id: "sbom-document",
+          kind: "read_failed",
+          reason: `${s.file}: ${e.message} — component count not derived`,
+        });
+      }
       let component_count = null;
       if (content && s.format === "cyclonedx-1.x") {
         try {
           const j = JSON.parse(content);
           component_count = (j.components || []).length;
-        } catch {}
+        } catch (e) {
+          // A present-but-unparseable SBOM reported `null components` with no
+          // explanation, which reads as "no components" rather than "not read".
+          errors.push({
+            artifact_id: "sbom-document",
+            kind: "parse_failed",
+            reason: `${s.file}: ${e.message} — component count unavailable`,
+          });
+        }
       }
       found.push({ file: s.file, format: s.format, size_bytes: stat.size, component_count });
     } catch (e) {
-      found.push({ file: s.file, format: s.format, error: e.message });
+      // The descriptor opened; fstat is what failed here. Reporting it as an
+      // open failure sends the operator after the wrong thing.
+      found.push({ file: s.file, format: s.format, error: e.message, error_kind: "stat_failed" });
     } finally {
       if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* non-fatal */ } }
     }
@@ -281,10 +330,31 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   const root = path.resolve(cwd);
 
   // sbom-tool-available: a lockfile or an SBOM document is a sufficient proxy.
-  const lockfiles = findLockfiles(root);
-  const sbomDocuments = findSbomDocuments(root);
+  const lockfiles = findLockfiles(root, errors);
+  const sbomDocuments = findSbomDocuments(root, errors);
   const hasAnything = lockfiles.length > 0 || sbomDocuments.length > 0;
 
+  // A lockfile that was found but not read contributes no component count, so
+  // the inventory under-reports; the operator sees which one and why.
+  for (const l of lockfiles) {
+    if (!l.error) continue;
+    errors.push({
+      artifact_id: "lockfile-inventory",
+      kind: l.error_kind || "lockfile_read_failed",
+      reason: `${l.file}: ${l.error}`,
+    });
+  }
+  for (const s of sbomDocuments) {
+    if (!s.error) continue;
+    errors.push({
+      artifact_id: "sbom-document",
+      // Carried from the push site, mirroring the lockfile loop above: an
+      // fstat failure and an open failure are different operator actions.
+      kind: s.error_kind || "open_failed",
+      reason: `${s.file}: ${s.error}`,
+    });
+  }
+
   const artifacts = {
     "lockfile-inventory": {
       value: lockfiles.length
@@ -346,8 +416,13 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       }
       npmLockfile.integrity_present_count = withIntegrity;
       npmLockfile.integrity_missing_count = withoutIntegrity;
-    } catch {
+    } catch (e) {
       // A malformed lockfile leaves the indicator unflipped: inconclusive, not miss.
+      errors.push({
+        artifact_id: "lockfile-inventory",
+        kind: "lockfile_parse_failed",
+        reason: `${npmLockfile.file}: ${e.message} — lockfile-no-integrity left undecided (inconclusive, not miss)`,
+      });
     }
   }
 
@@ -378,6 +453,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       lockfiles_found: lockfiles.length,
       sbom_documents_found: sbomDocuments.length,
       ecosystems_detected: [...new Set(lockfiles.map(l => l.ecosystem))],
+      // Magnitude behind the lockfile-no-integrity verdict: "hit" alone does not
+      // say whether one entry or nine hundred resolve without a hash. Present
+      // only when an npm lockfile was found AND parsed.
+      ...(npmLockfile && npmLockfile.integrity_present_count != null
+        ? {
+          npm_integrity_present_count: npmLockfile.integrity_present_count,
+          npm_integrity_missing_count: npmLockfile.integrity_missing_count,
+        }
+        : {}),
     },
     collector_errors: errors,
   };

package/lib/collectors/scan-excludes.js

@@ -85,8 +85,9 @@ function walkTree(root, opts = {}) {
         }
         walk(full, depth + 1);
       } else if (entry.isSymbolicLink()) {
-        // A symlink Dirent is neither isDirectory() nor isFile(): never emitted.
-        try { fs.realpathSync(full); } catch { /* dangling link — ignore */ }
+        // A symlink Dirent is neither isDirectory() nor isFile(), so it is
+        // never traversed and never emitted — including a dangling one.
+        continue;
       } else if (entry.isFile()) {
         // A regular file cannot introduce a directory cycle, so no realpath /
         // `seen` check. Windows path.relative returns backslashes, so rel is

package/lib/cve-regression-watcher.js

@@ -7,9 +7,6 @@
  * it never mutates the catalog; each candidate is triage input.
  */
 
-const path = require('path');
-const fs = require('fs');
-
 const CVE_ID_RE = /^CVE-((?:19|20)\d{2})-\d{4,7}$/;
 
 /**

package/lib/framework-gap.js

@@ -159,6 +159,11 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
  * free text. Omitting `opts.lessons` (parsed zeroday-lessons.json) yields a
  * report with no new-control section rather than an error. Returns
  * { frameworks, universal_gaps, new_control_requirements, theater_risks, summary }.
+ *
+ * `cveCatalog` is positional surface this function does not read — the scenario
+ * matches against `controlGaps` alone. It holds the fourth slot so `opts` stays
+ * fifth, and mirrors theaterCheck(), which does read its catalog. Dropping the
+ * parameter would silently bind every caller's `opts` argument to it instead.
  */
 function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, opts = {}) {
   const scenario = threatScenario.toLowerCase();

package/lib/lint-skills.js

@@ -100,8 +100,20 @@ function isStrictIsoCalendarDate(s) {
 const KEBAB_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
 const JSON_FILENAME_RE = /^[A-Za-z0-9._-]+\.json$/;
 
+// `helpExitCode` is null unless the run is over before linting starts: 0 after
+// --help, 2 after an unknown argument. parseArgs never terminates the process —
+// it returns the code and the caller must honour it and stop.
+//
+// The invariant this keeps: every exit in this file goes through safeExit(), so
+// no path here can write to stdout and then terminate synchronously. That is the
+// `process-exit-after-stdout-write` shape, and it is a convention held file-wide
+// rather than a repair of an observed truncation: Node writes pipe stdout
+// synchronously on Windows and Linux (asynchronously on macOS), and the help
+// block is a few hundred bytes, so process.exit() did not in fact truncate it
+// here. Holding the invariant means a future help block that grows, or a run on
+// a platform with async pipe writes, cannot reintroduce the class.
 function parseArgs(argv) {
-  const opts = { skill: null, quiet: false, strict: false };
+  const opts = { skill: null, quiet: false, strict: false, helpExitCode: null };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--skill') {
@@ -115,11 +127,13 @@ function parseArgs(argv) {
       opts.strict = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
-      process.exit(0);
+      opts.helpExitCode = 0;
+      return opts;
     } else {
       console.error(`Unknown argument: ${a}`);
       printHelp();
-      process.exit(2);
+      opts.helpExitCode = 2;
+      return opts;
     }
   }
   return opts;
@@ -798,6 +812,10 @@ function lintPlaybookAirGap() {
 
 function main() {
   const opts = parseArgs(process.argv);
+  if (opts.helpExitCode !== null) {
+    safeExit(opts.helpExitCode);
+    return;
+  }
   const manifest = readJson(MANIFEST_PATH);
 
   let skills = manifest.skills;
@@ -805,7 +823,8 @@ function main() {
     skills = skills.filter((s) => s.name === opts.skill);
     if (skills.length === 0) {
       console.error(`No skill named "${opts.skill}" in manifest.json`);
-      process.exit(2);
+      safeExit(2);
+      return;
     }
   }
 
@@ -888,6 +907,7 @@ function main() {
 
 // The frontmatter parser is exported so `watchlist` does not grow a second one.
 module.exports = {
+  parseArgs,
   parseFrontmatter,
   extractFrontmatterBlock,
   unquote,

package/lib/playbook-runner.js

@@ -1292,6 +1292,60 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     analyze_complete: !!(analyzeResult && typeof analyzeResult === 'object'),
     validate_complete: !!(validateResult && typeof validateResult === 'object'),
   };
+
+  // Nothing downstream guards the analyze result's container shape: every
+  // bundle format maps over `analyze.matched_cves` directly, and so does
+  // analyzeFindingShape, so a non-object result or a non-array matched_cves
+  // throws before phase 7 produces any output at all. Normalizing once, here,
+  // is what makes the whole phase survive it — the run still emits an evidence
+  // bundle and the shape failure is readable on runtime_errors. The container
+  // and its elements are both normalized: every bundle builder dereferences an
+  // element, so one null inside an otherwise well-formed array aborts the phase
+  // exactly as a non-array container does.
+  const shapeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
+  const analyzeIsObject = !!analyzeResult && typeof analyzeResult === 'object' && !Array.isArray(analyzeResult);
+  if (!analyzeIsObject || !Array.isArray(analyzeResult.matched_cves)) {
+    pushRunError(runOpts._runErrors, {
+      kind: 'analyze_shape',
+      message: analyzeIsObject
+        ? `analyze.matched_cves is ${shapeOf(analyzeResult.matched_cves)}, expected an array; treated as empty`
+        : `analyze result is ${shapeOf(analyzeResult)}, expected an object; treated as empty`,
+    }, { dedupeKey: x => x.message || '' });
+    // A copy, so close() reports the caller's malformed result without
+    // rewriting it underneath them.
+    analyzeResult = { ...(analyzeIsObject ? analyzeResult : {}), matched_cves: [] };
+  } else {
+    // Dropped rather than repaired: a consumer cannot read a CVE id off a null,
+    // and inventing a placeholder entry would put a finding in the evidence
+    // bundle that the analyze phase never produced.
+    const usable = (e) => !!e && typeof e === 'object' && !Array.isArray(e);
+    const dropped = analyzeResult.matched_cves.filter((e) => !usable(e));
+    if (dropped.length) {
+      pushRunError(runOpts._runErrors, {
+        kind: 'analyze_shape',
+        message: `analyze.matched_cves holds ${dropped.length} malformed element(s) (${[...new Set(dropped.map(shapeOf))].join(', ')}); they are dropped and the remaining ${analyzeResult.matched_cves.length - dropped.length} are used`,
+      }, { dedupeKey: x => x.message || '' });
+      analyzeResult = { ...analyzeResult, matched_cves: analyzeResult.matched_cves.filter(usable) };
+    }
+  }
+
+  // The residual guard for the four sites that interpolate the finding shape —
+  // the notification draft, the auditor-ready exception language, the
+  // learning-loop lesson and the feeds_into finding context. The normalization
+  // above removes the shapes analyzeFindingShape is known to throw on; this
+  // catches anything it still throws on, degrading those four fields to
+  // `<MISSING:…>` and putting the throw on runtime_errors rather than aborting
+  // the phase.
+  const safeFindingShape = () => {
+    try { return analyzeFindingShape(analyzeResult); }
+    catch (e) {
+      pushRunError(runOpts._runErrors,
+        { kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) },
+        { dedupeKey: x => x.message || '' });
+      return {};
+    }
+  };
+
   const enrichNotification = (na) => {
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       o && typeof o === 'object' &&
@@ -1359,16 +1413,9 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // Which template vars failed to resolve; empty when all rendered.
       ...(function () {
         const missing = [];
-        // Wrapped so a malformed analyze result cannot bring down close();
-        // the failure surfaces through runOpts._runErrors instead.
-        let findingShape;
-        try { findingShape = analyzeFindingShape(analyzeResult); }
-        catch (e) {
-          if (Array.isArray(runOpts._runErrors)) {
-            pushRunError(runOpts._runErrors, { kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) }, { dedupeKey: e => e.message || '' });
-          }
-          findingShape = {};
-        }
+        // safeFindingShape, not analyzeFindingShape: a malformed analyze result
+        // must not bring down close(); the failure surfaces on runtime_errors.
+        const findingShape = safeFindingShape();
         const draft = interpolate(
           na.draft_notification,
           { ...agentSignals, ...findingShape },
@@ -1416,7 +1463,11 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // does not supply, so the auditor-ready language routinely renders
       // `<MISSING:…>`. missing_interpolation_vars names which.
       const exMissing = [];
-      const findingShape = (() => { try { return analyzeFindingShape(analyzeResult); } catch { return {}; } })();
+      // safeFindingShape, like the other three shape consumers. The feeds_into
+      // context below reports the same throw on every close(), so this site's
+      // own disposition is not separately observable — it is uniform so a
+      // future reader does not read the bare catch as a deliberate exemption.
+      const findingShape = safeFindingShape();
       exception = {
         scope: interpolate(t.scope, { ...agentSignals, ...findingShape }, exMissing),
         duration: t.duration,
@@ -1492,7 +1543,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
 
   const lesson = c.learning_loop?.enabled ? {
     enabled: true,
-    attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, analyzeFindingShape(analyzeResult)),
+    attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, safeFindingShape()),
     control_gap: c.learning_loop.lesson_template.control_gap,
     framework_gap: c.learning_loop.lesson_template.framework_gap,
     new_control_requirement: c.learning_loop.lesson_template.new_control_requirement,
@@ -1542,7 +1593,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     analyze: analyzeResult,
     validate: validateResult,
     // Same two-sourced finding.* shape and guards as the escalation context.
-    finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...analyzeFindingShape(analyzeResult) },
+    finding: { ...(agentSignals.finding && typeof agentSignals.finding === 'object' && !Array.isArray(agentSignals.finding) ? agentSignals.finding : {}), ...safeFindingShape() },
     // Without the accumulator, a feeds_into condition failure never reaches
     // analyze.runtime_errors[].
     ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
@@ -2356,7 +2407,10 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       '@id': productPurl,
       subcomponents: [{ '@id': productPurl }],
     };
-    const remediationId = validate.selected_remediation?.id || (validate.remediation_paths?.[0]?.id) || null;
+    // validate() selects the priority-1 path as its last rung, so a null
+    // selected_remediation means the phase declares no remediation paths at all
+    // and remediation_options_considered is empty too — there is no id to name.
+    const remediationId = validate.selected_remediation?.id || null;
     const remediationDescription = validate.selected_remediation?.description || null;
     const actionStatementFor = (fallback) => {
       if (remediationId && remediationDescription) {

package/lib/prefetch.js

@@ -487,8 +487,9 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // `pins` is the registered source name; `github` is accepted too, so
-  // GITHUB_TOKEN reaches the header whichever spelling an operator uses.
+  // `pins` is the registered name for the MITRE GitHub releases feed. The
+  // `github` alias is defensive: no registered source emits it, and prefetch()
+  // refuses `--source github` before any header is built.
   if ((source === "pins" || source === "github") && process.env.GITHUB_TOKEN) {
     return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
   }

package/lib/refresh-external.js

@@ -1701,12 +1701,6 @@ async function main() {
   process.exitCode = cacheIntegrityFailure ? 4 : (hadFailure ? 1 : 0);
 }
 
-async function sequential(items, fn) {
-  const out = [];
-  for (const it of items) out.push(await fn(it));
-  return out;
-}
-
 if (require.main === module) {
   main().catch((err) => {
     // A hinted error prints its message plus a JSON line, never a stack trace.

package/lib/refresh-network.js

@@ -116,10 +116,9 @@ function getBufferOnce(url, timeoutMs) {
     if (!isAllowedTarballHost(url)) {
       return reject(new Error(`refusing to fetch tarball from non-allowlisted host: ${u.hostname}`));
     }
-    const cap = (() => {
-      const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
-      return Number.isFinite(env) && env > 0 ? env : 200 * 1024 * 1024;
-    })();
+    // Same reader as the buffered-length check, so the streaming cap and the
+    // post-download cap cannot drift apart when the default changes.
+    const cap = tarballSizeCap();
     const req = https.get({
       host: u.host, path: u.pathname + u.search,
       headers: { "User-Agent": "exceptd/refresh-network" },

package/lib/scoring.js

@@ -431,10 +431,17 @@ function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
+    // A null or non-object entry cannot be walked field by field: `field in
+    // entry` throws, taking down validation of the whole catalog. Report it as
+    // the error it is, so the remaining entries are still checked.
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${cveId}: entry is ${entry === null ? 'null' : typeof entry}, expected an object`);
+      continue;
+    }
     // Drafts carry a conservative-default rwep_score beside null-until-curated
     // factor fields, so the divergence check below fires on every one. They are
     // reviewed through `_auto_imported_meta.curation_needed` instead.
-    if (entry && entry._auto_imported === true) continue;
+    if (entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {
       if (!(field in entry)) {
         errors.push(`${cveId}: missing required field '${field}'`);