hooks: in-thread ESM hooks from Node.js 22.22.3, 24.11.1 and 25.1 (nodejs/node#59929)

[toabctl]

The in-thread ESM hooks (module.registerHooks) were only used from Node.js 24.12 / 25.2, for a crash we had attributed to nodejs/node#60380. Plan 03's spikes found the real causes:

• The crash (this[#customizations].loadSync is not a function): a --require preload calling registerHooks inside Node's own loader thread, which Node 22 – 24.11 runs preloads in too. register.cjs returns there, so our hooks never trigger it.
• What really breaks in-thread hooks next to another loader (Yarn Plug'n'Play, tsx, OpenTelemetry's hook.mjs): a loader-thread hook that returns no source for a CommonJS module is rejected with ERR_INVALID_RETURN_PROPERTY_VALUE before module: handle null source from async loader hooks in sync hooks nodejs/node#59929, i.e. before Node 22.22.3, 24.11.1 and 25.1 — the same gate import-in-the-middle and dd-trace use. Verified: forced sync with OTel, dd-trace and PnP gives the right lockfiles on 22.22.3, 22.23.2 and 24.11.1, and fails on 22.22.2 and 24.10.0.

So from those versions on, the in-thread hooks are used in every process. Current Node 22 no longer needs the loader thread, which removes its cost and the bundler-process gate, the gate that misses pnpm/bun isolated layouts (plan 02 S1).

Changes

• syncHooksSafe and the matrix's SYNC_HOOKS use those versions. A unit-tested version table covers 22.22.2, 24.10.0, 24.11.0 and 25.0, which stay on the loader thread.
• CI: the Node 22 matrix job also runs on 22.22.2 (nodejs-22=22.22.2-r1), the last 22 with the loader-thread hooks that older Node.js uses. Latest 22 now covers the in-thread path.
• When module.register fails, the error names what breaks Node's loader thread (another tool's loader, or a preload that calls registerHooks) instead of blaming bundle-lockfile.
• New unit tests:
  • the real entry module sees its own file through import.meta, despite the ?bundle-lockfile-real URL;
  • a cycle back into a wrapped entry reads the wrapper. This is documented in internals.md; none of the wrapped entries has such a cycle.
• The punycode test no longer assumes every Node 22 stays silent for a package's require(): 22.22.2 warns there, with and without bundle-lockfile.
• Docs: README, bundlers.md, internals.md and troubleshooting.md give the versions and the real causes.

Verified on the workstation (Wolfi containers)

• Full matrix on Node 22.23.2, now in-thread: 413/413.
• Node 22 CI subset on 22.22.2 (loader thread), 22.22.3 and 24.11.1: 241/241 each.
• Unit tests on 20.20.2, 22.22.2, 22.22.3, 22.23.2, 24.10.0, 24.11.1, 24.21.0 and 26.11.1: all pass.

🤖 Generated with Claude Code