fix(arborist): retry bin-links on Windows EPERM

[manzoorwanijk]

In continuation of our exploration of using install-strategy=linked in the Gutenberg monorepo, which powers the WordPress Block Editor, this is a follow up of the fixes from #8996.

On Windows, npm install with install-strategy=linked fails with EPERM: operation not permitted during the bin-linking phase. This is hitting us on Windows CI for the Gutenberg monorepo (~200 workspace packages).

Summary

During rebuild, bin-links/fix-bin.js rewrites hashbang lines in bin files using write-file-atomic, which does a temp-file write followed by fs.rename(). On Windows, antivirus (Windows Defender) and the search indexer can transiently lock files that were just written, causing the rename to fail with EPERM.

The linked strategy amplifies this because it writes all packages into .store/ in parallel, increasing the window for antivirus lock conflicts compared to the hoisted layout.

Root cause

npm already patches the global fs with graceful-fs at startup (entry.js:8), which adds Windows rename retry logic. However, graceful-fs's retry only kicks in when the destination file does not exist — it checks fs.stat(to) after EPERM, and if the target already exists (stat succeeds), it gives up immediately. In write-file-atomic's case, the destination file always exists (it's being overwritten), so the retry never fires.

Changes

• Wrapped the binLinks() call in rebuild.js #createBinLinks with a new #binLinksWithRetry method that retries up to 5 times with 500ms–2.5s backoff on Windows when the error code is EPERM, EACCES, or EBUSY.
• Wrapped the binLinks() call in rebuild.js #createBinLinks with @gar/promise-retry. On Windows, EPERM/EACCES/EBUSY errors trigger a retry with exponential backoff (5 retries, 500ms min timeout).
• Added @gar/promise-retry to arborist's dependencies.
• The retry only activates on process.platform === 'win32' — no behavior change on macOS/Linux.

Testing

We tested this approach in our fork and it resolves the issue on Windows CI for the Gutenberg monorepo.

References

Fixes #9021

[wraithgar]

We may want to dig into the write-file-atomic PR first to see why this isn't already happening.

[manzoorwanijk]

We may want to dig into the write-file-atomic PR first to see why this isn't already happening.

I dug into this. As you already pointed out, npm already calls gracefulify(require('node:fs')) at startup (entry.js:8), which patches the global fs singleton - so write-file-atomic's require('fs') already gets the patched fs.rename.

The reason it doesn't help is that graceful-fs's rename retry has a condition that prevents it from retrying in this case. After getting EPERM, it does fs.stat(to) - if the destination file already exists (stat succeeds), it gives up immediately without retrying. In write-file-atomic's case, the destination file always exists (it's being overwritten), so the retry never fires.

The fix needs to be here at the arborist level. I'll update to use promiseRetry per your review.

[wraithgar]

We are making an exception for this PR on our policy accepting dependency updates. This dependency is already in the npm tree, and adding it is only a matter of adding it to the package.json and lockfile. The bundled assets are already present.

[manzoorwanijk]

Yes, I already saw it already used in the repo and used the exact same version for the same reason.

[wraithgar]

Oh yes so much cleaner w/ the retry library!