@dogfood-lab/findings 1.2.3 → 1.3.0

package/cli.js

@@ -51,6 +51,9 @@ import {
   writePattern,
   writeRecommendation,
   writeDoctrine,
+  writePatterns,
+  writeRecommendations,
+  writeDoctrines,
   loadPatterns,
   loadRecommendations,
   loadDoctrines
@@ -429,7 +432,10 @@ Filters (for list):
     if (errors.length > 0) {
       console.error(`Errors: ${errors.length}`);
       for (const e of errors) {
-        console.error(`  ${e.findingId}: ${e.error}`);
+        // L2-004 (Wave A2 amend2): surface the structured `.code` so
+        // operators can grep for FINDING_ID_COLLISION etc., matching
+        // the sibling artifact CLIs (cli.js:676/756/832).
+        console.error(`  ${e.findingId || '<unknown>'}: ${e.code || 'WRITE_ERROR'} ${e.error}`);
       }
       process.exit(1);
     }
@@ -663,9 +669,16 @@ Filters (for list):
       }
 
       if (write && patterns.length > 0) {
-        for (const p of patterns) {
-          const path = writePattern(ROOT, p);
-          console.log(`Written: ${relative(ROOT, path)}`);
+        const { written, errors } = writePatterns(ROOT, patterns);
+        for (const p of written) {
+          console.log(`Written: ${relative(ROOT, p)}`);
+        }
+        if (errors.length > 0) {
+          console.error(`Errors: ${errors.length}`);
+          for (const e of errors) {
+            console.error(`  ${e.patternId || '<unknown>'}: ${e.code || 'WRITE_ERROR'} ${e.error}`);
+          }
+          process.exit(1);
         }
       } else if (!write && patterns.length > 0) {
         console.log(`(dry-run) ${patterns.length} pattern(s) would be written. Use --write to materialize.`);
@@ -714,7 +727,17 @@ Filters (for list):
     const sub = positional[0];
     if (sub === 'derive') {
       const write = flags.write;
-      const { recommendations, stats } = deriveRecommendations(ROOT);
+      const { recommendations, skipped, stats } = deriveRecommendations(ROOT);
+
+      // D2B-001 — surface structured skip signal to operators. The derive
+      // engine still emits clean recommendations from the patterns it could
+      // read; the skipped list documents the partial-completion honestly.
+      if (skipped && skipped.length > 0) {
+        console.error(`${skipped.length} pattern(s) skipped (torn/unreadable):`);
+        for (const s of skipped) {
+          console.error(`  ${relative(ROOT, s.path)} — ${s.error}`);
+        }
+      }
 
       console.log(`Patterns considered: ${stats.patternsConsidered}`);
       console.log(`Recommendations emitted: ${stats.recommendationsEmitted}\n`);
@@ -726,9 +749,16 @@ Filters (for list):
       }
 
       if (write && recommendations.length > 0) {
-        for (const r of recommendations) {
-          const path = writeRecommendation(ROOT, r);
-          console.log(`Written: ${relative(ROOT, path)}`);
+        const { written, errors } = writeRecommendations(ROOT, recommendations);
+        for (const p of written) {
+          console.log(`Written: ${relative(ROOT, p)}`);
+        }
+        if (errors.length > 0) {
+          console.error(`Errors: ${errors.length}`);
+          for (const e of errors) {
+            console.error(`  ${e.recommendationId || '<unknown>'}: ${e.code || 'WRITE_ERROR'} ${e.error}`);
+          }
+          process.exit(1);
         }
       } else if (!write && recommendations.length > 0) {
         console.log(`(dry-run) ${recommendations.length} recommendation(s) would be written. Use --write to materialize.`);
@@ -774,7 +804,15 @@ Filters (for list):
     const sub = positional[0];
     if (sub === 'derive') {
       const write = flags.write;
-      const { doctrines, stats } = deriveDoctrine(ROOT);
+      const { doctrines, skipped, stats } = deriveDoctrine(ROOT);
+
+      // D2B-001 — surface structured skip signal to operators.
+      if (skipped && skipped.length > 0) {
+        console.error(`${skipped.length} pattern(s) skipped (torn/unreadable):`);
+        for (const s of skipped) {
+          console.error(`  ${relative(ROOT, s.path)} — ${s.error}`);
+        }
+      }
 
       console.log(`Patterns considered: ${stats.patternsConsidered}`);
       console.log(`Doctrines emitted: ${stats.doctrinesEmitted}`);
@@ -787,9 +825,16 @@ Filters (for list):
       }
 
       if (write && doctrines.length > 0) {
-        for (const d of doctrines) {
-          const path = writeDoctrine(ROOT, d);
-          console.log(`Written: ${relative(ROOT, path)}`);
+        const { written, errors } = writeDoctrines(ROOT, doctrines);
+        for (const p of written) {
+          console.log(`Written: ${relative(ROOT, p)}`);
+        }
+        if (errors.length > 0) {
+          console.error(`Errors: ${errors.length}`);
+          for (const e of errors) {
+            console.error(`  ${e.doctrineId || '<unknown>'}: ${e.code || 'WRITE_ERROR'} ${e.error}`);
+          }
+          process.exit(1);
         }
       } else if (!write && doctrines.length > 0) {
         console.log(`(dry-run) ${doctrines.length} doctrine(s) would be written. Use --write to materialize.`);

package/derive/load-records.js

@@ -3,38 +3,60 @@
  * Discovers and loads verified dogfood records from the filesystem.
  */
 
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, existsSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 
 import { isUnsafeSegment } from '@dogfood-lab/ingest/lib/unsafe-segment.js';
+import { loadJsonFile } from '../lib/safe-yaml-load.js';
 
 /**
- * Load all records for a specific repo.
+ * Load all records for a specific repo (legacy array shape).
+ *
+ * Torn record JSON files are NO LONGER silently dropped — they surface via
+ * the sibling `loadRecordsForRepoWithSkips`. H2 / F-721047-010 — silent-
+ * loader closure. The advisor-surfaced sibling at line :110.
  *
  * @param {string} rootDir - dogfood-labs repo root.
  * @param {string} repoKey - Full org/repo key (e.g. "mcp-tool-shop-org/repo-crawler-mcp").
  * @returns {Array<{ record: object, rejected: boolean, path: string }>}
  */
 export function loadRecordsForRepo(rootDir, repoKey) {
+  return loadRecordsForRepoWithSkips(rootDir, repoKey).entries;
+}
+
+/**
+ * Audit-honesty variant of `loadRecordsForRepo`: returns both the loaded
+ * records and a list of torn / unreadable JSON files.
+ *
+ * @param {string} rootDir
+ * @param {string} repoKey
+ * @returns {{ entries: Array<{ record: object, rejected: boolean, path: string }>, skipped: Array<{ path: string, error: string }> }}
+ */
+export function loadRecordsForRepoWithSkips(rootDir, repoKey) {
   const [org, repo] = repoKey.split('/');
   // Path-traversal guard: F-916867-005. Mirrors persist.js + load-context.js
   // via the central helper at @dogfood-lab/ingest/lib/unsafe-segment.js.
   // A malformed repoKey (`..` or path-separator) would otherwise resolve
   // outside the records tree and silently load (or skip) unrelated files.
   if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) {
-    return [];
+    return { entries: [], skipped: [] };
   }
-  const results = [];
+  const entries = [];
+  const skipped = [];
 
   // Accepted records
   const acceptedDir = resolve(rootDir, 'records', org, repo);
-  results.push(...walkRecords(acceptedDir, false));
+  const acc = walkRecordsWithSkips(acceptedDir, false);
+  entries.push(...acc.entries);
+  skipped.push(...acc.skipped);
 
   // Rejected records
   const rejectedDir = resolve(rootDir, 'records', '_rejected', org, repo);
-  results.push(...walkRecords(rejectedDir, true));
+  const rej = walkRecordsWithSkips(rejectedDir, true);
+  entries.push(...rej.entries);
+  skipped.push(...rej.skipped);
 
-  return results;
+  return { entries, skipped };
 }
 
 /**
@@ -56,13 +78,27 @@ export function loadRecordById(rootDir, runId) {
 }
 
 /**
- * Load all records across all repos.
+ * Load all records across all repos (legacy array shape).
+ *
+ * Torn record JSON files are NO LONGER silently dropped — they surface via
+ * the sibling `loadAllRecordsWithSkips`. H2 / F-721047-010.
  *
  * @param {string} rootDir - dogfood-labs repo root.
  * @returns {Array<{ record: object, rejected: boolean, path: string }>}
  */
 export function loadAllRecords(rootDir) {
-  const results = [];
+  return loadAllRecordsWithSkips(rootDir).entries;
+}
+
+/**
+ * Audit-honesty variant of `loadAllRecords`.
+ *
+ * @param {string} rootDir
+ * @returns {{ entries: Array<{ record: object, rejected: boolean, path: string }>, skipped: Array<{ path: string, error: string }> }}
+ */
+export function loadAllRecordsWithSkips(rootDir) {
+  const entries = [];
+  const skipped = [];
 
   // Accepted records
   const recordsDir = resolve(rootDir, 'records');
@@ -72,7 +108,9 @@ export function loadAllRecords(rootDir) {
       const orgDir = join(recordsDir, org);
       for (const repo of listDirs(orgDir)) {
         const repoDir = join(orgDir, repo);
-        results.push(...walkRecords(repoDir, false));
+        const w = walkRecordsWithSkips(repoDir, false);
+        entries.push(...w.entries);
+        skipped.push(...w.skipped);
       }
     }
   }
@@ -84,58 +122,112 @@ export function loadAllRecords(rootDir) {
       const orgDir = join(rejectedDir, org);
       for (const repo of listDirs(orgDir)) {
         const repoDir = join(orgDir, repo);
-        results.push(...walkRecords(repoDir, true));
+        const w = walkRecordsWithSkips(repoDir, true);
+        entries.push(...w.entries);
+        skipped.push(...w.skipped);
       }
     }
   }
 
-  return results;
+  return { entries, skipped };
 }
 
-/** Walk a record directory tree and load all .json files. */
-function walkRecords(dir, rejected) {
-  if (!existsSync(dir)) return [];
-  const results = [];
+/**
+ * Walk a record directory tree, load all `.json` files via the shared
+ * `loadJsonFile` helper, and return `{ entries, skipped }`. Torn JSON
+ * files are NO LONGER silently dropped — they appear in `skipped` with
+ * a structured `{ path, error }`.
+ *
+ * H2 / F-721047-010 — silent-loader closure (advisor-surfaced sibling at
+ * load-records.js:110).
+ */
+function walkRecordsWithSkips(dir, rejected) {
+  const entries = [];
+  const skipped = [];
+  if (!existsSync(dir)) return { entries, skipped };
 
   function walk(d) {
-    for (const entry of readdirSync(d)) {
+    let children;
+    try {
+      children = readdirSync(d);
+    } catch (err) {
+      skipped.push({ path: d, error: `readdir error: ${err.message}` });
+      return;
+    }
+    for (const entry of children) {
       const full = join(d, entry);
+      let stat;
       try {
-        if (statSync(full).isDirectory()) {
-          walk(full);
-        } else if (extname(entry) === '.json') {
-          const data = JSON.parse(readFileSync(full, 'utf-8'));
-          results.push({ record: data, rejected, path: full });
-        }
-      } catch {
-        // Skip unreadable files
+        stat = statSync(full);
+      } catch (err) {
+        skipped.push({ path: full, error: `stat error: ${err.message}` });
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (extname(entry) !== '.json') continue;
+      const { data, error } = loadJsonFile(full);
+      if (error !== null) {
+        skipped.push({ path: full, error });
+      } else {
+        entries.push({ record: data, rejected, path: full });
       }
     }
   }
 
   walk(dir);
-  return results;
+  return { entries, skipped };
 }
 
-/** Find a specific record file by run_id pattern. */
+/**
+ * Find a specific record file by run_id pattern.
+ *
+ * H2 / F-721047-010 — silent-loader closure (advisor-surfaced sibling at
+ * load-records.js:137). Replaces the bare `try { ... } catch {}` with the
+ * structured `loadJsonFile` helper. A torn JSON file that happens to
+ * include the run_id in its name no longer silently masks the actual
+ * record under a different (perhaps later-renamed) sibling.
+ */
 function findRecordFile(rootDir, runId, rejected) {
   if (!existsSync(rootDir)) return null;
 
   function search(dir) {
-    for (const entry of readdirSync(dir)) {
+    let children;
+    try {
+      children = readdirSync(dir);
+    } catch {
+      // Permission/transient error on the directory — fall through; the
+      // caller's outer search will try sibling roots.
+      return null;
+    }
+    for (const entry of children) {
       const full = join(dir, entry);
+      let stat;
       try {
-        if (statSync(full).isDirectory()) {
-          const found = search(full);
-          if (found) return found;
-        } else if (extname(entry) === '.json' && entry.includes(runId)) {
-          const data = JSON.parse(readFileSync(full, 'utf-8'));
-          if (data.run_id === runId) {
-            return { record: data, rejected, path: full };
-          }
-        }
+        stat = statSync(full);
       } catch {
-        // Skip
+        continue;
+      }
+      if (stat.isDirectory()) {
+        const found = search(full);
+        if (found) return found;
+        continue;
+      }
+      if (extname(entry) !== '.json') continue;
+      if (!entry.includes(runId)) continue;
+      const { data, error } = loadJsonFile(full);
+      if (error !== null) {
+        // A torn JSON file that happens to be named after the run_id —
+        // surface this loudly via console.error rather than silently
+        // hiding it. The caller still gets null and may find a sibling.
+        // eslint-disable-next-line no-console
+        console.error(`findRecordFile: torn record JSON at ${full}: ${error}`);
+        continue;
+      }
+      if (data && data.run_id === runId) {
+        return { record: data, rejected, path: full };
       }
     }
     return null;

package/derive/write-findings.js

@@ -1,5 +1,33 @@
 /**
  * Write derived candidate findings to disk as YAML files.
+ *
+ * D2B-008 — finding_id collision guard. The id generator
+ * (`generateFindingId` → `dfind-<repoSlug>-<lessonSlug>`) does NOT yet
+ * discriminate by `rule_id`, so two rules that emit the same lesson slug
+ * for the same repo land on the same `finding_id`. AT HEAD a naive batch
+ * write silently clobbered the first finding via the atomic temp+rename
+ * (operator-invisible data loss). The batch helper `writeFindings` records
+ * the first occurrence per id and REFUSES every subsequent write with a
+ * structured `FINDING_ID_COLLISION` error routed through the existing
+ * `errors[]` channel — the CLI's `if (errors.length > 0) exit(1)` branch
+ * then propagates non-zero. The first write still lands so a
+ * single-finding batch keeps working.
+ *
+ * L3-001 (Wave A2 amend2 — family seal). The SINGLETON `writeFinding`
+ * had the same silent-clobber class on a different verb: two programmatic
+ * calls to `writeFinding(rootDir, finding)` with the same `finding_id`
+ * silently overwrote the first via atomicWriteFileSync. The fix-closed
+ * guard now lives at the singleton AND batch path via a shared
+ * process-level `seenWrites` Map keyed by `${rootDir}:${finding_id}`.
+ * Second-with-same-id throws `FindingIdCollisionError` (with `.code =
+ * FINDING_ID_COLLISION`); batch path collects into errors[]. The
+ * `resetSeenWrites(rootDir?)` helper exists for the narrow case of a
+ * caller that legitimately re-writes after an intentional disk wipe
+ * (test isolation, etc.).
+ *
+ * The structural fix (putting `rule_id` into the id slug so collisions
+ * stop happening in the first place) is needs-design and deferred to a
+ * follow-on wave; this guard is the fail-closed stopgap.
  */
 
 import { mkdirSync, existsSync } from 'node:fs';
@@ -7,6 +35,75 @@ import { resolve, dirname } from 'node:path';
 import yaml from 'js-yaml';
 
 import { atomicWriteFileSync } from '../lib/atomic-write.js';
+import { validateFinding } from '../validate.js';
+
+/**
+ * Structured error thrown when `writeFinding` receives a finding that fails
+ * `dogfood-finding.schema.json`. Mirrors `RecordValidationError` in
+ * @dogfood-lab/ingest/validate-record.js — typed class with `.code` so
+ * callers can pattern-match without grepping `.message`.
+ *
+ * D2B-002 — library-path schema gate. The CLI already validated via
+ * `validateFinding` in `cli.js derive`, but programmatic callers of
+ * `writeFinding` had no gate. Now neither can persist a malformed finding.
+ */
+export class FindingValidationError extends Error {
+  constructor(errors, findingId) {
+    const summary = errors
+      .map(e => `${e.path || '/'} ${e.message}`)
+      .join('; ');
+    super(`finding failed schema validation${findingId ? ` (${findingId})` : ''}: ${summary}`);
+    this.name = 'FindingValidationError';
+    this.code = 'FINDING_SCHEMA_INVALID';
+    this.findingId = findingId;
+    this.errors = errors;
+  }
+}
+
+/**
+ * Structured error thrown by the singleton `writeFinding` when called
+ * twice in the same process with the same `finding_id`. Mirrors the
+ * batch helper's `FINDING_ID_COLLISION` code (same vocabulary across
+ * singleton + batch paths). L3-001 family seal of D2B-008.
+ */
+export class FindingIdCollisionError extends Error {
+  constructor(findingId) {
+    super(`finding_id collision: '${findingId}' already written in this process; refused to silently clobber (D2B-008 / L3-001 family-seal). Call resetSeenWrites() if a legitimate re-write is intended.`);
+    this.name = 'FindingIdCollisionError';
+    this.code = 'FINDING_ID_COLLISION';
+    this.findingId = findingId;
+  }
+}
+
+/**
+ * Process-level memory of ids that have already been written via
+ * `writeFinding` (singleton) OR the singleton-call inside `writeFindings`
+ * (batch). Keyed by `${rootDir}:${finding_id}` so callers writing to
+ * distinct roots don't collide and so the test harness's per-test
+ * `mkdtempSync` roots are naturally isolated.
+ *
+ * Exposed as a Map (rather than Set) so test isolation can clear only
+ * a single root via `resetSeenWrites(rootDir)`.
+ */
+const seenWrites = new Map();
+
+/**
+ * Reset the singleton's in-process collision memory. Pass a `rootDir` to
+ * clear only entries scoped to that root (cheap, narrow); pass nothing
+ * to clear everything (only useful for full-process resets in tests).
+ *
+ * @param {string} [rootDir]
+ */
+export function resetSeenWrites(rootDir) {
+  if (rootDir === undefined) {
+    seenWrites.clear();
+    return;
+  }
+  const prefix = `${rootDir}:`;
+  for (const key of seenWrites.keys()) {
+    if (key.startsWith(prefix)) seenWrites.delete(key);
+  }
+}
 
 /**
  * Write a candidate finding to its canonical location.
@@ -18,9 +115,29 @@ import { atomicWriteFileSync } from '../lib/atomic-write.js';
  * @returns {string} - Path written.
  */
 export function writeFinding(rootDir, finding) {
+  // D2B-002 — fail-closed schema gate BEFORE touching the filesystem. The
+  // CLI already validates via `validateFinding` in `derive`; this protects
+  // every other call site (synthesis, review, programmatic, tests) so no
+  // path can persist a malformed finding.
+  const validation = validateFinding(finding);
+  if (!validation.valid) {
+    throw new FindingValidationError(validation.errors, finding?.finding_id);
+  }
+
   const [org, repo] = (finding.repo || '').split('/');
   if (!org || !repo) throw new Error(`Invalid repo in finding: ${finding.repo}`);
 
+  // L3-001 (Wave A2 amend2): same-process same-id refusal. Programmatic
+  // callers that loop over assembleFinding output now fail-closed at the
+  // singleton path, not silently at the atomicWriteFileSync.
+  const id = finding.finding_id;
+  if (id !== undefined && id !== null) {
+    const key = `${rootDir}:${id}`;
+    if (seenWrites.has(key)) {
+      throw new FindingIdCollisionError(id);
+    }
+  }
+
   const dir = resolve(rootDir, 'findings', org, repo);
   mkdirSync(dir, { recursive: true });
 
@@ -36,26 +153,61 @@ export function writeFinding(rootDir, finding) {
   });
 
   atomicWriteFileSync(filePath, yamlStr);
+
+  if (id !== undefined && id !== null) {
+    seenWrites.set(`${rootDir}:${id}`, true);
+  }
   return filePath;
 }
 
 /**
- * Write multiple findings and return write stats.
+ * Write multiple findings to disk, refusing any intra-batch collision on
+ * `finding_id`. See file header for the D2B-008 rationale.
+ *
+ * Returns `{ written, errors }`:
+ *   - `written`: paths of findings successfully written (first occurrence per id).
+ *   - `errors`: structured records for refused colliding writes (and any
+ *      programmatic write failures). Collision records carry
+ *      `{ findingId, code: 'FINDING_ID_COLLISION', error }`.
+ *
+ * The CLI at packages/findings/cli.js:425+ already exits non-zero when
+ * `errors.length > 0`, so collisions now break CI rather than silently
+ * destroying findings.
  *
  * @param {string} rootDir
  * @param {Array} findings
- * @returns {{ written: string[], errors: Array<{ findingId: string, error: string }> }}
+ * @returns {{ written: string[], errors: Array<{ findingId: string, code?: string, error: string }> }}
  */
 export function writeFindings(rootDir, findings) {
   const written = [];
   const errors = [];
+  const seenIds = new Map(); // finding_id → index of first occurrence (for debug)
+
+  for (let i = 0; i < findings.length; i++) {
+    const f = findings[i];
+    const id = f.finding_id;
+
+    // Intra-batch collision guard — fail-closed.
+    if (id !== undefined && id !== null && seenIds.has(id)) {
+      const firstIdx = seenIds.get(id);
+      errors.push({
+        findingId: id,
+        code: 'FINDING_ID_COLLISION',
+        error: `intra-batch finding_id collision: '${id}' already claimed by index ${firstIdx}; refused write at index ${i} to avoid silent clobber (D2B-008)`
+      });
+      continue;
+    }
 
-  for (const f of findings) {
     try {
       const path = writeFinding(rootDir, f);
       written.push(path);
+      if (id !== undefined && id !== null) seenIds.set(id, i);
     } catch (err) {
-      errors.push({ findingId: f.finding_id, error: err.message });
+      // D2B-002 — preserve structured codes (FINDING_SCHEMA_INVALID etc.) so
+      // batch callers see the same vocabulary as singleton callers.
+      const errRec = { findingId: id, error: err.message };
+      if (err && err.code) errRec.code = err.code;
+      errors.push(errRec);
     }
   }
 

package/lib/rename-with-retry.js

@@ -16,6 +16,13 @@
  * appender) are themselves synchronous, and Promise-based retries would
  * leak the async boundary into otherwise-deterministic flush paths.
  *
+ * D1B-002-findings — the backoff used to be a CPU-busy `while (Date.now() <
+ * until)` spin. The repo already ships `sleepSync` via `Atomics.wait` on a
+ * tiny SharedArrayBuffer (see `file-lock.js:286`). Atomics.wait yields the
+ * thread instead of pegging a core, with the same sync API. The retry
+ * envelope and visible behaviour are preserved; only the cost of the wait
+ * changes.
+ *
  * @param {string} tmp - Source path (the just-written temp file).
  * @param {string} dest - Destination path (the canonical artifact).
  * @param {object} [opts]
@@ -25,6 +32,24 @@
  */
 import { renameSync } from 'node:fs';
 
+/**
+ * Sleep synchronously for `ms` milliseconds via `Atomics.wait` on a tiny
+ * SharedArrayBuffer. Yields the thread (does not spin). Mirrors the
+ * `sleepSync` in `file-lock.js:286` — the contract is identical; the
+ * helper is duplicated here because rename-with-retry must not import the
+ * larger file-lock module (cyclic-import risk: atomic-write imports
+ * rename-with-retry, and file-lock imports atomic-write transitively
+ * through the lock-event write path).
+ *
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  if (ms <= 0) return;
+  const sab = new SharedArrayBuffer(4);
+  const view = new Int32Array(sab);
+  Atomics.wait(view, 0, 0, ms);
+}
+
 export function renameWithRetry(tmp, dest, { retries = 10, baseMs = 15, maxMs = 200 } = {}) {
   for (let i = 0; i <= retries; i++) {
     try {
@@ -33,11 +58,10 @@ export function renameWithRetry(tmp, dest, { retries = 10, baseMs = 15, maxMs =
     } catch (err) {
       if ((err.code !== 'EPERM' && err.code !== 'EBUSY') || i === retries) throw err;
       const delay = Math.min(baseMs * (1 << i), maxMs);
-      // Synchronous sleep — the public API is sync (matches renameSync), so
-      // setTimeout would change the contract. Spin-wait is acceptable here
-      // because the delays are bounded (≤200ms) and the failure mode is rare.
-      const until = Date.now() + delay;
-      while (Date.now() < until) { /* spin */ }
+      // Synchronous sleep via Atomics.wait — yields the thread instead of
+      // spinning. The public API stays sync (matches renameSync). The
+      // delays remain bounded (≤200ms) and the failure mode is rare.
+      sleepSync(delay);
     }
   }
 }