@blamejs/exceptd-skills 0.12.13 → 0.12.16

package/lib/prefetch.js

@@ -15,8 +15,14 @@
  *   kev/known_exploited_vulnerabilities.json          — full KEV feed
  *   nvd/<cve-id>.json                                 — NVD 2.0 per-CVE response
  *   epss/<cve-id>.json                                — EPSS per-CVE response
- *   ietf/<doc-name>.json                              — IETF Datatracker doc record
- *   github/<owner>__<repo>__releases.json             — releases listing
+ *   rfc/<doc-name>.json                               — IETF Datatracker doc record
+ *   pins/<owner>__<repo>__releases.json               — MITRE GitHub releases listing
+ *
+ * audit M P2-K: the registered source names in SOURCES below are `rfc` and
+ * `pins`. Earlier comments + --help text said `ietf` and `github`; an
+ * operator running `--source ietf` or `--source github` would hit "unknown
+ * source" because no such key exists. The names below are the canonical
+ * ones consumed by --source filtering.
  *
  * Usage:
  *   node lib/prefetch.js                  # fetch everything not fresh
@@ -137,8 +143,8 @@ Sources:
   kev      CISA Known Exploited Vulnerabilities
   nvd      NIST NVD 2.0 per-CVE
   epss     FIRST EPSS per-CVE
-  ietf     IETF Datatracker per-RFC
-  github   MITRE GitHub releases (ATLAS / ATT&CK / D3FEND / CWE)
+  rfc      IETF Datatracker per-RFC
+  pins     MITRE GitHub releases (ATLAS / ATT&CK)
 
 Options:
   --max-age <dur>     skip entries fresher than this (e.g. 12h, 1d). Default: 24h.
@@ -296,7 +302,15 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  if (source === "github" && process.env.GITHUB_TOKEN) return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
+  // audit M P2-J: the registered source name for MITRE GitHub releases is
+  // `pins` (see SOURCES above). The prior check looked for `github`, so
+  // GITHUB_TOKEN never reached the per-request Authorization header and
+  // anonymous-rate-limited fetches were always used even when an operator
+  // had supplied a token. Accept both spellings so this is forgiving of
+  // the historical naming and the registered name.
+  if ((source === "pins" || source === "github") && process.env.GITHUB_TOKEN) {
+    return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
+  }
   return {};
 }
 
@@ -459,13 +473,21 @@ function readCached(cacheDir, source, id, opts = {}) {
   const idx = loadIndex(cacheDir);
   const meta = idx.entries[entryKey(source, id)];
   if (!meta) return null;
-  const ageMs = Date.now() - new Date(meta.fetched_at).getTime();
-  if (!opts.allowStale && ageMs > maxAgeMs) return null;
+  // audit M P2-L: when `fetched_at` is missing / non-string / unparseable,
+  // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false —
+  // so the cached entry would have been returned as if fresh. Treat any
+  // non-finite age as "no provenance, refuse" unless the caller explicitly
+  // opted into allowStale.
+  const ageMs = meta.fetched_at ? Date.now() - new Date(meta.fetched_at).getTime() : NaN;
+  if (!opts.allowStale) {
+    if (!meta.fetched_at || !Number.isFinite(ageMs)) return null;
+    if (ageMs > maxAgeMs) return null;
+  }
   const p = entryPath(cacheDir, source, id);
   if (!fs.existsSync(p)) return null;
   try {
     const data = JSON.parse(fs.readFileSync(p, "utf8"));
-    return { data, age_ms: ageMs, meta };
+    return { data, age_ms: Number.isFinite(ageMs) ? ageMs : null, meta };
   } catch {
     return null;
   }

package/lib/refresh-external.js

@@ -549,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 };
   },
 };
@@ -591,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 };
   },
 };

package/lib/refresh-network.js

