@blamejs/exceptd-skills 0.12.10 → 0.12.13

package/lib/prefetch.js

@@ -188,9 +188,93 @@ function loadIndex(cacheDir) {
   }
 }
 
-function saveIndex(cacheDir, idx) {
+// v0.12.12 C4: atomic write helper — tmp + rename. Concurrent readers either
+// see the prior file in full or the new file in full, never a half-written
+// buffer. fs.renameSync is atomic on POSIX and on Windows for same-volume
+// renames; a `.tmp.<pid>.<rand>` sibling to the destination is always
+// same-volume.
+function writeFileAtomic(p, body) {
+  const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+  fs.writeFileSync(tmpPath, body);
+  try {
+    fs.renameSync(tmpPath, p);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    throw err;
+  }
+}
+
+// v0.12.12 C2: lockfile-gated read-modify-write for _index.json. Two
+// concurrent prefetch runs against the same cache dir previously raced —
+// each loaded the index at start, mutated its in-memory copy as entries
+// fetched, then wrote at the end. The second writer overwrote the first,
+// silently dropping any entries the first run wrote.
+//
+// Stale-lock recovery: if a holder crashes without unlinking, the lockfile
+// persists. After backoff, if the lockfile's mtime is older than 30s we
+// treat it as orphaned and unlink it before retrying.
+async function withIndexLock(cacheDir, mutator) {
   if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true });
-  fs.writeFileSync(path.join(cacheDir, "_index.json"), JSON.stringify(idx, null, 2) + "\n", "utf8");
+  const lockPath = path.join(cacheDir, "_index.json.lock");
+  const indexPath = path.join(cacheDir, "_index.json");
+  const MAX_RETRIES = 50;
+  const STALE_LOCK_MS = 30_000;
+  let acquired = false;
+  for (let i = 0; i < MAX_RETRIES; i++) {
+    try {
+      fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+      acquired = true;
+      break;
+    } catch (e) {
+      // EEXIST is the POSIX signal another process holds the lock. On
+      // Windows the same race surfaces as EPERM (a sharing-violation
+      // raised when the other process is mid-unlink). Treat both as
+      // "lock held, back off" rather than a fatal error.
+      if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+          try { fs.unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      } catch {}
+      await new Promise((r) => setTimeout(r, 50 + Math.random() * 150));
+    }
+  }
+  if (!acquired) {
+    throw new Error(`withIndexLock: could not acquire ${lockPath} after ${MAX_RETRIES} attempts`);
+  }
+  try {
+    // Always re-read the current on-disk index inside the lock. Stale
+    // in-memory copies from before acquisition are the entire bug class.
+    let current;
+    if (fs.existsSync(indexPath)) {
+      try { current = JSON.parse(fs.readFileSync(indexPath, "utf8")); }
+      catch { current = { entries: {}, generated_at: null }; }
+    } else {
+      current = { entries: {}, generated_at: null };
+    }
+    const mutated = await mutator(current);
+    const toWrite = mutated === undefined ? current : mutated;
+    writeFileAtomic(indexPath, JSON.stringify(toWrite, null, 2) + "\n");
+    return toWrite;
+  } finally {
+    try { fs.unlinkSync(lockPath); } catch {}
+  }
+}
+
+// Back-compat: existing callers used saveIndex(cacheDir, idx). The thin
+// wrapper merges entries under the lock so a concurrent run's writes are
+// preserved (rather than blindly overwriting them with the caller's
+// possibly-stale in-memory `idx`).
+async function saveIndex(cacheDir, idx) {
+  await withIndexLock(cacheDir, (current) => {
+    const mergedEntries = { ...current.entries, ...idx.entries };
+    return {
+      entries: mergedEntries,
+      generated_at: idx.generated_at || current.generated_at,
+    };
+  });
 }
 
 function entryKey(source, id) {
@@ -292,17 +376,32 @@ async function prefetch(options = {}) {
         run: () => timedFetch(item.url, reqHeaders),
         meta: { id: item.id },
       })
