@blamejs/exceptd-skills 0.12.22 → 0.12.23

package/lib/prefetch.js

@@ -18,11 +18,10 @@
  *   rfc/<doc-name>.json                               — IETF Datatracker doc record
  *   pins/<owner>__<repo>__releases.json               — MITRE GitHub releases listing
  *
- * 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.
+ * The registered source names in SOURCES below are `rfc` and `pins`.
+ * `--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
@@ -237,7 +236,7 @@ async function withIndexLock(cacheDir, mutator) {
       // 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;
-      // T P1-1: PID-liveness check. Same pattern as withCatalogLock in
+      // PID-liveness check. Same pattern as withCatalogLock in
       // lib/refresh-external.js — read the lockfile's PID, probe with
       // process.kill(pid, 0); ESRCH → holder dead, reclaim immediately;
       // EPERM → holder alive (different user), keep waiting. The mtime
@@ -322,11 +321,12 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // 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 registered source name for MITRE GitHub releases is `pins`
+  // (see SOURCES above). Accept both `pins` and `github` so GITHUB_TOKEN
+  // reaches the per-request Authorization header regardless of which
+  // spelling the operator's automation uses; without this, anonymous
+  // rate-limited fetches happen even when a token is configured. Be
+  // 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}` };
@@ -415,14 +415,14 @@ async function prefetch(options = {}) {
         const dir = path.dirname(targetPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         const body = JSON.stringify(res.json, null, 2) + "\n";
-        // T P1-3: stage the payload to a same-volume tmp file BEFORE
-        // attempting to acquire the index lock. If withIndexLock fails
-        // (timeout after MAX_RETRIES), we want the partially-completed
-        // download discarded — not left on disk as an orphan payload
-        // with no index entry. Air-gap operators feed off `readCached`,
-        // which consults the index; an unindexed payload silently becomes
-        // junk taking cache space. Pattern: stage → lock → rename+index
-        // → release. The rename is atomic same-volume; if it fails inside
+        // Stage the payload to a same-volume tmp file BEFORE attempting
+        // to acquire the index lock. If withIndexLock fails (timeout
+        // after MAX_RETRIES), the partially-completed download must be
+        // discarded — not left on disk as an orphan payload with no
+        // index entry. Air-gap operators feed off `readCached`, which
+        // consults the index; an unindexed payload silently becomes junk
+        // taking cache space. Pattern: stage → lock → rename+index →
+        // release. The rename is atomic same-volume; if it fails inside
         // the lock we clean up the tmp file. If we never reach the rename
         // (lock acquisition throws), the tmp file is unlinked in the
         // catch block below.
@@ -520,8 +520,8 @@ function readCached(cacheDir, source, id, opts = {}) {
   const idx = loadIndex(cacheDir);
   const meta = idx.entries[entryKey(source, id)];
   if (!meta) return null;
-  // L: when `fetched_at` is missing / non-string / unparseable,
-  // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false —
+  // 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.

package/lib/refresh-external.js

@@ -94,11 +94,9 @@ function parseArgs(argv) {
     else if (a.startsWith("--from-fixture=")) out.fromFixture = a.slice("--from-fixture=".length);
     else if (a === "--report-out") out.reportOut = argv[++i];
     else if (a.startsWith("--report-out=")) out.reportOut = a.slice("--report-out=".length);
-    // FF P1-3: previously only EXCEPTD_AIR_GAP=1 reached the GHSA/OSV source
-    // modules — the CLI flag was undocumented in parseArgs, so a downstream
-    // operator following the documented `--air-gap` path silently allowed
-    // network calls. Now the flag is honoured; env var still works as a
-    // fallback so existing automation isn't broken.
+    // Honour `--air-gap` here so it reaches the GHSA/OSV source modules.
+    // EXCEPTD_AIR_GAP=1 still works as an env-var fallback so existing
+    // automation isn't broken.
     else if (a === "--air-gap") out.airGap = true;
   }
   return out;
@@ -852,10 +850,9 @@ function loadCtx(opts) {
     d3fendCatalog: JSON.parse(fs.readFileSync(ABS("data/d3fend-catalog.json"), "utf8")),
     fixtures: null,
     cacheDir: null,
-    // FF P1-3: thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap
-    // so the GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
-    // can branch on ctx.airGap and refuse network egress. Pre-fix the GHSA/OSV
-    // sources only saw `ctx?.airGap` as undefined when the CLI flag was used.
+    // Thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap so the
+    // GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
+    // branch on it and refuse network egress.
     airGap: !!(opts && opts.airGap) || process.env.EXCEPTD_AIR_GAP === "1",
   };
   if (opts.fromFixture) {
@@ -949,15 +946,15 @@ async function withCatalogLock(catalogPath, mutator) {
       // 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;
-      // T P1-1: PID-liveness check before falling back to mtime. The
-      // lockfile already contains String(process.pid) of the holder; parse
-      // it and probe with `process.kill(pid, 0)`. ESRCH means the holder is
-      // dead — reclaim immediately rather than waiting STALE_LOCK_MS for
-      // the mtime gate to expire. EPERM (holder alive, different user) is
-      // treated as "alive, keep waiting." The mtime gate remains as a
-      // belt-and-suspenders for the case where the lockfile content is
-      // missing / malformed / belongs to a recycled PID. Matches the PID
-      // pattern in orchestrator/index.js _acquireWatchLock and
+      // PID-liveness check before falling back to mtime. The lockfile
+      // contains String(process.pid) of the holder; parse it and probe with
+      // `process.kill(pid, 0)`. ESRCH means the holder is dead — reclaim
+      // immediately rather than waiting STALE_LOCK_MS for the mtime gate
+      // to expire. EPERM (holder alive, different user) is treated as
+      // "alive, keep waiting." The mtime gate remains as a belt-and-
+      // suspenders for cases where the lockfile content is missing /
+      // malformed / belongs to a recycled PID. Matches the PID pattern in
+      // orchestrator/index.js _acquireWatchLock and
       // lib/playbook-runner.js pidAlive().
       let reclaimedByPid = false;
       try {

package/lib/refresh-network.js

@@ -418,27 +418,48 @@ async function main() {
   // 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 === "1") {
+    process.emitWarning(
+      `EXPECTED_FINGERPRINT pin check skipped via KEYS_ROTATED=1 during refresh-network. ` +
+      `Update keys/EXPECTED_FINGERPRINT to lock the new pin once rotation completes.`,
+      { code: 'EXCEPTD_KEYS_ROTATED_OVERRIDE' }
+    );
+  }
   if (fs.existsSync(expectedFingerprintPath) && !process.env.KEYS_ROTATED) {
     try {
-      // KK P1-5: route through the shared lib/verify loader so a BOM-prefixed
-      // pin file (Notepad with files.encoding=utf8bom) is tolerated identically
-      // across every verify site. Pre-fix the inline split-trim-find returned
+      // Route through the shared lib/verify loader so a BOM-prefixed pin
+      // file (Notepad with files.encoding=utf8bom) is tolerated identically
+      // across every verify site. An inline split-trim-find would retain
       // the BOM as part of the first line, which would never match a live
       // fingerprint and would block every legitimate refresh-network run.
       const { loadExpectedFingerprintFirstLine } = require("./verify.js");
       const expectedFp = loadExpectedFingerprintFirstLine(expectedFingerprintPath);
-      // v0.12.16 (codex P1 PR #11): `expectedFp` is read verbatim from
-      // keys/EXPECTED_FINGERPRINT (formatted as `SHA256:<base64>`), but
+      // Pin file present but the loader returned null. The loader refuses
+      // UTF-16LE / UTF-16BE pin files and any other shape that cannot be
+      // safely decoded. Treat this as a hard fail: the operator placed a
+      // pin file but the bytes are not consumable, so we must not fall
+      // through to an unpinned refresh. Re-save the pin as UTF-8 (with or
+      // without BOM) and retry.
+      if (expectedFp === null) {
+        emit({
+          ok: false,
+          error: `keys/EXPECTED_FINGERPRINT exists but its bytes could not be parsed (likely UTF-16 BOM or non-UTF-8 encoding)`,
+          pin_path: expectedFingerprintPath,
+          hint: "Re-save the pin file as UTF-8 (the loader accepts UTF-8-with-BOM). Refusing to swap on --network with an unparseable pin.",
+        }, opts.json);
+        process.exitCode = 5; return;
+      }
+      // The pin file is canonically 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:")
+      const expectedFpBase64 = expectedFp.startsWith("SHA256:")
         ? expectedFp.slice("SHA256:".length)
         : expectedFp;
-      if (expectedFpBase64 && expectedFpBase64 !== localFp) {
+      if (expectedFpBase64 !== localFp) {
         emit({
           ok: false,
           error: `local keys/public.pem fingerprint diverges from keys/EXPECTED_FINGERPRINT pin`,
@@ -687,13 +708,13 @@ if (require.main === module) {
 module.exports = {
   parseTar,
   fingerprintPublicKey,
-  // A: exported for tests/normalize-contract.test.js so the
-  // byte-stability contract can be asserted across all four normalize()
-  // implementations (lib/sign.js, lib/verify.js, lib/refresh-network.js,
+  // Exported for tests/normalize-contract.test.js so the byte-stability
+  // contract can be asserted across all four normalize() implementations
+  // (lib/sign.js, lib/verify.js, lib/refresh-network.js,
   // scripts/verify-shipped-tarball.js).
   normalizeSkillBytes,
-  // B + Q P1: exported for in-process tests of the refresh
-  // path's manifest envelope check.
+  // Exported for in-process tests of the refresh path's manifest envelope
+  // check.
   verifyTarballManifestSignature,
   canonicalManifestBytesForRefresh,
 };

package/lib/scoring.js

@@ -92,7 +92,7 @@ function score(cveId, catalog) {
 }
 
 /**
- * E10: Validate an RWEP factor bag. Returns an array of warning strings
+ * Validate an RWEP factor bag. Returns an array of warning strings
  * for missing-but-defaultable fields and out-of-range values. Does NOT
  * throw — operators wanting hard enforcement should treat a non-empty
  * return as a failure themselves.
@@ -342,13 +342,14 @@ function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
-    // FF P1-1: skip auto-imported drafts. KEV/GHSA/OSV-discovered drafts
-    // store a conservative-default rwep_score (poc=true, reboot=true, etc.)
+    // Skip auto-imported drafts. KEV/GHSA/OSV-discovered drafts store a
+    // conservative-default rwep_score (poc=true, reboot=true, etc.)
     // alongside `poc_available: null` and other null-until-curated factor
-    // fields, so the recomputed-vs-stored divergence check ALWAYS fires
-    // against them — flooding the predeploy gate. Drafts are reviewed
-    // separately via the `_auto_imported_meta.curation_needed` list and the
-    // strict catalog validator's draft-warning tier. Once curation promotes
+    // fields, so the recomputed-vs-stored divergence check would always
+    // fire against them and flood the predeploy gate. Drafts are reviewed
+    // separately via the `_auto_imported_meta.curation_needed` list and
+    // the strict catalog validator's draft-warning tier. Once curation
+    // promotes
     // an entry, `_auto_imported` is cleared and full validation resumes.
     if (entry && entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {

package/lib/sign.js

@@ -178,9 +178,9 @@ function signAll() {
 
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
-  // S5: verdict line FIRST, fingerprint banner after. An operator
-  // scrolling output should not be able to see "fingerprint: SHA256..."
-  // and assume success when errors > 0.
+  // Verdict line FIRST, fingerprint banner after. An operator scrolling
+  // output should not be able to see "fingerprint: SHA256..." and assume
+  // success when errors > 0.
   if (errors > 0) {
     console.error(`\n[sign] FAILED — ${signed} signed, ${errors} errors.`);
   } else {
@@ -343,14 +343,13 @@ function canonicalManifestBytes(manifest) {
  * Returns the manifest_signature object literal to splice into the
  * manifest top level.
  *
- * A: the previous shape included a `signed_at` ISO timestamp.
- * That field was stripped from the canonical bytes before signing (via
- * `delete clone.manifest_signature`), so it was NOT covered by the
- * signature — an attacker who replayed a known-valid signature could
- * rewrite `signed_at` to any value, lending false freshness authority to
- * a stale signature. The field is now omitted entirely. Freshness signal
- * lives outside the signed bytes (git-log mtime of manifest.json, npm
- * publish timestamp).
+ * The manifest_signature shape carries `algorithm` + `signature_base64`
+ * only — no `signed_at` ISO timestamp. A `signed_at` field stripped from
+ * the canonical bytes before signing would be unsigned metadata; an
+ * attacker who replayed a known-valid signature could rewrite it to any
+ * value, lending false freshness authority to a stale signature.
+ * Freshness signal lives outside the signed bytes (git-log mtime of
+ * manifest.json, npm publish timestamp).
  *
  * @param {object} manifest
  * @param {string} privateKey PEM-encoded Ed25519 private key

package/lib/source-osv.js

@@ -175,7 +175,7 @@ function osvRequestOnce({ method, reqPath, body, timeoutMs }) {
   return new Promise((resolve, reject) => {
     const t = osvTransport();
     if (t.error) {
-      // F13: surface the validation error structurally; no retry.
+      // Surface the validation error structurally; no retry.
       return resolve({ ok: false, error: t.error, source: "offline" });
     }
     const { mod, host, port } = t;
@@ -539,7 +539,7 @@ function extractCvss(rec) {
     const prev = vectorsByVersion.get(ver);
     if (!prev) vectorsByVersion.set(ver, v);
   }
-  // F10: try versions in descending order. CVSS 4.0 derivation is not yet
+  // Try versions in descending order. CVSS 4.0 derivation is not yet
   // implemented here — if v4 was the highest but can't be computed, walk
   // down to v3.x. Only return null when ALL versions fail.
   const versions = Array.from(vectorsByVersion.keys()).sort((a, b) => b - a);
@@ -737,7 +737,7 @@ function normalizeAdvisory(rec) {
   // OSV.dev canonical advisory URL — used as the primary vendor advisory.
   const osvUrl = `https://osv.dev/vulnerability/${encodeURIComponent(rec.id)}`;
 
-  // F6: dedupe verification_sources. OSV records frequently carry the
+  // Dedupe verification_sources. OSV records frequently carry the
   // canonical osv.dev URL in references[] as well, which would otherwise
   // produce a duplicate alongside the prepended `osvUrl`.
   const verification_sources = Array.from(new Set([
@@ -746,9 +746,9 @@ function normalizeAdvisory(rec) {
     ...refUrls.slice(0, 10),
   ]));
 
-  // F5: EPSS coverage does not extend to non-CVE identifiers. Surface this
+  // EPSS coverage does not extend to non-CVE identifiers. Surface this
   // explicitly so curators know to re-query if MITRE later assigns a CVE
-  // id to the entry. Wording mirrors the MAL-2026-3083 catalog entry.
+  // id to the entry.
   const isCveKey = /^CVE-/i.test(catalogKey);
   const epss_note = isCveKey
     ? null
@@ -840,13 +840,13 @@ async function buildDiff(ctx) {
   const cveCatalog = ctx.cveCatalog || {};
   const existingKeys = new Set(Object.keys(cveCatalog));
   const diffs = [];
-  // F7: distinguish unreachable (fetch failed, network or 5xx) from
+  // Distinguish unreachable (fetch failed, network or 5xx) from
   // normalize-rejected (record fetched but normalization produced null).
   // Operators triaging a refresh-report want to know whether to chase a
   // network outage or a malformed upstream record.
   let unreachable = 0;
   let normalizeErrors = 0;
-  // Finding 18: ids that ARE in the catalog but skipped because of overlap
+  // Ids that ARE in the catalog but skipped because of overlap
   // are not "errors"; surface them so the summary doesn't read as silently
   // dropping work. Particularly useful when a curator dispatches the same
   // batch twice and wonders why nothing happened.

package/lib/validate-catalog-meta.js

@@ -242,7 +242,7 @@ function main() {
   console.log(
     `\n${passed}/${total} catalogs validated${warnSuffix}${failSuffix}.`,
   );
-  // F18: process.exitCode + return so buffered writes drain.
+  // process.exitCode + return so buffered writes drain.
   process.exitCode = failed === 0 ? 0 : 1;
 }
 

package/lib/validate-cve-catalog.js

@@ -418,7 +418,7 @@ function main() {
     (warned ? `, ${warned} with warnings` : '') +
     (failed ? `, ${failed} failed` : '') + '.';
   console.log(summary);
-  // F18: process.exitCode + return so buffered output drains.
+  // process.exitCode + return so buffered output drains.
   process.exitCode = failed === 0 ? 0 : 1;
 }
 

package/lib/verify.js

@@ -164,14 +164,14 @@ function signAll() {
   const manifestSig = crypto.sign(null, canonical, {
     key: privateKey, dsaEncoding: 'ieee-p1363',
   });
-  // A: `signed_at` is intentionally OMITTED. The previous shape
-  // emitted a `signed_at` timestamp alongside the Ed25519 signature, but
-  // `signed_at` was stripped from the canonical bytes before signing — so
-  // an attacker could replay a known-valid signature against the same
-  // canonical content while rewriting `signed_at` to any value, lending
-  // false freshness authority to a stale signature. Operators who need
-  // freshness signal should consult the git-log mtime of manifest.json
-  // (or the npm publish timestamp), which are external to the signed bytes.
+  // `signed_at` is intentionally OMITTED. A `signed_at` timestamp
+  // alongside the Ed25519 signature would be unsigned metadata (stripped
+  // from the canonical bytes before signing), so an attacker could replay
+  // a known-valid signature against the same canonical content while
+  // rewriting `signed_at` to any value — lending false freshness
+  // authority to a stale signature. Operators who need a freshness
+  // signal should consult the git-log mtime of manifest.json (or the
+  // npm publish timestamp), which are external to the signed bytes.
   manifest.manifest_signature = {
     algorithm: 'Ed25519',
     signature_base64: manifestSig.toString('base64'),
@@ -347,11 +347,12 @@ function verifyManifestSignature(manifest) {
   if (typeof sig.signature_base64 !== 'string') {
     return { status: 'invalid', reason: 'manifest_signature.signature_base64 missing or not a string' };
   }
-  // E: require the algorithm field to be present and exactly
-  // 'Ed25519'. The previous form accepted a missing algorithm field
-  // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) which let a
-  // future downgrade attacker drop the field to bait a weaker default.
-  // lib/sign.js always writes the field, so no legitimate consumer breaks.
+  // Require the algorithm field to be present and exactly 'Ed25519'.
+  // Accepting a missing algorithm field
+  // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) would let a
+  // downgrade attacker drop the field to bait a weaker default.
+  // lib/sign.js always writes the field, so no legitimate consumer
+  // breaks.
   if (sig.algorithm !== 'Ed25519') {
     return {
       status: 'invalid',
@@ -441,10 +442,10 @@ function loadManifestValidated() {
     throw new Error(`[verify] manifest_signature verification FAILED — ${sigResult.reason}. The manifest has been modified (or signed with a different key) since last sign-all. Refusing to verify any skill against this manifest.`);
   }
   if (sigResult.status === 'missing') {
-    // D: dedupe the legacy-tarball warning. Many CLI verbs
-    // call loadManifestValidated() more than once per invocation; the
-    // previous console.warn spammed stderr per call. Node's emitWarning()
-    // with a stable `code` collapses repeated emissions automatically.
+    // Dedupe the legacy-tarball warning. Many CLI verbs call
+    // loadManifestValidated() more than once per invocation, so a plain
+    // console.warn would spam stderr per call. Node's emitWarning() with
+    // a stable `code` collapses repeated emissions automatically.
     process.emitWarning(
       'manifest.json has no top-level manifest_signature field. This tarball predates v0.12.17 manifest signing; skills will still be verified but a coordinated rewrite of manifest.json could go undetected. Re-run `node lib/sign.js sign-all` to add the signature.',
       { code: 'EXCEPTD_MANIFEST_UNSIGNED' }
@@ -594,12 +595,12 @@ function validateAgainstSchema(value, schema, here, root) {
  * @param {string} [pinPath]             optional override (testability)
  */
 /**
- * KK P1-5: shared loader for keys/EXPECTED_FINGERPRINT. Reads the pin file,
- * strips a leading UTF-8 BOM (Notepad with files.encoding=utf8bom would
- * otherwise prepend U+FEFF and silently break every verify path on the host),
- * tolerates CRLF line endings, ignores comment lines (`#`) and blanks, and
- * returns the first non-comment / non-empty line. Returns null if the file
- * is unreadable / empty.
+ * Shared loader for keys/EXPECTED_FINGERPRINT. Reads the pin file, strips
+ * a leading UTF-8 BOM (Notepad with files.encoding=utf8bom would otherwise
+ * prepend U+FEFF and silently break every verify path on the host),
+ * tolerates CRLF line endings, ignores comment lines (`#`) and blanks,
+ * and returns the first non-comment / non-empty line. Returns null if
+ * the file is unreadable / empty.
  *
  * Shared across four sites so every loader normalises identically:
  *   - lib/verify.js              (manifest signature gate)
@@ -610,9 +611,18 @@ function validateAgainstSchema(value, schema, here, root) {
  * four sites under a BOM + CRLF fuzz corpus.
  */
 function loadExpectedFingerprintFirstLine(pinPath) {
-  let raw;
-  try { raw = fs.readFileSync(pinPath, 'utf8'); }
+  let buf;
+  try { buf = fs.readFileSync(pinPath); }
   catch { return null; }
+  if (buf.length >= 2) {
+    const b0 = buf[0];
+    const b1 = buf[1];
+    // UTF-16LE (FF FE) and UTF-16BE (FE FF) pin files would silently decode
+    // as UTF-8 mojibake — the first line never matches a live fingerprint
+    // and the operator sees no signal. Refuse them; re-save as UTF-8.
+    if ((b0 === 0xFF && b1 === 0xFE) || (b0 === 0xFE && b1 === 0xFF)) return null;
+  }
+  let raw = buf.toString('utf8');
   if (raw.length > 0 && raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
   const lines = raw
     .split(/\r?\n/)
@@ -627,7 +637,7 @@ function checkExpectedFingerprint(liveFp, pinPath) {
   if (!liveFp || typeof liveFp.sha256 !== 'string') {
     return { status: 'mismatch', expected: 'unknown', actual: '(invalid)', rotationOverride: false };
   }
-  // KK P1-5: route through the shared loader so a BOM-prefixed pin file
+  // Route through the shared loader so a BOM-prefixed pin file
   // (Notepad with files.encoding=utf8bom) is tolerated identically across
   // every verify site. Pre-fix the verbatim split-trim-find produced a
   // first-line of "SHA256:..." (with leading BOM) that would never equal