@blamejs/exceptd-skills 0.12.11 → 0.12.15

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

@@ -141,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
@@ -214,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 };
   },
 };
@@ -297,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 };
   },
 };
@@ -342,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 };
   },
 };
@@ -398,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 };
   },
 };
@@ -520,20 +549,31 @@ const GHSA_SOURCE = {
     return ghsa.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    const ghsa = require("./source-ghsa");
+    // v0.12.14 (audit B-F1): the prior shape mutated ctx.cveCatalog in
+    // memory but NEVER persisted to disk. Bulk `--source ghsa --apply`
+    // reported "applied: N updates" while the catalog file gained zero
+    // entries. Worse under `--swarm`: KEV's withCatalogLock would re-read
+    // catalog from disk INSIDE the lock and overwrite the unflushed
+    // in-memory mutations. Route through the same withCatalogLock helper
+    // that KEV/EPSS/NVD/RFC use (v0.12.12 concurrency fix).
+    const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
     let updated = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (d.field !== "_new_entry") continue;
-      if (!d.after || !d.id) continue;
-      if (ctx.cveCatalog[d.id]) continue; // never overwrite existing entries
-      try {
-        ctx.cveCatalog[d.id] = d.after;
-        updated++;
-      } catch (e) {
-        errors.push(`${d.id}: ${e.message}`);
+    await withCatalogLock(catalogPath, (catalog) => {
+      for (const d of diffs) {
+        if (d.field !== "_new_entry") continue;
+        if (!d.after || !d.id) continue;
+        if (catalog[d.id]) continue; // never overwrite existing entries
+        try {
+          catalog[d.id] = d.after;
+          updated++;
+        } catch (e) {
+          errors.push(`${d.id}: ${e.message}`);
+        }
       }
-    }
+      ctx.cveCatalog = catalog;
+      return catalog;
+    });
     return { updated, errors };
   },
 };
@@ -562,20 +602,27 @@ const OSV_SOURCE = {
     return osv.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    // Same shape as GHSA applyDiff — skip overwrites, surface conflicts.
+    // v0.12.14 (audit B-F1): same fix as GHSA — route the read-modify-write
+    // through withCatalogLock so writes actually land on disk and so
+    // concurrent --source osv --apply doesn't lose updates.
+    const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
     let updated = 0;
     const errors = [];
-    for (const d of diffs) {
-      if (d.field !== "_new_entry") continue;
-      if (!d.after || !d.id) continue;
-      if (ctx.cveCatalog[d.id]) continue; // never overwrite existing entries
-      try {
-        ctx.cveCatalog[d.id] = d.after;
-        updated++;
-      } catch (e) {
-        errors.push(`${d.id}: ${e.message}`);
+    await withCatalogLock(catalogPath, (catalog) => {
+      for (const d of diffs) {
+        if (d.field !== "_new_entry") continue;
+        if (!d.after || !d.id) continue;
+        if (catalog[d.id]) continue; // never overwrite existing entries
+        try {
+          catalog[d.id] = d.after;
+          updated++;
+        } catch (e) {
+          errors.push(`${d.id}: ${e.message}`);
+        }
       }
-    }
+      ctx.cveCatalog = catalog;
+      return catalog;
+    });
     return { updated, errors };
   },
 };
@@ -824,8 +871,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) {
@@ -834,8 +970,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]);
   }
@@ -939,18 +1080,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",
@@ -971,7 +1123,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
@@ -1068,7 +1222,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) {
@@ -1084,11 +1243,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, seedSingleAdvisory };
+module.exports = { ALL_SOURCES, loadCtx, parseArgs, seedSingleAdvisory, withCatalogLock, writeJsonAtomic };