-      .then((res) => {
-        const dir = path.dirname(entryPath(opts.cacheDir, item.source, item.id));
+      .then(async (res) => {
+        const targetPath = entryPath(opts.cacheDir, item.source, item.id);
+        const dir = path.dirname(targetPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(entryPath(opts.cacheDir, item.source, item.id), JSON.stringify(res.json, null, 2) + "\n", "utf8");
-        idx.entries[entryKey(item.source, item.id)] = {
+        // v0.12.12 C4: atomic write of the payload. A concurrent reader
+        // (refresh --from-cache running in parallel) sees the prior
+        // payload in full or the new payload in full, never a partial
+        // buffer.
+        writeFileAtomic(targetPath, JSON.stringify(res.json, null, 2) + "\n");
+        const meta = {
           fetched_at: new Date().toISOString(),
           etag: res.etag,
           last_modified: res.lastModified,
           url: item.url,
           sha256: crypto.createHash("sha256").update(JSON.stringify(res.json)).digest("hex"),
         };
+        idx.entries[entryKey(item.source, item.id)] = meta;
+        // v0.12.12 C2: persist this entry's metadata to _index.json under
+        // lock immediately, merging with whatever the on-disk index has
+        // (another concurrent prefetch may have written sibling entries).
+        // Without this, only the in-memory idx is updated; the final
+        // saveIndex() would overwrite a sibling run's writes.
+        await withIndexLock(opts.cacheDir, (current) => {
+          current.entries[entryKey(item.source, item.id)] = meta;
+          return current;
+        });
         result.fetched++;
         result.by_source[item.source].fetched++;
         log(`  [${item.source}] ${item.id} — ok`);
@@ -317,7 +416,10 @@ async function prefetch(options = {}) {
   await Promise.all(jobPromises);
   await queue.drain();
   idx.generated_at = new Date().toISOString();
-  saveIndex(opts.cacheDir, idx);
+  // v0.12.12 C2: saveIndex now merges under lock with whatever is on disk
+  // (another concurrent prefetch's entries). Without the merge, a sibling
+  // run's writes would be silently overwritten here at the end of our run.
+  await saveIndex(opts.cacheDir, idx);
 
   // Final summary is unconditional — --quiet suppresses per-entry chatter
   // (the noisy part) but the operator still needs one line confirming success.
@@ -398,4 +500,15 @@ async function main() {
 
 if (require.main === module) main();
 
-module.exports = { prefetch, readCached, parseArgs, SOURCES, DEFAULT_CACHE };
+module.exports = {
+  prefetch,
+  readCached,
+  parseArgs,
+  SOURCES,
+  DEFAULT_CACHE,
+  // v0.12.12 C2: exported for the concurrent-writer regression test.
+  // Not part of the operator-facing API — internal contract for tests
+  // that need to exercise the lockfile path without spawning the full
+  // prefetch network pipeline.
+  _internal: { withIndexLock, writeFileAtomic, loadIndex, saveIndex },
+};

package/lib/refresh-external.js

@@ -125,10 +125,14 @@ Modes:
   --swarm            fan out sources across worker threads. Best with --from-cache.
   --advisory <id>    (v0.12.0) seed a single catalog entry from an advisory ID.
                      CVE-* and GHSA-* route through the GitHub Advisory
-                     Database. MAL-*, SNYK-*, RUSTSEC-*, USN-*, UVI-*, GO-*,
-                     MGASA-*, PYSEC-*, and other OSV-native namespaces route
-                     through OSV.dev (v0.12.10). Writes a DRAFT to
-                     data/cve-catalog.json marked with _auto_imported: true.
+                     Database. When GHSA returns 404 for a CVE-* id
+                     (CNAs / OSV mirrors operate on different cadences) the
+                     dispatcher falls back to OSV.dev's /v1/vulns/{id}
+                     before failing (v0.12.11). MAL-*, SNYK-*, RUSTSEC-*,
+                     USN-*, UVI-*, GO-*, MGASA-*, PYSEC-*, and other
+                     OSV-native namespaces route through OSV.dev (v0.12.10).
+                     Writes a DRAFT to data/cve-catalog.json marked with
+                     _auto_imported: true.
                      Editorial fields (framework_control_gaps, iocs,
                      atlas_refs, attack_refs) remain null pending review via:
                        exceptd run cve-curation --advisory <id>
@@ -137,6 +141,17 @@ Modes:
                        exceptd refresh --advisory GHSA-xxxx-xxxx-xxxx --apply
                        exceptd refresh --advisory MAL-2026-3083
                        exceptd refresh --advisory RUSTSEC-2025-0001
+  --curate <CVE-ID>  emit editorial questions + ranked candidates
+                     (ATLAS/ATT&CK/CWE/framework gaps) for a draft entry.
+                     With --answers <path> the operator-supplied answers
+                     are validated, applied to the catalog entry, and the
+                     draft is promoted out of _auto_imported / _draft once
+                     every required schema field is populated. Atomic write;
+                     concurrent --apply runs against the same catalog are
+                     safe. --apply is an alias for "--answers implies write".
+                     Examples:
+                       exceptd refresh --curate CVE-2026-45321
+                       exceptd refresh --curate CVE-2026-45321 --answers a.json --apply
 
 Sources (default = all):
   kev   CISA Known Exploited Vulnerabilities
@@ -210,26 +225,32 @@ const KEV_SOURCE = {
     let updated = 0;
     let added = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (d.op === "add") {
-        // Auto-discovered new entry. Refuse to overwrite if the entry
-        // somehow exists (race condition / stale fixture); skip silently.
-        if (ctx.cveCatalog[d.id]) continue;
-        ctx.cveCatalog[d.id] = d.entry;
-        added++;
-        continue;
-      }
-      if (!ctx.cveCatalog[d.id]) {
-        errors.push(`KEV: no local entry for ${d.id}`);
-        continue;
+    const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
+    await withCatalogLock(catalogPath, (catalog) => {
+      for (const d of diffs) {
+        if (d.op === "add") {
+          // Auto-discovered new entry. Refuse to overwrite if the entry
+          // somehow exists (race condition / stale fixture); skip silently.
+          if (catalog[d.id]) continue;
+          catalog[d.id] = d.entry;
+          added++;
+          continue;
+        }
+        if (!catalog[d.id]) {
+          errors.push(`KEV: no local entry for ${d.id}`);
+          continue;
+        }
+        catalog[d.id][d.field] = d.after;
+        catalog[d.id].last_verified = TODAY;
+        updated++;
       }
-      ctx.cveCatalog[d.id][d.field] = d.after;
-      ctx.cveCatalog[d.id].last_verified = TODAY;
-      updated++;
-    }
-    ctx.cveCatalog._meta = ctx.cveCatalog._meta || {};
-    ctx.cveCatalog._meta.last_updated = TODAY;
-    writeJson(ctx.cvePath || ABS("data/cve-catalog.json"), ctx.cveCatalog);
+      catalog._meta = catalog._meta || {};
+      catalog._meta.last_updated = TODAY;
+      // Refresh the in-memory view so later sources in the same process
+      // (sequential or --swarm) see the post-write state.
+      ctx.cveCatalog = catalog;
+      return catalog;
+    });
     return { updated: updated + added, added, drift_updated: updated, errors };
   },
 };
@@ -293,18 +314,22 @@ const EPSS_SOURCE = {
   async applyDiff(ctx, diffs) {
     let updated = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (!ctx.cveCatalog[d.id]) {
-        errors.push(`EPSS: no local entry for ${d.id}`);
-        continue;
+    const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
+    await withCatalogLock(catalogPath, (catalog) => {
+      for (const d of diffs) {
+        if (!catalog[d.id]) {
+          errors.push(`EPSS: no local entry for ${d.id}`);
+          continue;
+        }
+        catalog[d.id][d.field] = d.after;
+        catalog[d.id].last_verified = TODAY;
+        updated++;
       }
-      ctx.cveCatalog[d.id][d.field] = d.after;
-      ctx.cveCatalog[d.id].last_verified = TODAY;
-      updated++;
-    }
-    ctx.cveCatalog._meta = ctx.cveCatalog._meta || {};
-    ctx.cveCatalog._meta.last_updated = TODAY;
-    writeJson(ctx.cvePath || ABS("data/cve-catalog.json"), ctx.cveCatalog);
+      catalog._meta = catalog._meta || {};
+      catalog._meta.last_updated = TODAY;
+      ctx.cveCatalog = catalog;
+      return catalog;
+    });
     return { updated, errors };
   },
 };
@@ -338,18 +363,22 @@ const NVD_SOURCE = {
   async applyDiff(ctx, diffs) {
     let updated = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (!ctx.cveCatalog[d.id]) {
-        errors.push(`NVD: no local entry for ${d.id}`);
-        continue;
+    const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
+    await withCatalogLock(catalogPath, (catalog) => {
+      for (const d of diffs) {
+        if (!catalog[d.id]) {
+          errors.push(`NVD: no local entry for ${d.id}`);
+          continue;
+        }
+        catalog[d.id][d.field] = d.after;
+        catalog[d.id].last_verified = TODAY;
+        updated++;
       }
-      ctx.cveCatalog[d.id][d.field] = d.after;
-      ctx.cveCatalog[d.id].last_verified = TODAY;
-      updated++;
-    }
-    ctx.cveCatalog._meta = ctx.cveCatalog._meta || {};
-    ctx.cveCatalog._meta.last_updated = TODAY;
-    writeJson(ctx.cvePath || ABS("data/cve-catalog.json"), ctx.cveCatalog);
+      catalog._meta = catalog._meta || {};
+      catalog._meta.last_updated = TODAY;
+      ctx.cveCatalog = catalog;
+      return catalog;
+    });
     return { updated, errors };
   },
 };
@@ -394,26 +423,30 @@ const RFC_SOURCE = {
     let updated = 0;
     let added = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (d.op === "add") {
-        if (ctx.rfcCatalog[d.id]) continue;
-        ctx.rfcCatalog[d.id] = d.entry;
-        added++;
-        continue;
-      }
-      if (d.field !== "status") continue; // notes are informational
-      const entry = ctx.rfcCatalog[d.id];
-      if (!entry) {
-        errors.push(`RFC: no local entry for ${d.id}`);
-        continue;
+    const rfcPath = ABS("data/rfc-references.json");
+    await withCatalogLock(rfcPath, (rfcCatalog) => {
+      for (const d of diffs) {
+        if (d.op === "add") {
+          if (rfcCatalog[d.id]) continue;
+          rfcCatalog[d.id] = d.entry;
+          added++;
+          continue;
+        }
+        if (d.field !== "status") continue; // notes are informational
+        const entry = rfcCatalog[d.id];
+        if (!entry) {
+          errors.push(`RFC: no local entry for ${d.id}`);
+          continue;
+        }
+        entry.status = d.after;
+        entry.last_verified = TODAY;
+        updated++;
       }
-      entry.status = d.after;
-      entry.last_verified = TODAY;
-      updated++;
-    }
-    ctx.rfcCatalog._meta = ctx.rfcCatalog._meta || {};
-    ctx.rfcCatalog._meta.last_updated = TODAY;
-    writeJson(ABS("data/rfc-references.json"), ctx.rfcCatalog);
+      rfcCatalog._meta = rfcCatalog._meta || {};
+      rfcCatalog._meta.last_updated = TODAY;
+      ctx.rfcCatalog = rfcCatalog;
+      return rfcCatalog;
+    });
     return { updated: updated + added, added, drift_updated: updated, errors };
   },
 };
@@ -820,8 +853,97 @@ function loadCtx(opts) {
   return ctx;
 }
 
+// v0.12.12 C4: every persisted JSON write goes through writeJsonAtomic — a
+// tmp + rename pattern. fs.renameSync is atomic on POSIX and on Windows for
+// same-volume renames (which a `.tmp.<pid>.<rand>` adjacent to the target
+// always satisfies). A concurrent reader either sees the prior file content
+// in full or the new content in full — never a half-written buffer. The
+// tmp name carries pid + random so two writers in the same process (e.g.
+// 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");
+  try {
+    fs.renameSync(tmpPath, p);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    throw err;
+  }
+}
+
+// Back-compat alias — exported callers and historical sites still reference
+// writeJson. Atomic by default; never the unsafe direct-write form.
 function writeJson(p, obj) {
-  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  writeJsonAtomic(p, obj);
+}
+
+/**
+ * v0.12.12 C1: lockfile-gated read-modify-write helper for JSON catalogs.
+ *
+ * Two concurrent `refresh --advisory CVE-A --apply` and
+ * `refresh --advisory CVE-B --apply` processes against the same catalog used
+ * to race: each read the catalog, mutated its in-memory copy, then wrote —
+ * the second write overwrote the first, silently dropping one CVE. The fix
+ * is a sidecar lockfile (created with O_EXCL via `flag: 'wx'`) that
+ * serializes the read-mutate-write triple. The mutator receives the
+ * current-on-disk catalog (re-read inside the lock, NOT a stale in-memory
+ * copy from before lock acquisition) and returns it after mutation; the
+ * helper then writes atomically via writeJsonAtomic.
+ *
+ * Stale-lock recovery: if a holder crashes without unlinking, the lockfile
+ * persists. After backoff, if the lockfile's mtime is older than 30s we
+ * treat it as orphaned and unlink it before retrying. 30s is well past any
+ * legitimate single-CVE apply (sub-second on modern disks).
+ *
+ * On acquisition failure after N retries, we throw — better than silently
+ * proceeding without the lock.
+ *
+ * @param {string} catalogPath  path to the JSON catalog to lock
+ * @param {(catalog: object) => object | Promise<object>} mutator
+ *        receives current-on-disk catalog, returns mutated catalog. May be
+ *        async. The return value is what gets written; if it returns
+ *        undefined, the in-place mutation of the passed-in catalog is used.
+ * @returns {Promise<{ wrote: boolean, result: any }>}
+ */
+async function withCatalogLock(catalogPath, mutator) {
+  const lockPath = `${catalogPath}.lock`;
+  const MAX_RETRIES = 50;
+  const STALE_LOCK_MS = 30_000;
+  let acquired = false;
+  for (let i = 0; i < MAX_RETRIES; i++) {
+    try {
+      fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+      acquired = true;
+      break;
+    } catch (e) {
+      // EEXIST is the POSIX signal another process holds the lock. On
+      // Windows the same race surfaces as EPERM (sharing-violation raised
+      // when the holder is mid-unlink). Treat both as "lock held, back off."
+      if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
+      // Stale-lock check before sleeping — a long-dead holder shouldn't keep
+      // us waiting MAX_RETRIES * backoff before we recover.
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+          try { fs.unlinkSync(lockPath); } catch {}
+          continue; // retry immediately without sleeping
+        }
+      } catch {} // lockfile vanished between EEXIST and stat — fine, retry
+      await new Promise((r) => setTimeout(r, 50 + Math.random() * 150));
+    }
+  }
+  if (!acquired) {
+    throw new Error(`withCatalogLock: could not acquire ${lockPath} after ${MAX_RETRIES} attempts`);
+  }
+  try {
+    const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+    const mutated = await mutator(catalog);
+    const toWrite = mutated === undefined ? catalog : mutated;
+    writeJsonAtomic(catalogPath, toWrite);
+    return { wrote: true, result: toWrite };
+  } finally {
+    try { fs.unlinkSync(lockPath); } catch {}
+  }
 }
 
 function chosenSources(opts) {
@@ -830,8 +952,13 @@ function chosenSources(opts) {
   const out = [];
   for (const n of names) {
     if (!ALL_SOURCES[n]) {
-      console.error(`refresh-external: unknown source "${n}". Valid: ${Object.keys(ALL_SOURCES).join(", ")}`);
-      process.exit(2);
+      // v0.12.12 C3: previously `process.exit(2)` after a console.error.
+      // Stdout writes elsewhere in this run could truncate; throwing lets
+      // main().catch() surface the error through the standard channel and
+      // exit code via process.exitCode + natural event-loop drain.
+      const err = new Error(`refresh-external: unknown source "${n}". Valid: ${Object.keys(ALL_SOURCES).join(", ")}`);
+      err._exceptd_unknown_source = true;
+      throw err;
     }
     out.push(ALL_SOURCES[n]);
   }
@@ -861,7 +988,27 @@ async function seedSingleAdvisory(opts) {
   const sourceName = useOsv ? "osv" : "ghsa";
   const fixtureEnv = useOsv ? "EXCEPTD_OSV_FIXTURE" : "EXCEPTD_GHSA_FIXTURE";
 
-  const result = await sourceMod.fetchAdvisoryById(id, {});
+  let result = await sourceMod.fetchAdvisoryById(id, {});
+  // F4 (v0.12.11): CVE-* identifiers may have an OSV record before GHSA
+  // publishes one (CNAs and OSV mirrors operate on different cadences).
+  // When GHSA returns 404 specifically, retry through OSV's /v1/vulns/{id}
+  // — OSV indexes CVE ids as primary keys. If both 404, surface a combined
+  // error message so operators know both sources were tried before failing.
+  let fallbackSourceUsed = null;
+  if (!result.ok && !useOsv && /^CVE-/i.test(id) && /HTTP 404/.test(result.error || "")) {
+    const fallback = await osvMod.fetchAdvisoryById(id, {});
+    if (fallback.ok) {
+      result = fallback;
+      fallbackSourceUsed = "osv";
+    } else if (/HTTP 404/.test(fallback.error || "") || /not in fixture/.test(fallback.error || "")) {
+      // Both sources tried, both 404 — combine the error message.
+      const combined = { ok: false, verb: "refresh", error: `--advisory ${id}: not found in GHSA or OSV (GHSA: ${result.error}; OSV: ${fallback.error})`, source: "offline", routed_to: "ghsa+osv", hint: `Both GHSA and OSV.dev returned 404 for ${id}. Verify the CVE id (CVE-YYYY-NNNN) and that an advisory record exists upstream.` };
+      if (opts.json) process.stdout.write(JSON.stringify(combined) + "\n");
+      else process.stderr.write(`[refresh --advisory] ${combined.error}\n  hint: ${combined.hint}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   if (!result.ok) {
     const err = { ok: false, verb: "refresh", error: `--advisory ${id}: ${result.error}`, source: result.source, routed_to: sourceName, hint: `Verify the ID format (CVE-YYYY-NNNN, GHSA-*, MAL-*, SNYK-*, RUSTSEC-*, USN-*, etc.) and network reachability. Set ${fixtureEnv} for offline testing.` };
     if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
@@ -869,17 +1016,21 @@ async function seedSingleAdvisory(opts) {
     process.exitCode = 2;
     return;
   }
+  // If the OSV fallback fired, normalize/route through the OSV module from
+  // here on — the advisory shape is OSV's, not GHSA's.
+  const effectiveMod = fallbackSourceUsed === "osv" ? osvMod : sourceMod;
+  const effectiveName = fallbackSourceUsed === "osv" ? "osv" : sourceName;
   const advisory = result.advisories[0];
   if (!advisory) {
-    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: no matching advisory found`, source: result.source, routed_to: sourceName };
+    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: no matching advisory found`, source: result.source, routed_to: effectiveName };
     if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
     else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
     process.exitCode = 2;
     return;
   }
-  const normalized = sourceMod.normalizeAdvisory(advisory);
+  const normalized = effectiveMod.normalizeAdvisory(advisory);
   if (!normalized) {
-    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: advisory could not be normalized (missing required fields)`, routed_to: sourceName, source_id: advisory.ghsa_id || advisory.id || null };
+    const err = { ok: false, verb: "refresh", error: `--advisory ${id}: advisory could not be normalized (missing required fields)`, routed_to: effectiveName, source_id: advisory.ghsa_id || advisory.id || null };
     if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
     else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
     process.exitCode = 2;
@@ -911,18 +1062,29 @@ async function seedSingleAdvisory(opts) {
 
   // Apply: write to cve-catalog.json with the _auto_imported flag.
   // v0.12.8: honor --catalog / EXCEPTD_CVE_CATALOG so tests can redirect.
+  // v0.12.12 C1: lock-gated RMW. Without this, two concurrent
+  // `refresh --advisory CVE-A --apply` + `--advisory CVE-B --apply`
+  // processes against the same catalog silently dropped one CVE 1-in-20
+  // trials (read-old → mutate → write-overwrites-sibling-mutation).
   const catalogPath = resolveCatalogPath(opts);
-  const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
-  if (catalog[cveId] && !catalog[cveId]._auto_imported && !catalog[cveId]._draft) {
-    // Refuse to overwrite a human-curated entry.
-    const err = { ok: false, verb: "refresh", error: `${cveId} already present in catalog and is human-curated (not a draft). Refusing to overwrite. Edit manually if intentional.`, existing_last_updated: catalog[cveId].last_updated };
+  let humanCurated = null;
+  await withCatalogLock(catalogPath, (catalog) => {
+    if (catalog[cveId] && !catalog[cveId]._auto_imported && !catalog[cveId]._draft) {
+      // Refuse to overwrite a human-curated entry — signal via closure so
+      // we can emit the structured error after the lock releases.
+      humanCurated = { last_updated: catalog[cveId].last_updated };
+      return catalog; // unchanged write — idempotent, releases lock
+    }
+    catalog[cveId] = normalized[cveId];
+    return catalog;
+  });
+  if (humanCurated) {
+    const err = { ok: false, verb: "refresh", error: `${cveId} already present in catalog and is human-curated (not a draft). Refusing to overwrite. Edit manually if intentional.`, existing_last_updated: humanCurated.last_updated };
     if (opts.json) process.stdout.write(JSON.stringify(err) + "\n");
     else process.stderr.write(`[refresh --advisory] ${err.error}\n`);
     process.exitCode = 4;
     return;
   }
-  catalog[cveId] = normalized[cveId];
-  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + "\n", "utf8");
   const output = {
     ok: true,
     verb: "refresh",
@@ -943,7 +1105,9 @@ async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
     printHelp();
-    process.exit(0);
+    // v0.12.12 C3: exitCode + return so buffered stdout flushes naturally.
+    process.exitCode = 0;
+    return;
   }
 
   // v0.12.0: `--advisory <id>` short-circuits the normal source loop and
@@ -1040,7 +1204,12 @@ async function main() {
     }
   }
 
-  process.exit(hadFailure ? 1 : 0);
+  // v0.12.12 C3: same anti-pattern v0.12.9 fixed in prefetch's main(). After
+  // Promise.all(sources.map(runOne)) in --swarm mode, process.exit() could
+  // truncate buffered stdout (refresh-report path log line, summary log
+  // lines piped to a consumer). exitCode + return lets the event loop end
+  // naturally and stdout drains in full.
+  process.exitCode = hadFailure ? 1 : 0;
 }
 
 async function sequential(items, fn) {
@@ -1056,11 +1225,18 @@ if (require.main === module) {
     if (err && err._exceptd_hint) {
       console.error(err.message);
       console.error(JSON.stringify({ ok: false, error: err.message.split("\n")[0], hint: err.message.split("\n").slice(1).join(" ").trim(), verb: "refresh" }));
+    } else if (err && err._exceptd_unknown_source) {
+      // v0.12.12 C3: surface the source-validation error without leaking a
+      // stack trace; chosenSources throws this for unknown --source values.
+      console.error(err.message);
     } else {
       console.error(`refresh-external: fatal: ${err && err.stack ? err.stack : err}`);
     }
-    process.exit(2);
+    // v0.12.12 C3: exitCode + return rather than process.exit(2) — the
+    // event loop has no further work after main()'s rejection, so this
+    // ends the process with code 2 but lets stderr drain first.
+    process.exitCode = 2;
   });
 }
 
-module.exports = { ALL_SOURCES, loadCtx, parseArgs };
+module.exports = { ALL_SOURCES, loadCtx, parseArgs, seedSingleAdvisory, withCatalogLock, writeJsonAtomic };

package/lib/refresh-network.js

@@ -125,6 +125,18 @@ function parseTar(buf) {
   const entries = [];
   let offset = 0;
   let pendingLongName = null;
+  // v0.12.12: tarballs from a compromised registry CDN could ship entries
+  // with `..`-bearing names targeting paths outside the install root. The
+  // immediate callers (verify-shipped-tarball.js + the network update path)
+  // do hash + signature checks before honoring entries, so this is
+  // defense-in-depth — drop the entry rather than handing a path-traversal
+  // string downstream.
+  const isSafeName = (n) => {
+    if (typeof n !== "string" || n.length === 0) return false;
+    // Reject absolute paths AND any segment that is exactly ".."
+    if (/^[\\/]/.test(n) || /^[A-Za-z]:[\\/]/.test(n)) return false;
+    return !n.split(/[\\/]/).some((seg) => seg === "..");
+  };
   while (offset + 512 <= buf.length) {
     const block = buf.subarray(offset, offset + 512);
     // empty block = end-of-archive marker
@@ -141,7 +153,9 @@ function parseTar(buf) {
     if (type === "L") {
       pendingLongName = buf.subarray(dataStart, dataEnd).toString("utf8").replace(/\0.*$/, "");
     } else if (type === "0" || type === "" || type === "\0") {
-      entries.push({ name, body: buf.subarray(dataStart, dataEnd) });
+      if (isSafeName(name)) {
+        entries.push({ name, body: buf.subarray(dataStart, dataEnd) });
+      }
     }
     // round up to 512
     offset = dataStart + Math.ceil(size / 512) * 512;