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

write-file-atomic uses bare require('fs') and has no retry logic for fs.rename. By contrast, graceful-fs already patches fs.rename on Windows with exponential backoff for EACCES/EPERM/EBUSY (up to 60s). Since write-file-atomic doesn't use graceful-fs, the rename fails immediately on the first lock conflict.

The longer-term fix is for write-file-atomic to use graceful-fs (tracked in npm/write-file-atomic#227, with a PR ready - npm/write-file-atomic#228), but in the meantime this PR adds retry logic at the arborist level.

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.
• 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]

Suggested change

	// On Windows, antivirus/indexer can transiently lock files, causing
	// EPERM/EACCES/EBUSY on the rename inside write-file-atomic (used by
	// bin-links/fix-bin.js). Retry with backoff for up to ~7.5 seconds.
	// On Windows, antivirus/indexer can transiently lock files, causing EPERM/EACCES/EBUSY on the rename inside write-file-atomic (used by bin-links/fix-bin.js).
	// Retry with backoff for up to ~7.5 seconds.

As part of our efforts to increase accessibility we try to keep comments all on one line, breaking only for sentences.

[wraithgar]

Elsewhere we have delegated retries to a library. There is a LOT that goes into retrying and it's not something we want to hand roll.

cli/workspaces/libnpmexec/lib/with-lock.js

Line 70 in 10d5302

return promiseRetry(async (retry) => {

[wraithgar]

This is a good example of why a retry library is the right option. We can wrap this whole thing in the retry library and then make the decision on whether or not to retry it at all (by checking codes) in our callback.

[wraithgar]

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