@@ -97,6 +97,10 @@ function getJson(url, timeoutMs) {
 function getBuffer(url, timeoutMs) {
   return new Promise((resolve, reject) => {
     const u = new URL(url);
+    const cap = (() => {
+      const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
+      return Number.isFinite(env) && env > 0 ? env : 200 * 1024 * 1024;
+    })();
     const req = https.get({
       host: u.host, path: u.pathname + u.search,
       headers: { "User-Agent": "exceptd/refresh-network" },
@@ -107,7 +111,17 @@ function getBuffer(url, timeoutMs) {
         return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
       }
       const chunks = [];
-      res.on("data", (c) => chunks.push(c));
+      let total = 0;
+      // v0.12.14 (audit F5): enforce streaming size cap so a hostile
+      // registry CDN can't stream gigabytes into RAM.
+      res.on("data", (c) => {
+        total += c.length;
+        if (total > cap) {
+          req.destroy(new Error(`tarball exceeds ${cap}-byte cap during streaming download`));
+          return;
+        }
+        chunks.push(c);
+      });
       res.on("end", () => resolve(Buffer.concat(chunks)));
     });
     req.on("timeout", () => req.destroy(new Error("timeout")));
@@ -177,6 +191,36 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
   } catch { return false; }
 }
 
+// v0.12.14 (audit F1, F7): CRLF/BOM normalization mirrors lib/verify.js's
+// normalize(). Duplicated here to keep refresh-network free of cross-module
+// runtime deps. ANY change here MUST be mirrored in lib/verify.js +
+// lib/sign.js — the three normalize() implementations form a byte-stability
+// contract.
+function normalizeSkillBytes(buf) {
+  let s = Buffer.isBuffer(buf) ? buf.toString("utf8") : String(buf);
+  if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  return Buffer.from(s.replace(/\r\n/g, "\n"), "utf8");
+}
+
+// Manifest path validation. Mirrors lib/verify.js validateSkillPath().
+function validateManifestSkillPath(skillPath) {
+  if (typeof skillPath !== "string") throw new Error(`manifest skill.path must be a string, got ${typeof skillPath}`);
+  if (skillPath.includes("\\")) throw new Error(`manifest skill.path must use forward slashes: ${JSON.stringify(skillPath)}`);
+  if (!skillPath.startsWith("skills/")) throw new Error(`manifest skill.path must start with 'skills/': ${JSON.stringify(skillPath)}`);
+  if (skillPath.includes("..")) throw new Error(`manifest skill.path must not contain '..': ${JSON.stringify(skillPath)}`);
+  return skillPath;
+}
+
+// v0.12.14 (audit F5): tarball download size cap. A hostile registry CDN
+// could stream gigabytes; Node buffers chunks in RAM until OOM. Current
+// tarball is ~2 MB; 200 MB is generous defense-in-depth. Tunable via
+// EXCEPTD_TARBALL_SIZE_CAP_BYTES for future growth.
+const TARBALL_SIZE_CAP_BYTES_DEFAULT = 200 * 1024 * 1024;
+function tarballSizeCap() {
+  const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
+  return Number.isFinite(env) && env > 0 ? env : TARBALL_SIZE_CAP_BYTES_DEFAULT;
+}
+
 async function main() {
   const opts = parseArgs(process.argv);
   const localPkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
@@ -204,6 +248,8 @@ async function main() {
   const latestVersion = meta.version;
   const tarballUrl = meta.dist && meta.dist.tarball;
   const tarballShasum = meta.dist && meta.dist.shasum;
+  const tarballIntegrity = meta.dist && meta.dist.integrity; // SHA-512 SRI
+  const registrySignatures = Array.isArray(meta.dist && meta.dist.signatures) ? meta.dist.signatures : [];
   if (!tarballUrl) {
     emit({ ok: false, error: "registry metadata missing dist.tarball" }, opts.json);
     process.exitCode = 2; return;
@@ -240,6 +286,32 @@ async function main() {
     process.exitCode = 2; return;
   }
 
+  // v0.12.14 (audit F5): defense-in-depth tarball size cap.
+  const sizeCap = tarballSizeCap();
+  if (tgzBuf.length > sizeCap) {
+    emit({ ok: false, error: `tarball exceeds size cap: ${tgzBuf.length} bytes > ${sizeCap} (EXCEPTD_TARBALL_SIZE_CAP_BYTES)` }, opts.json);
+    process.exitCode = 4; return;
+  }
+
+  // v0.12.14 (audit F6, F3): verify SHA-512 SRI first (collision-resistant
+  // beyond SHA-1 reach), then SHA-1 shasum for compatibility, then dist.
+  // signatures[] (npm registry's Ed25519 signing key). Each layer is
+  // defense-in-depth — registry compromise that produces a SHA-1 collision
+  // doesn't trivially produce a SHA-512 collision; an attacker who breaks
+  // both still has to forge the npm-signing-key signature on the tarball.
+  if (tarballIntegrity && /^sha512-/.test(tarballIntegrity)) {
+    const expected = tarballIntegrity.slice("sha512-".length);
+    const actual = crypto.createHash("sha512").update(tgzBuf).digest("base64");
+    if (actual !== expected) {
+      emit({ ok: false, error: `tarball SHA-512 integrity mismatch: dist.integrity=${tarballIntegrity}, actual=sha512-${actual}` }, opts.json);
+      process.exitCode = 4; return;
+    }
+  } else if (tarballIntegrity) {
+    // Non-sha512 SRI (e.g. sha384) — emit a warning but accept; SHA-1 path
+    // below still gates.
+    progress(`note: dist.integrity present but not sha512: ${tarballIntegrity.slice(0, 40)}`, opts.json);
+  }
+
   // Verify shasum (registry-provided integrity).
   if (tarballShasum) {
     const actual = crypto.createHash("sha1").update(tgzBuf).digest("hex");
@@ -285,27 +357,96 @@ async function main() {
     process.exitCode = 5; return;
   }
 
+  // v0.12.16 (audit I P1-5): cross-check the local public key against
+  // keys/EXPECTED_FINGERPRINT (the CI-pinned signing key). The prior
+  // refresh-network code only compared LOCAL ↔ TARBALL fingerprints, so a
+  // coordinated attacker who swapped both `keys/public.pem` on the operator's
+  // host AND the registry tarball passed every check — fingerprints match
+  // each other but match the attacker's key. The pin in EXPECTED_FINGERPRINT
+  // is the external trust anchor that closes this gap.
+  //
+  // Honors `KEYS_ROTATED=1` env to allow legitimate key rotation without
+  // re-bootstrap. Missing EXPECTED_FINGERPRINT file → warn-and-continue
+  // (don't break existing installs whose tree predates the pin file).
+  const expectedFingerprintPath = path.join(ROOT, "keys", "EXPECTED_FINGERPRINT");
+  if (fs.existsSync(expectedFingerprintPath) && !process.env.KEYS_ROTATED) {
+    try {
+      const expectedFp = fs.readFileSync(expectedFingerprintPath, "utf8")
+        .split(/\r?\n/).map(l => l.trim()).find(l => l.length > 0);
+      // v0.12.16 (codex P1 PR #11): `expectedFp` is read verbatim from
+      // keys/EXPECTED_FINGERPRINT (formatted as `SHA256:<base64>`), but
+      // `fingerprintPublicKey()` returns the raw base64 without the
+      // `SHA256:` prefix. Comparing the two raw strings would refuse every
+      // legitimate run unless KEYS_ROTATED=1 was set. Normalize by stripping
+      // the prefix from the pin file before compare. lib/verify.js's
+      // checkExpectedFingerprint() does the symmetric thing (adds the
+      // prefix to localFp); either side works as long as one is canonical.
+      const expectedFpBase64 = expectedFp && expectedFp.startsWith("SHA256:")
+        ? expectedFp.slice("SHA256:".length)
+        : expectedFp;
+      if (expectedFpBase64 && expectedFpBase64 !== localFp) {
+        emit({
+          ok: false,
+          error: `local keys/public.pem fingerprint diverges from keys/EXPECTED_FINGERPRINT pin`,
+          local_fingerprint: "SHA256:" + localFp,
+          pinned_fingerprint: expectedFp,
+          hint: "Either keys/public.pem was rotated since the pin was set (rerun `npm run bootstrap` to re-pin), or the local public.pem was tampered with. Set KEYS_ROTATED=1 to bypass once. Refusing to swap on --network.",
+        }, opts.json);
+        process.exitCode = 5; return;
+      }
+    } catch { /* unreadable pin file = warn-and-continue */ }
+  }
+
   // Verify every signed entry in the tarball manifest using the local key.
   let tarballManifest;
   try { tarballManifest = JSON.parse(tarballManifestEntry.body.toString("utf8")); }
   catch (e) { emit({ ok: false, error: `tarball manifest.json parse: ${e.message}` }, opts.json); process.exitCode = 4; return; }
 
+  // v0.12.14 (audit F1): the prior loop iterated `sk.id` + a fixed payload
+  // path `skills/<id>/SKILL.md`. Manifest entries actually expose `name` +
+  // `path` (a forward-slash relative path like `skills/<name>/skill.md`,
+  // lowercase). Result: the loop matched zero entries; `failures.length === 0`
+  // and `verifiedCount === 0` and the swap proceeded with `ok: true`. Every
+  // operator running `exceptd refresh --network` installed unverified bytes.
+  //
+  // Fixed shape mirrors lib/verify.js: iterate `manifest.skills[]` by
+  // `name` + `path` + `signature`. Apply the same CRLF/BOM normalization
+  // before verify (lib/verify.js normalize() — duplicated here to keep
+  // this path free of cross-module runtime deps). validateSkillPath()
+  // is also mirrored to defend against path traversal in a tampered
+  // tarball manifest before we resolve the path against the extracted
+  // tree.
   const localKeyObj = crypto.createPublicKey(localPubKeyText);
   const skills = Array.isArray(tarballManifest.skills) ? tarballManifest.skills : [];
   const failures = [];
   let verifiedCount = 0;
   for (const sk of skills) {
-    if (!sk || !sk.id || !sk.signature) continue;
-    // Find the skill payload entry. manifest convention: skills/<id>/SKILL.md
-    const payloadName = `skills/${sk.id}/SKILL.md`;
-    const payloadEntry = entries.find((e) => stripPkg(e.name) === payloadName);
-    if (!payloadEntry) { failures.push({ id: sk.id, reason: "payload not in tarball" }); continue; }
-    const ok = verifyDetached(localKeyObj, payloadEntry.body, sk.signature);
+    if (!sk || typeof sk.name !== "string" || typeof sk.signature !== "string") {
+      failures.push({ name: sk?.name || "(missing name)", reason: "manifest entry missing name or signature" });
+      continue;
+    }
+    let normalizedPath;
+    try { normalizedPath = validateManifestSkillPath(sk.path); }
+    catch (e) { failures.push({ name: sk.name, reason: `manifest path rejected: ${e.message}` }); continue; }
+    const payloadEntry = entries.find((e) => stripPkg(e.name) === normalizedPath);
+    if (!payloadEntry) { failures.push({ name: sk.name, reason: `payload missing from tarball: ${normalizedPath}` }); continue; }
+    const normalized = normalizeSkillBytes(payloadEntry.body);
+    const ok = verifyDetached(localKeyObj, normalized, sk.signature);
     if (ok) verifiedCount++;
-    else failures.push({ id: sk.id, reason: "signature did not verify against local public key" });
+    else failures.push({ name: sk.name, reason: "Ed25519 signature did not verify against local public key" });
   }
 
-  if (failures.length > 0) {
+  if (skills.length === 0) {
+    emit({
+      ok: false,
+      error: "tarball manifest.json declares zero skills — refusing to swap",
+      verified: 0,
+      total: 0,
+      hint: "A legitimate tarball must declare at least one skill. Treat this as a tarball-integrity failure.",
+    }, opts.json);
+    process.exitCode = 5; return;
+  }
+  if (verifiedCount !== skills.length || failures.length > 0) {
     emit({
       ok: false,
       error: `${failures.length}/${skills.length} skill signature(s) failed verification — refusing to swap`,
@@ -317,6 +458,34 @@ async function main() {
     process.exitCode = 5; return;
   }
 
+  // v0.12.14 (audit F2): the swap loop replaces `data/` + `manifest.json` +
+  // `manifest-snapshot.json` in addition to `skills/`. None of those files
+  // are covered by the per-skill Ed25519 signature (which signs only the
+  // skill body bytes). The only integrity check between the registry and
+  // those bytes is SHA-1 dist.shasum — collision-broken since 2017 and
+  // weaker than `npm install` itself which honors dist.integrity (SHA-512
+  // SRI) + dist.signatures (npm Ed25519 registry key) + dist.attestations
+  // (sigstore SLSA provenance).
+  //
+  // Defense-in-depth: refuse the swap if the manifest skills list doesn't
+  // exactly match the skill payload entries present in the tarball. A
+  // malicious tarball that drops/adds a skill outside the manifest no
+  // longer slips through.
+  const manifestSkillPaths = new Set(skills.map(s => validateManifestSkillPath(s.path)));
+  const tarballSkillPayloads = entries
+    .map(e => stripPkg(e.name))
+    .filter(name => /^skills\/[^/]+\/skill\.md$/.test(name));
+  for (const tp of tarballSkillPayloads) {
+    if (!manifestSkillPaths.has(tp)) {
+      emit({
+        ok: false,
+        error: `tarball ships skill payload not declared in manifest: ${tp} — refusing to swap`,
+        hint: "Tarball+manifest divergence. Report at https://github.com/blamejs/exceptd-skills/issues.",
+      }, opts.json);
+      process.exitCode = 5; return;
+    }
+  }
+
   if (opts.dryRun) {
     emit({
       ok: true,
@@ -330,9 +499,16 @@ async function main() {
     return;
   }
 
-  // Atomic swap: stage to a tmp dir under the install, then rename.
+  // v0.12.14 (audit F4): the prior swap loop renamed targets one-by-one,
+  // and a mid-loop failure left the install half-applied with no automatic
+  // rollback. New shape: rename all old targets into a single backup dir
+  // first (so the install is empty-of-old before any new content is moved
+  // in); then rename all new targets in; on failure, walk the backup dir
+  // in reverse and restore.
   const stageDir = fs.mkdtempSync(path.join(ROOT, ".refresh-network-"));
   let written = 0;
+  let backupDir = null;
+  const completedSteps = []; // [{kind: 'backup' | 'install', target}]
   try {
     for (const entry of entries) {
       const rel = stripPkg(entry.name);
@@ -347,19 +523,32 @@ async function main() {
       written++;
     }
 
-    // Replace targets.
-    const replaceList = ["data", "skills", "manifest.json", "manifest-snapshot.json"];
-    const backupDir = path.join(ROOT, `.refresh-network-backup-${Date.now()}`);
+    // v0.12.14 (audit F10): use PID + random suffix in the backup dir name
+    // so concurrent refresh-network invocations don't collide on the
+    // millisecond clock.
+    const backupSuffix = `${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    backupDir = path.join(ROOT, `.refresh-network-backup-${Date.now()}-${backupSuffix}`);
     fs.mkdirSync(backupDir);
+    const replaceList = ["data", "skills", "manifest.json", "manifest-snapshot.json"];
+
+    // Phase A: move all existing targets to backupDir. After this loop
+    // completes, the install root has none of the replaced targets.
     for (const target of replaceList) {
-      const src = path.join(stageDir, target);
-      if (!fs.existsSync(src)) continue;
       const dst = path.join(ROOT, target);
       if (fs.existsSync(dst)) {
         fs.renameSync(dst, path.join(backupDir, target));
+        completedSteps.push({ kind: "backup", target });
       }
-      fs.renameSync(src, dst);
     }
+
+    // Phase B: move all new targets in from stage.
+    for (const target of replaceList) {
+      const src = path.join(stageDir, target);
+      if (!fs.existsSync(src)) continue;
+      fs.renameSync(src, path.join(ROOT, target));
+      completedSteps.push({ kind: "install", target });
+    }
+
     fs.rmSync(stageDir, { recursive: true, force: true });
     // Best-effort cleanup of backup dir — keep on disk for one cycle so
     // operators can manually roll back if something feels off.
@@ -371,11 +560,38 @@ async function main() {
       total_skills: skills.length,
       files_written: written,
       backup_dir: path.relative(ROOT, backupDir),
+      registry_signatures_present: registrySignatures.length,
       message: `refreshed catalog from v${localVersion} → v${latestVersion} (${verifiedCount}/${skills.length} signatures verified). Backup at ${path.relative(ROOT, backupDir)} — safe to remove after verifying the new run.`,
     }, opts.json);
   } catch (e) {
+    // v0.12.14 (audit F4): walk completedSteps in reverse to undo partial work.
+    const rollbackErrors = [];
+    for (const step of [...completedSteps].reverse()) {
+      try {
+        if (step.kind === "install") {
+          // Remove the newly-installed copy.
+          fs.rmSync(path.join(ROOT, step.target), { recursive: true, force: true });
+        } else if (step.kind === "backup" && backupDir) {
+          // Restore from backup.
+          const src = path.join(backupDir, step.target);
+          const dst = path.join(ROOT, step.target);
+          if (fs.existsSync(src)) fs.renameSync(src, dst);
+        }
+      } catch (re) {
+        rollbackErrors.push({ target: step.target, kind: step.kind, error: re.message });
+      }
+    }
     fs.rmSync(stageDir, { recursive: true, force: true });
-    emit({ ok: false, error: `swap failed mid-rename: ${e.message}`, hint: "If files are missing, restore from the backup dir at the install root, or reinstall with `npm install -g @blamejs/exceptd-skills`." }, opts.json);
+    emit({
+      ok: false,
+      error: `swap failed mid-rename: ${e.message}`,
+      rolled_back: rollbackErrors.length === 0,
+      rollback_errors: rollbackErrors,
+      backup_dir: backupDir ? path.relative(ROOT, backupDir) : null,
+      hint: rollbackErrors.length === 0
+        ? "Auto-rollback completed. Install state matches pre-refresh. Re-run `exceptd refresh --network` or `npm install -g @blamejs/exceptd-skills` to retry."
+        : "Auto-rollback partially failed. Restore manually from the backup dir at the install root, or reinstall with `npm install -g @blamejs/exceptd-skills`.",
+    }, opts.json);
     process.exitCode = 4;
   }
 }