From ed7ec03a6de722f38e52109e37bef301aeff17e9 Mon Sep 17 00:00:00 2001
From: Philipp Dunkel <pip@pipobscure.com>
Date: Sat, 1 Aug 2026 20:38:52 +0200
Subject: [PATCH] vfs: add --vfs-load to run modules from a mount

Builds on --vfs-mount to make a mount a real execution environment,
resolving require()/import inside it.

Adds --vfs-load, which runs the entry point (process.argv[1]) and all
subsequent require()/import resolution against the last --vfs-mount
rather than the real file system. process.argv[1] becomes that mount's
root, as if `node <mountPoint>` had been run, so the mount's own
package.json "main"/index.js selects the entry point and positional
arguments are the program's own. A self-mounting shebang
(`#!/usr/bin/env -S node --vfs-load --vfs-mount`) therefore makes an
archive directly executable. --vfs-load requires at least one
--vfs-mount, and workers inherit it alongside the mounts.

Making resolution VFS-aware requires four of the CJS/ESM loader's
resolution primitives - package.json reading, nearest-parent/scope
lookup, legacy main resolution, and extensionless-file format sniffing -
to stop bypassing the public fs module and call it instead, since that
bypass is what let them ignore a mount. Each defers to the real native
binding unchanged for anything outside an active mount. A lean mount
registry (internal/vfs/registry) is extracted from internal/vfs/setup so
the resolution fast path can answer "is this path under a mount?"
without loading the heavier setup/provider machinery.

Provider selection - and, for a --vfs-load entry, its resolution - is
deferred until after -r and --import preload modules have run, so a
provider registered from either backs the mount.

Native addons are supported: a directory-backed mount dlopens the real
underlying file directly (RealFSProvider.toRealPath); an archive-backed
mount extracts the addon to a content-hashed temp file first, scoped
per pid so processes don't clobber each other's extractions.

Signed-off-by: Philipp Dunkel <pip@pipobscure.com>
---
 doc/api/cli.md                                |  69 ++++-
 doc/api/vfs.md                                |  24 +-
 doc/node.1                                    |  45 ++-
 lib/internal/modules/cjs/loader.js            |   8 +-
 lib/internal/modules/esm/get_format.js        |   5 +-
 lib/internal/modules/esm/resolve.js           |   8 +-
 lib/internal/modules/package_json_reader.js   |  20 +-
 lib/internal/modules/run_main.js              |  29 +-
 lib/internal/modules/vfs_addons.js            | 106 +++++++
 lib/internal/modules/vfs_resolution.js        | 291 ++++++++++++++++++
 lib/internal/process/pre_execution.js         | 186 +++++++----
 lib/internal/vfs/file_system.js               |  12 +
 lib/internal/vfs/providers/real.js            |  12 +
 lib/internal/vfs/registry.js                  |  67 ++++
 lib/internal/vfs/setup.js                     |  42 +--
 lib/internal/worker.js                        |   7 +-
 src/node.cc                                   |   7 +-
 src/node_options.cc                           |  18 +-
 src/node_options.h                            |   1 +
 test/parallel/test-bootstrap-modules.js       |   6 +
 test/parallel/test-vfs-cli-flag-addons.js     |  80 +++++
 .../test-vfs-cli-flag-custom-provider.js      | 201 ++++++++++++
 test/parallel/test-vfs-cli-flag.js            | 212 +++++++++++++
 test/parallel/test-vfs-mount-require.js       |  73 +++++
 24 files changed, 1392 insertions(+), 137 deletions(-)
 create mode 100644 lib/internal/modules/vfs_addons.js
 create mode 100644 lib/internal/modules/vfs_resolution.js
 create mode 100644 lib/internal/vfs/registry.js
 create mode 100644 test/parallel/test-vfs-cli-flag-addons.js
 create mode 100644 test/parallel/test-vfs-cli-flag-custom-provider.js
 create mode 100644 test/parallel/test-vfs-cli-flag.js
 create mode 100644 test/parallel/test-vfs-mount-require.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index fa7db08d71dd..074f6ea6df90 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1497,8 +1497,8 @@ added: v26.4.0
 > Stability: 1 - Experimental
 
 Enable the experimental [`node:vfs`][] module. This flag also gates the
-[`--vfs-mount`][] startup flag, which is only allowed when `--experimental-vfs`
-is set.
+[`--vfs-mount`][] and [`--vfs-load`][] startup flags, which are only allowed
+when `--experimental-vfs` is set.
 
 ### `--experimental-vm-modules`
 
@@ -3564,6 +3564,38 @@ added: v0.1.3
 
 Print node's version.
 
+### `--vfs-load`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Requires [`--experimental-vfs`][] and at least one [`--vfs-mount`][].
+
+Runs the entry point (`process.argv[1]`) and all subsequent
+`require()`/`import` resolution against the **last** [`--vfs-mount`][] rather
+than the real file system. `process.argv[1]` becomes that mount's root, as if
+`node <mountPoint>` had been run: the mount's own `package.json` `"main"` (or
+`index.js`) selects the entry point, and any positional command-line argument
+is the program's own (available from `process.argv[2]` onward), never an
+entry-point override.
+
+Module resolution under the loaded mount is fully sandboxed: `package.json`
+lookups, `node_modules`-style resolution, and legacy `main` resolution never
+fall back to the real file system once they would step outside the mount.
+
+Combined with a self-mounting shebang this makes an archive directly
+executable. The kernel appends the script's own path as the trailing argument,
+which the final `--vfs-mount` consumes as its source, so the archive mounts
+itself and runs (the ZIP is located by its trailing record, so the shebang
+prefix is ignored):
+
+```console
+$ (printf '#!/usr/bin/env -S node --vfs-load --vfs-mount\n'; cat app.zip) > app
+$ chmod +x app
+$ ./app arg1 arg2   # runs the archive's index.js with ['arg1', 'arg2']
+```
+
 ### `--vfs-mount=source[=target]`
 
 <!-- YAML
@@ -3577,9 +3609,11 @@ added: REPLACEME
 Requires [`--experimental-vfs`][]. May be repeated to mount several sources.
 
 Mounts `source` as a virtual file system ([`node:vfs`][]) at `target` (or at
-`source`'s own path when no `target` is given). The running program's own
-[`node:fs`][] calls to paths under `target` then resolve against the mount,
-while every other path uses the real file system unchanged.
+`source`'s own path when no `target` is given). Paths under `target` then
+resolve against the mount - both `require()`/`import` and the running
+program's own [`node:fs`][] calls - while every other path uses the real file
+system unchanged. Mounting alone does **not** change the entry point; pass
+[`--vfs-load`][] to also run from a mount.
 
 * If `source` is a directory, it's mounted with a [`RealFSProvider`][] rooted
   there. The files are already real, so mounting doesn't change what bytes are
@@ -3588,15 +3622,26 @@ while every other path uses the real file system unchanged.
 * If `source` is a file, a provider is chosen for it by **content**, not by
   file extension, so an archive can carry any name. Providers registered with
   [`vfs.registerProvider()`][] (typically from a module preloaded with
-  [`--require`][]) are tried first, in reverse registration order and for
-  directories as well as files; if none claims the source, the built-in
-  providers handle it - a directory with [`RealFSProvider`][], and a file whose
-  bytes are a ZIP archive with the read-only [`ZipProvider`][]
+  [`--require`][] or [`--import`][]) are tried first, in reverse registration
+  order and for directories as well as files; if none claims the source, the
+  built-in providers handle it - a directory with [`RealFSProvider`][], and a
+  file whose bytes are a ZIP archive with the read-only [`ZipProvider`][]
   ([`zlib.ZipFile`][]; a `.zip` name is accepted without reading, as a fast
   path). A source no provider claims fails with `ERR_VFS_INVALID_TARGET`.
 
-This affects only paths under a mount, the same as any other [`node:vfs`][]
-mount.
+Provider selection is deferred until after [`--require`][] and [`--import`][]
+preload modules have run, so a preloaded module can register a custom provider
+that backs the mount.
+
+This only affects the paths under a mount. The running program's own
+[`node:fs`][] calls to other paths work normally against the real file system,
+the same as any other [`node:vfs`][] mount.
+
+Native addons (`.node` files) are supported: from a directory-backed mount
+they're loaded directly from their real underlying path; from an
+archive-backed mount, the addon's bytes are extracted to a content-hashed file
+under the OS temporary directory before being loaded, and that file is
+best-effort removed when the process exits.
 
 A [`Worker`][] created from a process started with `--vfs-mount` inherits the
 same mounts unless its own `execArgv` explicitly supplies its own
@@ -4021,6 +4066,7 @@ one is included in the list below.
 * `--use-openssl-ca`
 * `--use-system-ca`
 * `--v8-pool-size`
+* `--vfs-load`
 * `--vfs-mount`
 * `--watch-kill-signal`
 * `--watch-path`
@@ -4537,6 +4583,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--require`]: #-r---require-module
 [`--use-env-proxy`]: #--use-env-proxy
 [`--use-system-ca`]: #--use-system-ca
+[`--vfs-load`]: #--vfs-load
 [`--vfs-mount`]: #--vfs-mountsourcetarget
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md#class-buffer
diff --git a/doc/api/vfs.md b/doc/api/vfs.md
index 9731b356d012..a89a7ab96a61 100644
--- a/doc/api/vfs.md
+++ b/doc/api/vfs.md
@@ -34,9 +34,11 @@ It does not isolate untrusted code from the host file system or from other
 Node.js capabilities. Code that can access a [`VirtualFileSystem`][] instance,
 mount it, select its provider, or pass paths to it is trusted application code.
 
-Mounting a VFS only redirects supported [`node:fs`][] calls whose resolved paths
-are under the mount point. It does not prevent code from using other paths or
-other Node.js APIs to access resources available to the process.
+Mounting a VFS only redirects supported [`node:fs`][] calls (and, since the
+CJS/ESM module loader ultimately resolves and reads files the same way,
+`require()`/`import` resolution) whose resolved paths are under the mount
+point. It does not prevent code from using other paths or other Node.js APIs
+to access resources available to the process.
 [`RealFSProvider`][] maps VFS paths under its configured root and rejects paths
 that resolve outside that root, but that check is not a security boundary.
 [`ZipProvider`][] has no real file-system paths of its own to escape; its
@@ -110,11 +112,12 @@ Registers a provider that the [`--vfs-mount`][] startup flag can select for a
 mount source it recognizes. This is the extension point for supporting archive
 formats beyond the built-in ZIP, or for wrapping the built-in directory and
 ZIP providers: a module that implements, say, a 7-Zip provider registers it
-here — typically from a module preloaded with [`--require`][], so it is in
-place before `--vfs-mount` selects a provider:
+here — typically from a module preloaded with [`--require`][] or [`--import`][],
+so it is in place before `--vfs-mount` selects a provider (selection is
+deferred until after both kinds of preload have run):
 
 ```console
-$ node --experimental-vfs -r @me/my-7z-provider --vfs-mount app.7z app.js
+$ node --experimental-vfs -r @me/my-7z-provider --vfs-load --vfs-mount app.7z
 ```
 
 ```cjs
@@ -146,8 +149,8 @@ Selection rules for a `--vfs-mount` source:
   most recently registered wins), so a custom provider always takes precedence
   over the built-ins — even for a source they would otherwise handle. This lets
   a provider back, wrap, or vet any mount, including a directory (for example,
-  a provider that wraps [`RealFSProvider`][], or one that verifies a signature
-  before allowing use).
+  a provider that wraps [`RealFSProvider`][] to record every read, or one that
+  verifies a signature before allowing use).
 * If no registered provider claims the source, the built-ins handle it: a
   directory with [`RealFSProvider`][], and a file whose bytes are a ZIP archive
   with the built-in ZIP provider. A `.zip` name is accepted without reading the
@@ -240,6 +243,10 @@ signatures as their [`node:fs`][] counterparts:
   `fstatSync`
 * Streams: `createReadStream`, `createWriteStream`
 * Watchers: `watch`, `watchFile`, `unwatchFile`
+* `toProviderPath(path)`: converts an absolute mounted path to the
+  provider-relative POSIX path passed to [`VirtualProvider`][] methods -
+  useful for code that needs to reach `vfs.provider` directly, bypassing
+  this class's own `fs`-shaped methods.
 
 #### Callback API
 
@@ -439,6 +446,7 @@ fields use synthetic but stable values:
 * `blocks` is `Math.ceil(size / 512)`.
 * Times default to the moment the entry was created/last modified.
 
+[`--import`]: cli.md#--importmodule
 [`--require`]: cli.md#-r---require-module
 [`--vfs-mount`]: cli.md#--vfs-mountsourcetarget
 [`MemoryProvider`]: #class-memoryprovider
diff --git a/doc/node.1 b/doc/node.1
index 41a03151ee1f..e3c3b438a343 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -813,8 +813,8 @@ inheriting tags.
 .
 .It Fl -experimental-vfs
 Enable the experimental \fBnode:vfs\fR module. This flag also gates the
-\fB--vfs-mount\fR startup flag, which is only allowed when
-\fB--experimental-vfs\fR is set.
+\fB--vfs-mount\fR and \fB--vfs-load\fR startup flags, which are only allowed
+when \fB--experimental-vfs\fR is set.
 .
 .It Fl -experimental-vm-modules
 Enable experimental ES Module support in the \fBnode:vm\fR module.
@@ -1777,6 +1777,26 @@ amount of CPUs, but it may diverge in environments such as VMs or containers.
 .It Fl v , Fl -version
 Print node's version.
 .
+.It Fl -vfs-load
+Requires \fB--experimental-vfs\fR and at least one \fB--vfs-mount\fR.
+Runs the entry point (\fBprocess.argv[1]\fR) and all subsequent
+\fBrequire()\fR/\fBimport\fR resolution against the last \fB--vfs-mount\fR rather
+than the real file system. \fBprocess.argv[1]\fR becomes that mount's root, as
+if \fBnode <mountPoint>\fR had been run: the mount's own \fBpackage.json\fR
+\fB"main"\fR (or \fBindex.js\fR) selects the entry point, and any positional
+command-line argument is the program's own (available from \fBprocess.argv[2]\fR
+onward), never an entry-point override.
+Module resolution under the loaded mount is fully sandboxed: \fBpackage.json\fR
+lookups, \fBnode_modules\fR-style resolution, and legacy \fBmain\fR resolution
+never fall back to the real file system once they would step outside the mount.
+Combined with a self-mounting shebang this makes an archive directly
+executable:
+.Bd -literal
+$ (printf '#!/usr/bin/env -S node --vfs-load --vfs-mount\\n'; cat app.zip) > app
+$ chmod +x app
+$ ./app arg1 arg2   # runs the archive's index.js with ['arg1', 'arg2']
+.Ed
+.
 .It Fl -vfs-mount Ns = Ns Ar source Ns Oo = Ns Ar target Oc
 .Bl -bullet
 .It
@@ -1787,9 +1807,11 @@ resolved path.
 .El
 Requires \fB--experimental-vfs\fR. May be repeated to mount several sources.
 Mounts \fBsource\fR as a virtual file system (\fBnode:vfs\fR) at \fBtarget\fR (or
-at \fBsource\fR's own path when no \fBtarget\fR is given). The running program's
-own \fBnode:fs\fR calls to paths under \fBtarget\fR then resolve against the
-mount, while every other path uses the real file system unchanged.
+at \fBsource\fR's own path when no \fBtarget\fR is given). Paths under
+\fBtarget\fR then resolve against the mount - both \fBrequire()\fR/\fBimport\fR
+and the running program's own \fBnode:fs\fR calls - while every other path uses
+the real file system unchanged. Mounting alone does not change the entry
+point; pass \fB--vfs-load\fR to also run from a mount.
 .Bl -bullet
 .It
 If \fBsource\fR is a directory, it's mounted with a \fBRealFSProvider\fR rooted
@@ -1797,10 +1819,15 @@ there, adding path containment.
 .It
 If \fBsource\fR is a file, a provider is chosen for it by content, not by file
 extension. Providers registered with \fBvfs.registerProvider()\fR (from a
-\fB--require\fR preload) are tried first, for directories as well as files;
-otherwise the built-in ZIP provider handles a file whose bytes are a ZIP
-archive. A source no provider claims fails with \fBERR_VFS_INVALID_TARGET\fR.
+\fB--require\fR or \fB--import\fR preload) are tried first, for directories as
+well as files; otherwise the built-in ZIP provider handles a file whose bytes
+are a ZIP archive. A source no provider claims fails with
+\fBERR_VFS_INVALID_TARGET\fR.
 .El
+Native addons (\fB.node\fR files) are supported: from a directory-backed mount
+they're loaded directly from their real underlying path; from an
+archive-backed mount, the addon's bytes are extracted to a content-hashed
+file under the OS temporary directory before being loaded.
 A \fBWorker\fR created from a process started with \fB--vfs-mount\fR inherits the
 same mounts unless its own \fBexecArgv\fR explicitly supplies its own
 \fB--vfs-mount\fR.
@@ -2265,6 +2292,8 @@ one is included in the list below.
 .It
 \fB--v8-pool-size\fR
 .It
+\fB--vfs-load\fR
+.It
 \fB--vfs-mount\fR
 .It
 \fB--watch-kill-signal\fR
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index bb466d0b68d5..2e93e3ff5357 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -157,7 +157,7 @@ const {
 const assert = require('internal/assert');
 const fs = require('fs');
 const path = require('path');
-const internalFsBinding = internalBinding('fs');
+const { internalModuleStat: vfsInternalModuleStat } = require('internal/modules/vfs_resolution');
 const { safeGetenv } = internalBinding('credentials');
 const {
   getCjsConditions,
@@ -278,7 +278,7 @@ function stat(filename) {
     const result = statCache.get(filename);
     if (result !== undefined) { return result; }
   }
-  const result = internalFsBinding.internalModuleStat(filename);
+  const result = vfsInternalModuleStat(filename);
   if (statCache !== null && result >= 0) {
     // Only set cache when `internalModuleStat(filename)` succeeds.
     statCache.set(filename, result);
@@ -2101,7 +2101,9 @@ Module._extensions['.json'] = function(module, filename) {
  */
 Module._extensions['.node'] = function(module, filename) {
   // Be aware this doesn't use `content`
-  return process.dlopen(module, path.toNamespacedPath(filename));
+  const { resolveAddonRealPath } = require('internal/modules/vfs_addons');
+  const realFilename = resolveAddonRealPath(filename) ?? filename;
+  return process.dlopen(module, path.toNamespacedPath(realFilename));
 };
 
 /**
diff --git a/lib/internal/modules/esm/get_format.js b/lib/internal/modules/esm/get_format.js
index 7bc69b3eb5c3..f115c1ea047b 100644
--- a/lib/internal/modules/esm/get_format.js
+++ b/lib/internal/modules/esm/get_format.js
@@ -10,7 +10,8 @@ const {
 } = primordials;
 const { getOptionValue } = require('internal/options');
 const { getValidatedPath } = require('internal/fs/utils');
-const fsBindings = internalBinding('fs');
+const { getFormatOfExtensionlessFile: vfsGetFormatOfExtensionlessFile } =
+  require('internal/modules/vfs_resolution');
 const { internal: internalConstants } = internalBinding('constants');
 
 const extensionFormatMap = {
@@ -66,7 +67,7 @@ function mimeToFormat(mime) {
  */
 function getFormatOfExtensionlessFile(url) {
   const path = getValidatedPath(url);
-  switch (fsBindings.getFormatOfExtensionlessFile(path)) {
+  switch (vfsGetFormatOfExtensionlessFile(path)) {
     case internalConstants.EXTENSIONLESS_FORMAT_WASM:
       return 'wasm';
     default:
diff --git a/lib/internal/modules/esm/resolve.js b/lib/internal/modules/esm/resolve.js
index 3916e79328ed..f1e7f8c799bc 100644
--- a/lib/internal/modules/esm/resolve.js
+++ b/lib/internal/modules/esm/resolve.js
@@ -32,7 +32,10 @@ const { sep, posix: { relative: relativePosixPath }, resolve, join } = require('
 const { URL, pathToFileURL, fileURLToPath, isURL, URLParse } = require('internal/url');
 const { getCWDURL, setOwnProperty, kEmptyObject } = require('internal/util');
 const { canParse: URLCanParse } = internalBinding('url');
-const { legacyMainResolve: FSLegacyMainResolve } = internalBinding('fs');
+const {
+  legacyMainResolve: FSLegacyMainResolve,
+  internalModuleStat: vfsInternalModuleStat,
+} = require('internal/modules/vfs_resolution');
 const {
   ERR_INPUT_TYPE_NOT_ALLOWED,
   ERR_INVALID_ARG_TYPE,
@@ -49,7 +52,6 @@ const {
 const { defaultGetFormatWithoutErrors } = require('internal/modules/esm/get_format');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const internalFsBinding = internalBinding('fs');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -245,7 +247,7 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     throw err;
   }
 
-  const stats = internalFsBinding.internalModuleStat(
+  const stats = vfsInternalModuleStat(
     StringPrototypeEndsWith(path, '/') ? StringPrototypeSlice(path, -1) : path,
   );
 
diff --git a/lib/internal/modules/package_json_reader.js b/lib/internal/modules/package_json_reader.js
index 6c6bf0383bc3..c6ed3254a5ef 100644
--- a/lib/internal/modules/package_json_reader.js
+++ b/lib/internal/modules/package_json_reader.js
@@ -24,10 +24,15 @@ const {
   },
 } = require('internal/errors');
 const { kEmptyObject } = require('internal/util');
-const modulesBinding = internalBinding('modules');
 const path = require('path');
 const { validateString } = require('internal/validators');
-const internalFsBinding = internalBinding('fs');
+const {
+  internalModuleStat: vfsInternalModuleStat,
+  readPackageJSON: vfsReadPackageJSON,
+  getNearestParentPackageJSON: vfsGetNearestParentPackageJSON,
+  getPackageScopeConfig: vfsGetPackageScopeConfig,
+  getPackageType: vfsGetPackageType,
+} = require('internal/modules/vfs_resolution');
 
 
 /**
@@ -122,7 +127,7 @@ const requiresJSONParse = (value) => (value !== undefined && (value[0] === '[' |
 function read(jsonPath, { base, specifier, isESM } = kEmptyObject) {
   // This function will be called by both CJS and ESM, so we need to make sure
   // non-null attributes are converted to strings.
-  const parsed = modulesBinding.readPackageJSON(
+  const parsed = vfsReadPackageJSON(
     jsonPath,
     isESM,
     base == null ? undefined : `${base}`,
@@ -170,7 +175,7 @@ function getNearestParentPackageJSON(checkPath) {
     return deserializedPackageJSONCache.get(parentPackageJSONPath);
   }
 
-  const result = modulesBinding.getNearestParentPackageJSON(checkPath);
+  const result = vfsGetNearestParentPackageJSON(checkPath);
   const packageConfig = deserializePackageJSON(checkPath, result);
 
   moduleToParentPackageJSONCache.set(checkPath, packageConfig.path);
@@ -190,7 +195,7 @@ function getNearestParentPackageJSON(checkPath) {
  * @returns {import('typings/internalBinding/modules').PackageConfig} - The package configuration.
  */
 function getPackageScopeConfig(resolved) {
-  const result = modulesBinding.getPackageScopeConfig(`${resolved}`);
+  const result = vfsGetPackageScopeConfig(`${resolved}`);
 
   if (ArrayIsArray(result)) {
     const { data, exists, path } = deserializePackageJSON(`${resolved}`, result);
@@ -219,8 +224,7 @@ function getPackageScopeConfig(resolved) {
  * @returns {string}
  */
 function getPackageType(url) {
-  const type = modulesBinding.getPackageType(`${url}`);
-  return type ?? 'none';
+  return vfsGetPackageType(`${url}`);
 }
 
 const invalidPackageNameRegEx = /^\.|%|\\/;
@@ -280,7 +284,7 @@ function getPackageJSONURL(specifier, base) {
   let packageJSONPath = fileURLToPath(packageJSONUrl);
   let lastPath;
   do {
-    const stat = internalFsBinding.internalModuleStat(
+    const stat = vfsInternalModuleStat(
       StringPrototypeSlice(packageJSONPath, 0, packageJSONPath.length - 13),
     );
     // Check for !stat.isDirectory()
diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index 2974459755ec..0edf898f07c3 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -5,7 +5,7 @@ const {
   globalThis,
 } = primordials;
 
-const { getNearestParentPackageJSONType } = internalBinding('modules');
+const { getNearestParentPackageJSONType } = require('internal/modules/vfs_resolution');
 const { getOptionValue } = require('internal/options');
 const path = require('path');
 const { pathToFileURL, URL } = require('internal/url');
@@ -98,6 +98,11 @@ async function asyncRunEntryPointWithESMLoader(callback) {
     } else {
       cascadedLoader.waitForAsyncLoaderHookInitialization();
     }
+    // Now that -r and --import preloads have all run, mount any --vfs-mount
+    // targets so a provider registered by either backs them. Idempotent: a
+    // no-op when the main thread already mounted in prepareExecution() (no
+    // --import present).
+    require('internal/process/pre_execution').finishVfsMounts();
     await callback(cascadedLoader);
   } catch (err) {
     if (hasUncaughtExceptionCaptureCallback()) {
@@ -138,9 +143,22 @@ function runEntryPointWithESMLoader(callback) {
  * @param {string} main - First positional CLI argument, such as `'entry.js'` from `node entry.js`
  */
 function executeUserEntryPoint(main = process.argv[1]) {
+  const isEntryURL = getOptionValue('--entry-url');
+  // With --vfs-load the entry point is the mount root, a directory, which only
+  // resolves to its index.js / package.json "main" once the mount is active.
+  // When --import or a custom loader forces the ESM loader, the mount is not
+  // active until finishVfsMounts() runs inside runEntryPointWithESMLoader
+  // (after --import), which is after resolveMainPath() would normally run - and
+  // the ESM loader cannot import a directory. So defer resolving the entry into
+  // that flow, where the mount is in place and the directory resolves to a file
+  // the ESM loader accepts.
+  const deferResolve = !isEntryURL && getOptionValue('--vfs-load') &&
+    (getOptionValue('--import').length > 0 ||
+     getOptionValue('--experimental-loader').length > 0);
+
   let useESMLoader;
   let resolvedMain;
-  if (getOptionValue('--entry-url')) {
+  if (isEntryURL || deferResolve) {
     useESMLoader = true;
   } else {
     resolvedMain = resolveMainPath(main);
@@ -153,10 +171,11 @@ function executeUserEntryPoint(main = process.argv[1]) {
     const { wrapModuleLoad } = cjsLoader;
     wrapModuleLoad(main, null, true);
   } else {
-    const mainPath = resolvedMain || main;
-    const mainURL = getOptionValue('--entry-url') ? new URL(mainPath, getCWDURL()) : pathToFileURL(mainPath);
-
     runEntryPointWithESMLoader((cascadedLoader) => {
+      // `deferResolve` postpones resolveMainPath() to here, after --import and
+      // the VFS mount are in place (see above).
+      const mainPath = deferResolve ? (resolveMainPath(main) || main) : (resolvedMain || main);
+      const mainURL = isEntryURL ? new URL(mainPath, getCWDURL()) : pathToFileURL(mainPath);
       // Note that if the graph contains unsettled TLA, this may never resolve
       // even after the event loop stops running.
       return cascadedLoader.import(mainURL, undefined, { __proto__: null }, undefined, true);
diff --git a/lib/internal/modules/vfs_addons.js b/lib/internal/modules/vfs_addons.js
new file mode 100644
index 000000000000..c2f41800111f
--- /dev/null
+++ b/lib/internal/modules/vfs_addons.js
@@ -0,0 +1,106 @@
+'use strict';
+
+// Native addon ('.node' file) loading for a path inside an active VFS
+// mount (whether mounted via the --vfs CLI flag or from plain userland
+// code - internal/vfs/setup.js's activeVFSList covers both the same way).
+// `dlopen()` needs a real path on disk - there's nothing to intercept at
+// the fs-module level for that - so:
+//  - a directory-backed mount (RealFSProvider) already has a real
+//    underlying file; translate the virtual path back to it and dlopen
+//    that directly, no copying needed.
+//  - an archive-backed mount (ZipProvider) has no real backing file;
+//    extract the entry's bytes to a real temp file named by content hash
+//    (so repeated loads of the same addon within this process reuse the
+//    same extraction instead of re-extracting) and dlopen that instead.
+//    Each process gets its own pid-scoped temp directory - sharing one
+//    across processes would let one process delete or overwrite a file
+//    another process still has mapped. Extracted files are best-effort
+//    removed when the process exits.
+
+const {
+  SafeSet,
+} = primordials;
+
+const { createHash } = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { findVFSForPath } = require('internal/vfs/registry');
+
+const extractedAddons = new SafeSet();
+let cleanupRegistered = false;
+
+function registerCleanup() {
+  if (cleanupRegistered) { return; }
+  cleanupRegistered = true;
+  process.once('exit', () => {
+    for (const extractedPath of extractedAddons) {
+      try {
+        fs.unlinkSync(extractedPath);
+      } catch {
+        // Best effort: the file may still be mapped (Windows keeps loaded
+        // DLLs locked).
+      }
+    }
+  });
+}
+
+/**
+ * Extracts a VFS-internal addon to a real, content-hashed temp file (or
+ * reuses one already extracted with the same content) and returns its path.
+ * @param {import('internal/vfs/file_system').VirtualFileSystem} vfs
+ * @param {string} vfsPath
+ * @returns {string}
+ */
+function extractAddon(vfs, vfsPath) {
+  const content = vfs.readFileSync(vfsPath);
+  const hash = createHash('sha256').update(content).digest('hex');
+  const dir = path.join(os.tmpdir(), `node-vfs-addons-${process.pid}`);
+  const dest = path.join(dir, `${hash}.node`);
+
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpDest = `${dest}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpDest, content);
+    try {
+      fs.renameSync(tmpDest, dest);
+    } catch (err) {
+      // Another thread in this process (e.g. a worker_thread, which shares
+      // our pid and thus our temp directory) extracting the same content
+      // may have won the race; that's fine as long as the destination
+      // exists now.
+      try {
+        fs.unlinkSync(tmpDest);
+      } catch {
+        // Ignore: best-effort cleanup of our own losing-race temp file.
+      }
+      if (!fs.existsSync(dest)) { throw err; }
+    }
+  }
+
+  extractedAddons.add(dest);
+  registerCleanup();
+  return dest;
+}
+
+/**
+ * Resolves the real, on-disk path to `dlopen()` for a native addon whose
+ * virtual path is under an active VFS mount.
+ * @param {string} vfsPath
+ * @returns {string | null} The real path to dlopen, or null if `vfsPath` is
+ *   not under an active VFS mount (the caller should dlopen it unchanged).
+ */
+function resolveAddonRealPath(vfsPath) {
+  const found = findVFSForPath(vfsPath);
+  if (found === null) { return null; }
+  const { vfs, normalized } = found;
+  const provider = vfs.provider;
+  if (typeof provider.toRealPath === 'function') {
+    return provider.toRealPath(vfs.toProviderPath(normalized));
+  }
+  return extractAddon(vfs, normalized);
+}
+
+module.exports = {
+  resolveAddonRealPath,
+};
diff --git a/lib/internal/modules/vfs_resolution.js b/lib/internal/modules/vfs_resolution.js
new file mode 100644
index 000000000000..22656b44060f
--- /dev/null
+++ b/lib/internal/modules/vfs_resolution.js
@@ -0,0 +1,291 @@
+'use strict';
+
+// The CJS/ESM loader mostly resolves and reads files through the public
+// `fs` module, which any active VFS mount (internal/vfs/setup.js's
+// activeVFSList, populated by every vfs.mount() call - whether from the
+// --vfs CLI flag or from plain userland code) already redirects for any
+// path under that mount. But a handful of module-resolution primitives
+// bypass `fs` entirely and call straight into
+// internalBinding('fs')/internalBinding('modules'), hitting the real
+// filesystem no matter what's mounted. This file provides VFS-aware
+// replacements for exactly those primitives, each matching the native
+// function's contract precisely: when the given path is under an active
+// VFS mount, do the equivalent work against that VirtualFileSystem
+// (bounded at the mount's own root - never falling through past it into the
+// real, unmounted parent directory); otherwise call the real native
+// binding, unchanged.
+
+const {
+  ArrayIsArray,
+  JSONParse,
+  JSONStringify,
+  StringPrototypeEndsWith,
+} = primordials;
+
+const { Buffer } = require('buffer');
+const path = require('path');
+const {
+  codes: {
+    ERR_INVALID_PACKAGE_CONFIG,
+  },
+} = require('internal/errors');
+// From the tiny registry, not internal/vfs/setup: this runs on every module
+// resolution, and the registry answers "no VFS mounted" without loading the
+// heavy internal/vfs machinery (which stays off the startup path and out of
+// the startup snapshot; see test/parallel/test-bootstrap-modules.js).
+const { findVFSForPath } = require('internal/vfs/registry');
+
+const internalFsBinding = internalBinding('fs');
+const modulesBinding = internalBinding('modules');
+const { internal: internalConstants } = internalBinding('constants');
+
+/**
+ * VFS-aware replacement for internalBinding('fs').internalModuleStat: -2
+ * (not found/error), 0 (file), or 1 (directory) - callers only ever check
+ * `>= 0` vs not, so any error collapses to -2 like a plain ENOENT would.
+ * @param {string} filename
+ * @returns {number}
+ */
+function internalModuleStat(filename) {
+  const found = findVFSForPath(filename);
+  if (found === null) { return internalFsBinding.internalModuleStat(filename); }
+  try {
+    return found.vfs.statSync(found.normalized).isDirectory() ? 1 : 0;
+  } catch {
+    return -2;
+  }
+}
+
+/**
+ * Reads and minimally parses a package.json at an exact path, matching the
+ * shape `src/node_modules.cc`'s `PackageConfig::Serialize` produces:
+ * `[name, main, type, imports, exports, filePath]`, or `undefined` if the
+ * file doesn't exist. `imports`/`exports` are re-serialized to a JSON string
+ * when they're objects/arrays, exactly like the native reader, so
+ * `package_json_reader.js`'s existing lazy-parse-on-access getters keep
+ * working unchanged.
+ * @param {import('internal/vfs/file_system').VirtualFileSystem} vfs
+ * @param {string} jsonPath
+ * @returns {Array | undefined}
+ */
+function readPackageJSONFile(vfs, jsonPath) {
+  let raw;
+  try {
+    raw = vfs.readFileSync(jsonPath, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') { return undefined; }
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSONParse(raw);
+  } catch (err) {
+    throw new ERR_INVALID_PACKAGE_CONFIG(jsonPath, undefined, err.message);
+  }
+  if (parsed === null || typeof parsed !== 'object' || ArrayIsArray(parsed)) {
+    throw new ERR_INVALID_PACKAGE_CONFIG(jsonPath, undefined, 'not an object');
+  }
+  const name = typeof parsed.name === 'string' ? parsed.name : undefined;
+  const main = typeof parsed.main === 'string' ? parsed.main : undefined;
+  const type = parsed.type === 'commonjs' || parsed.type === 'module' ? parsed.type : 'none';
+  const toRaw = (value) => {
+    if (typeof value === 'string') { return value; }
+    if (typeof value === 'object' && value !== null) { return JSONStringify(value); }
+    return undefined;
+  };
+  const imports = toRaw(parsed.imports);
+  const exports = toRaw(parsed.exports);
+  return [name, main, type, imports, exports, jsonPath];
+}
+
+/**
+ * VFS-aware replacement for internalBinding('modules').readPackageJSON:
+ * reads one exact package.json path (no directory walking).
+ * @param {string} jsonPath
+ * @param {boolean} isESM
+ * @param {string} [base]
+ * @param {string} [specifier]
+ * @returns {Array | undefined}
+ */
+function readPackageJSON(jsonPath, isESM, base, specifier) {
+  const found = findVFSForPath(jsonPath);
+  if (found === null) { return modulesBinding.readPackageJSON(jsonPath, isESM, base, specifier); }
+  return readPackageJSONFile(found.vfs, found.normalized);
+}
+
+/**
+ * Shared directory-climbing algorithm behind getNearestParentPackageJSON()/
+ * getNearestParentPackageJSONType(): starting at the directory containing
+ * `fromPath`, look for a package.json, then climb toward the mount's root -
+ * stopping (not found) at a directory literally named node_modules, or the
+ * moment climbing further would step outside the mount, whichever comes
+ * first. Never falls through to the real parent directory above the mount.
+ * @param {import('internal/vfs/file_system').VirtualFileSystem} vfs
+ * @param {string} fromPath
+ * @returns {Array | undefined}
+ */
+function findPackageJSONUpward(vfs, fromPath) {
+  let dir = path.dirname(fromPath);
+  while (true) {
+    if (path.basename(dir) === 'node_modules') { return undefined; }
+    const found = readPackageJSONFile(vfs, path.join(dir, 'package.json'));
+    if (found !== undefined) { return found; }
+    if (dir === vfs.mountPoint) { return undefined; }
+    const parent = path.dirname(dir);
+    if (parent === dir) { return undefined; }
+    dir = parent;
+  }
+}
+
+/**
+ * VFS-aware replacement for
+ * internalBinding('modules').getNearestParentPackageJSON.
+ * @param {string} checkPath
+ * @returns {Array | undefined}
+ */
+function getNearestParentPackageJSON(checkPath) {
+  const found = findVFSForPath(checkPath);
+  if (found === null) { return modulesBinding.getNearestParentPackageJSON(checkPath); }
+  return findPackageJSONUpward(found.vfs, found.normalized);
+}
+
+/**
+ * VFS-aware replacement for
+ * internalBinding('modules').getNearestParentPackageJSONType.
+ * @param {string} checkPath
+ * @returns {string | undefined}
+ */
+function getNearestParentPackageJSONType(checkPath) {
+  const found = findVFSForPath(checkPath);
+  if (found === null) { return modulesBinding.getNearestParentPackageJSONType(checkPath); }
+  const result = findPackageJSONUpward(found.vfs, found.normalized);
+  return result === undefined ? undefined : result[2];
+}
+
+/**
+ * Shared directory-climbing algorithm behind getPackageScopeConfig()/
+ * getPackageType(): starting at the *same* directory as `resolvedPath`
+ * itself (matching the native "./package.json"-relative-to-self behavior),
+ * climb toward the mount root, stopping at a candidate that would live
+ * directly inside a node_modules directory, or at the mount's own root.
+ * @param {import('internal/vfs/file_system').VirtualFileSystem} vfs
+ * @param {string} resolvedPath
+ * @param {boolean} returnOnlyType
+ * @returns {Array | string | undefined}
+ */
+function findPackageScopeConfig(vfs, resolvedPath, returnOnlyType) {
+  const nodeModulesBoundary = path.join('node_modules', 'package.json');
+  let dir = path.dirname(resolvedPath);
+  while (true) {
+    const candidate = path.join(dir, 'package.json');
+    if (StringPrototypeEndsWith(candidate, nodeModulesBoundary)) { break; }
+    const found = readPackageJSONFile(vfs, candidate);
+    if (found !== undefined) { return returnOnlyType ? found[2] : found; }
+    if (dir === vfs.mountPoint) { break; }
+    const parent = path.dirname(dir);
+    if (parent === dir) { break; }
+    dir = parent;
+  }
+  return returnOnlyType ? undefined : path.join(dir, 'package.json');
+}
+
+/**
+ * @param {string | URL} resolved
+ * @returns {object | string}
+ */
+function getPackageScopeConfig(resolved) {
+  const resolvedPath = `${resolved}`;
+  const found = findVFSForPath(resolvedPath);
+  if (found === null) { return modulesBinding.getPackageScopeConfig(resolvedPath); }
+  return findPackageScopeConfig(found.vfs, found.normalized, false);
+}
+
+/**
+ * @param {string | URL} url
+ * @returns {string}
+ */
+function getPackageType(url) {
+  const resolvedPath = `${url}`;
+  const found = findVFSForPath(resolvedPath);
+  if (found === null) { return modulesBinding.getPackageType(resolvedPath) ?? 'none'; }
+  return findPackageScopeConfig(found.vfs, found.normalized, true) ?? 'none';
+}
+
+// Same order/semantics as esm/resolve.js's own legacyMainResolveExtensions -
+// duplicated here (rather than imported) to avoid a dependency cycle between
+// this file and the ESM resolver; both must stay in sync with
+// src/node_file.cc's `legacy_main_extensions`.
+const legacyMainExtensions = [
+  '', '.js', '.json', '.node',
+  '/index.js', '/index.json', '/index.node',
+  '/index.js', '/index.json', '/index.node',
+];
+const kWithMainEnd = 7;
+
+/**
+ * VFS-aware replacement for internalBinding('fs').legacyMainResolve.
+ * @param {string} packagePath
+ * @param {string} [main]
+ * @param {string} [base]
+ * @returns {number | undefined}
+ */
+function legacyMainResolve(packagePath, main, base) {
+  const found = findVFSForPath(packagePath);
+  if (found === null) { return internalFsBinding.legacyMainResolve(packagePath, main, base); }
+  const { vfs, normalized } = found;
+
+  const isFile = (candidate) => {
+    try {
+      return !vfs.statSync(candidate).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+
+  if (typeof main === 'string') {
+    const initial = path.resolve(normalized, main);
+    for (let i = 0; i < kWithMainEnd; i++) {
+      if (isFile(initial + legacyMainExtensions[i])) { return i; }
+    }
+  }
+
+  const initial = path.resolve(normalized, './index');
+  for (let i = kWithMainEnd; i < legacyMainExtensions.length; i++) {
+    if (isFile(initial + legacyMainExtensions[i])) { return i; }
+  }
+  return undefined;
+}
+
+const WASM_MAGIC = Buffer.from([0x00, 0x61, 0x73, 0x6d]);
+
+/**
+ * VFS-aware replacement for
+ * internalBinding('fs').getFormatOfExtensionlessFile.
+ * @param {string} filePath
+ * @returns {number}
+ */
+function getFormatOfExtensionlessFile(filePath) {
+  const found = findVFSForPath(filePath);
+  if (found === null) { return internalFsBinding.getFormatOfExtensionlessFile(filePath); }
+  try {
+    const content = found.vfs.readFileSync(found.normalized);
+    if (content.length >= 4 && content[0] === WASM_MAGIC[0] && content[1] === WASM_MAGIC[1] &&
+        content[2] === WASM_MAGIC[2] && content[3] === WASM_MAGIC[3]) {
+      return internalConstants.EXTENSIONLESS_FORMAT_WASM;
+    }
+  } catch {
+    // Matches the native function's own fallback on open/read failure.
+  }
+  return internalConstants.EXTENSIONLESS_FORMAT_JAVASCRIPT;
+}
+
+module.exports = {
+  internalModuleStat,
+  readPackageJSON,
+  getNearestParentPackageJSON,
+  getNearestParentPackageJSONType,
+  getPackageScopeConfig,
+  getPackageType,
+  legacyMainResolve,
+  getFormatOfExtensionlessFile,
+};
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 5c9ed45eef26..f33bff636b6f 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -2,6 +2,8 @@
 
 const {
   ArrayPrototypeForEach,
+  ArrayPrototypePush,
+  ArrayPrototypeSplice,
   Date,
   DatePrototypeGetDate,
   DatePrototypeGetFullYear,
@@ -110,8 +112,19 @@ function prepareExecution(options) {
 
   refreshRuntimeOptions();
 
+  // Needed before finishVfsMounts() below: mounting a VFS logs through
+  // internal/util/debuglog, which throws if used before this runs.
+  setupDebugEnv();
+
+  // If --vfs-mount is active, resolve its targets now - with --vfs-load the
+  // main entry point below anchors on the last mount's root rather than the
+  // real cwd - but defer choosing providers and mounting until
+  // finishVfsMounts() below, after -r preload modules have had a chance to
+  // register a custom provider for a target.
+  const vfsMounts = resolveVfsMounts();
+
   // Patch the process object and get the resolved main entry point.
-  const mainEntry = patchProcessObject(expandArgv1);
+  const mainEntry = patchProcessObject(expandArgv1, vfsMounts.loadTarget);
   setupTraceCategoryState();
   setupInspectorHooks();
   setupNetworkInspection();
@@ -127,7 +140,6 @@ function prepareExecution(options) {
   setupWebsocket();
   setupEventsource();
   setupCodeCoverage();
-  setupDebugEnv();
   // Process initial diagnostic reporting configuration, if present.
   initializeReport();
 
@@ -178,10 +190,15 @@ function prepareExecution(options) {
     initializeModuleLoaders({ shouldSpawnLoaderHookWorker, shouldPreloadModules });
   }
 
-  // Mount any --vfs-mount targets. Runs after -r preload modules, so a
-  // preloaded module can register a custom provider (via node:vfs's
-  // registerProvider()) before a target's provider is chosen.
-  mountVfsTargets();
+  // With no --import, all preloads (-r) have run on the main thread, so mount
+  // the --vfs-mount targets now. Otherwise defer until after --import runs:
+  // finishVfsMounts() is called again (idempotently) from
+  // asyncRunEntryPointWithESMLoader in internal/modules/run_main once -r and
+  // --import preloads are both done - which also covers worker threads, whose
+  // preloads all run later. A preload may register a custom provider first.
+  if (isMainThread && getOptionValue('--import').length === 0) {
+    finishVfsMounts();
+  }
 
   // This has to be done after the user module loader is initialized,
   // in case undici is externalized.
@@ -205,50 +222,6 @@ function setupVmModules() {
   }
 }
 
-/**
- * Mounts each --vfs-mount target as a virtual file system. Each entry is
- * `<source>` or `<source>=<target>`, where `<source>` is the directory or
- * archive to mount and `<target>` (optional) is where to mount it, defaulting
- * to `<source>`'s own resolved path. A provider is chosen for each source by
- * its contents (see internal/vfs/provider_registry); a source no provider
- * claims is rejected.
- */
-function mountVfsTargets() {
-  const entries = getOptionValue('--vfs-mount');
-  if (entries.length === 0) return;
-  emitExperimentalWarning('--vfs-mount');
-
-  const fs = require('fs');
-  const path = require('path');
-  const { selectProvider } = require('internal/vfs/provider_registry');
-  const { VirtualFileSystem } = require('internal/vfs/file_system');
-
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    const sep = StringPrototypeIndexOf(entry, '=');
-    const source = sep === -1 ? entry : StringPrototypeSlice(entry, 0, sep);
-    const target = sep === -1 ? source : StringPrototypeSlice(entry, sep + 1);
-    const resolvedSource = path.resolve(source);
-    const mountPoint = path.resolve(target);
-
-    let stats;
-    try {
-      stats = fs.statSync(resolvedSource);
-    } catch {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    if (!stats.isDirectory() && !stats.isFile()) {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    const provider = selectProvider(resolvedSource, stats);
-    if (provider === null) {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
-    vfs.mount(mountPoint);
-  }
-}
-
 function setupHttpProxy() {
   // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
   if (!getOptionValue('--use-env-proxy')) {
@@ -312,9 +285,11 @@ function refreshRuntimeOptions() {
  * Replace `process.argv[1]` with the resolved absolute file path of the entry point, if found.
  * @param {boolean} expandArgv1 - Whether to replace `process.argv[1]` with the resolved absolute file path of
  *   the main entry point.
+ * @param {string} [vfsMountTarget] - The resolved --vfs target, if active; process.argv[1] is then unconditionally
+ *   set to it, and whatever the user actually passed shifts down to argv[2] onward.
  * @returns {string}
  */
-function patchProcessObject(expandArgv1) {
+function patchProcessObject(expandArgv1, vfsMountTarget) {
   const binding = internalBinding('process_methods');
   binding.patchProcessObject(process);
 
@@ -333,10 +308,29 @@ function patchProcessObject(expandArgv1) {
 
   /** @type {string} */
   let mainEntry;
-  // If requested, update process.argv[1] to replace whatever the user provided with the resolved absolute file path of
-  // the entry point.
-  if (expandArgv1 && process.argv[1] && process.argv[1][0] !== '-') {
-    // Expand process.argv[1] into a full path.
+  if (expandArgv1 && vfsMountTarget !== undefined) {
+    // With --vfs active, argv[1] is unconditionally the mount root itself -
+    // as if the user had run `node <mountRoot>` directly - so normal
+    // package.json "main"/index.js resolution decides what actually runs,
+    // the same way it would for any other directory. A positional argument
+    // is never an entry-point override here; it is a user argument, so shift
+    // it (and everything after it) down to argv[2] onward. This is what a
+    // self-mounting shebang line (`#!/usr/bin/env node --vfs`) needs: the
+    // kernel appends the script's own path as the argument that becomes
+    // --vfs's value, so the first argument the *user* supplies on the
+    // command line is what would otherwise land in argv[1] and be misread
+    // as an entry-point path instead of the app's own argument. Workers are
+    // unaffected - they are prepared with expandArgv1 false and name their
+    // entry through `new Worker(filename)`, not argv[1].
+    mainEntry = vfsMountTarget;
+    if (process.argv[1] !== undefined) {
+      ArrayPrototypeSplice(process.argv, 1, 0, mainEntry);
+    } else {
+      process.argv[1] = mainEntry;
+    }
+  } else if (expandArgv1 && process.argv[1] && process.argv[1][0] !== '-') {
+    // If requested, update process.argv[1] to replace whatever the user
+    // provided with the resolved absolute file path of the entry point.
     const path = require('path');
     try {
       mainEntry = path.resolve(process.argv[1]);
@@ -493,6 +487,87 @@ function setupVfs() {
   BuiltinModule.allowRequireByUsers('vfs');
 }
 
+// The --vfs-mount targets resolved by resolveVfsMounts(), pending until
+// finishVfsMounts() mounts them (exactly once, guarded by vfsMountsDone).
+let pendingVfsMounts = [];
+let vfsMountsDone = false;
+
+/**
+ * Resolves and validates every --vfs-mount entry without yet choosing a
+ * provider or mounting, storing the result for finishVfsMounts(). Each entry
+ * is `<source>` or `<source>=<target>`, where `<source>` is the directory or
+ * archive to mount and `<target>` (optional) is where to mount it, defaulting
+ * to `<source>`'s own resolved path. Kept separate from finishVfsMounts() so
+ * the --vfs-load entry point's path can anchor process.argv[1] resolution
+ * early (that resolution anchors on the mount's root rather than the real
+ * cwd), while provider selection is deferred until after -r/--import preload
+ * modules have run - see prepareExecution().
+ * @returns {{ loadTarget: string | undefined }} The mount point to run as the
+ *   entry point when --vfs-load is set, otherwise undefined.
+ */
+function resolveVfsMounts() {
+  const entries = getOptionValue('--vfs-mount');
+  if (entries.length === 0) return { loadTarget: undefined };
+  emitExperimentalWarning('--vfs-mount');
+
+  const fs = require('fs');
+  const path = require('path');
+  const mounts = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const sep = StringPrototypeIndexOf(entry, '=');
+    const source = sep === -1 ? entry : StringPrototypeSlice(entry, 0, sep);
+    const target = sep === -1 ? source : StringPrototypeSlice(entry, sep + 1);
+    const resolvedSource = path.resolve(source);
+    const mountPoint = path.resolve(target);
+
+    let stats;
+    try {
+      stats = fs.statSync(resolvedSource);
+    } catch {
+      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
+    }
+    if (!stats.isDirectory() && !stats.isFile()) {
+      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
+    }
+    ArrayPrototypePush(mounts, { source: resolvedSource, mountPoint, stats });
+  }
+  pendingVfsMounts = mounts;
+
+  // --vfs-load runs the entry point from the last --vfs-mount. (The C++ option
+  // parser already rejects --vfs-load without any --vfs-mount.)
+  const loadTarget = getOptionValue('--vfs-load') ?
+    mounts[mounts.length - 1].mountPoint : undefined;
+  return { loadTarget };
+}
+
+/**
+ * Chooses a provider for each resolved --vfs-mount (see resolveVfsMounts())
+ * and mounts it. Module resolution then finds the mounts the same way any
+ * other VFS mount is found, via internal/vfs/setup.js's activeVFSList. Runs
+ * after -r and --import preload modules, so a preloaded module can register
+ * (through node:vfs's registerProvider()) a custom provider; custom providers
+ * are always tried before the built-ins. A file with no matching provider is
+ * rejected. Idempotent: called both from prepareExecution() (main thread, no
+ * --import) and from asyncRunEntryPointWithESMLoader() in
+ * internal/modules/run_main (after --import); only the first call mounts.
+ */
+function finishVfsMounts() {
+  if (vfsMountsDone || pendingVfsMounts.length === 0) return;
+  vfsMountsDone = true;
+  const { VirtualFileSystem } = require('internal/vfs/file_system');
+  const { selectProvider } = require('internal/vfs/provider_registry');
+  for (let i = 0; i < pendingVfsMounts.length; i++) {
+    const { source, mountPoint, stats } = pendingVfsMounts[i];
+    const provider = selectProvider(source, stats);
+    if (provider === null) {
+      throw new ERR_VFS_INVALID_TARGET(source);
+    }
+    const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
+    vfs.mount(mountPoint);
+  }
+}
+
 function setupWebStorage() {
   if (getEmbedderOptions().noBrowserGlobals ||
       !getOptionValue('--experimental-webstorage')) {
@@ -883,5 +958,6 @@ module.exports = {
   prepareTestRunnerMainExecution,
   markBootstrapComplete,
   loadPreloadModules,
+  finishVfsMounts,
   initializeFrozenIntrinsics,
 };
diff --git a/lib/internal/vfs/file_system.js b/lib/internal/vfs/file_system.js
index e47ed4c61080..fa7fee6e2f61 100644
--- a/lib/internal/vfs/file_system.js
+++ b/lib/internal/vfs/file_system.js
@@ -183,6 +183,18 @@ class VirtualFileSystem {
 
   // ==================== Path Resolution ====================
 
+  /**
+   * Converts an absolute mounted path to a provider-relative POSIX path.
+   * Exposed for callers (such as the module loader's native-addon handling)
+   * that need to reach the underlying provider directly, bypassing this
+   * facade's own fs-shaped methods.
+   * @param {string} inputPath The path to convert
+   * @returns {string}
+   */
+  toProviderPath(inputPath) {
+    return this.#toProviderPath(inputPath);
+  }
+
   /**
    * Converts an absolute mounted path to a provider-relative POSIX path.
    * If not mounted, treats the path as already provider-relative.
diff --git a/lib/internal/vfs/providers/real.js b/lib/internal/vfs/providers/real.js
index 02ceb1d365ef..6ea9252c5a99 100644
--- a/lib/internal/vfs/providers/real.js
+++ b/lib/internal/vfs/providers/real.js
@@ -284,6 +284,18 @@ class RealFSProvider extends VirtualProvider {
     return this.#rootPath;
   }
 
+  /**
+   * Resolves a VFS-relative path to its real underlying filesystem path,
+   * applying the same root-containment checks as every other method here,
+   * without opening it. Used by the module loader to `dlopen()` a native
+   * addon directly from its real location instead of extracting it.
+   * @param {string} vfsPath
+   * @returns {string}
+   */
+  toRealPath(vfsPath) {
+    return withoutVfsInterception(() => this.#resolvePath(vfsPath));
+  }
+
   /**
    * Resolves a VFS path to a real filesystem path.
    * Ensures the path doesn't escape the root directory.
diff --git a/lib/internal/vfs/registry.js b/lib/internal/vfs/registry.js
new file mode 100644
index 000000000000..d19e9ff1cfd4
--- /dev/null
+++ b/lib/internal/vfs/registry.js
@@ -0,0 +1,67 @@
+'use strict';
+
+// The registry of currently-mounted virtual file systems, kept in this tiny,
+// dependency-light module on purpose. The module-resolution fast path
+// (internal/modules/vfs_resolution, run on every stat()/package.json read)
+// only needs to answer "is this path under a mount?" - almost always "no" -
+// and must do so without dragging in the full internal/vfs machinery
+// (setup/fd/errors/providers). That machinery is loaded only when a VFS is
+// actually mounted, which is what pushes into `activeVFSList` here. Keeping
+// this off the universal startup path also keeps it out of the startup
+// snapshot (see test/parallel/test-bootstrap-modules.js).
+
+const {
+  ArrayPrototypeIndexOf,
+  ArrayPrototypePush,
+  ArrayPrototypeSplice,
+} = primordials;
+
+const { resolve } = require('path');
+
+const activeVFSList = [];
+
+function addVFS(vfs) {
+  ArrayPrototypePush(activeVFSList, vfs);
+}
+
+function removeVFS(vfs) {
+  const index = ArrayPrototypeIndexOf(activeVFSList, vfs);
+  if (index === -1) return false;
+  ArrayPrototypeSplice(activeVFSList, index, 1);
+  return true;
+}
+
+// The VFS that should handle `filename`, plus its resolved path, or null.
+// Fast: with no mounts (the common case) it returns before resolving anything.
+function findVFSForPath(filename) {
+  if (activeVFSList.length === 0) return null;
+  const normalized = resolve(filename);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      return { vfs, normalized };
+    }
+  }
+  return null;
+}
+
+// Like findVFSForPath, but also reports whether the entry exists in the mount.
+function findVFSForExists(filename) {
+  if (activeVFSList.length === 0) return null;
+  const normalized = resolve(filename);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      return { vfs, exists: vfs.existsSync(normalized) };
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  activeVFSList,
+  addVFS,
+  removeVFS,
+  findVFSForPath,
+  findVFSForExists,
+};
diff --git a/lib/internal/vfs/setup.js b/lib/internal/vfs/setup.js
index b063c31a0a32..a24282f07695 100644
--- a/lib/internal/vfs/setup.js
+++ b/lib/internal/vfs/setup.js
@@ -2,8 +2,6 @@
 
 const {
   ArrayPrototypeIndexOf,
-  ArrayPrototypePush,
-  ArrayPrototypeSplice,
   PromiseResolve,
   StringPrototypeStartsWith,
 } = primordials;
@@ -22,6 +20,15 @@ const {
 } = require('internal/errors');
 const { createENOENT, createEXDEV } = require('internal/vfs/errors');
 const { getVirtualFd, closeVirtualFd } = require('internal/vfs/fd');
+// activeVFSList + findVFS* live in a tiny registry so the resolution fast path
+// can consult them without loading this (heavy) module; see registry.js.
+const {
+  activeVFSList,
+  addVFS,
+  removeVFS,
+  findVFSForPath,
+  findVFSForExists,
+} = require('internal/vfs/registry');
 const { assertEncoding, vfsState, setVfsHandlers } = require('internal/fs/utils');
 const permission = require('internal/process/permission');
 const { getOptionValue } = require('internal/options');
@@ -73,8 +80,6 @@ function writeFileSyncFd(fd, data, options) {
 }
 
 // Registry of active VFS instances.
-const activeVFSList = [];
-
 let hooksInstalled = false;
 let vfsHandlerObj;
 
@@ -105,7 +110,7 @@ function registerVFS(vfs) {
       }
     }
   }
-  ArrayPrototypePush(activeVFSList, vfs);
+  addVFS(vfs);
   debug('register mount=%s active=%d', newMount, activeVFSList.length);
   if (!hooksInstalled) {
     vfsHandlerObj = createVfsHandlers();
@@ -117,37 +122,13 @@ function registerVFS(vfs) {
 }
 
 function deregisterVFS(vfs) {
-  const index = ArrayPrototypeIndexOf(activeVFSList, vfs);
-  if (index === -1) return;
-  ArrayPrototypeSplice(activeVFSList, index, 1);
+  if (!removeVFS(vfs)) return;
   debug('deregister active=%d', activeVFSList.length);
   if (activeVFSList.length === 0) {
     setVfsHandlers(null);
   }
 }
 
-function findVFSForExists(filename) {
-  const normalized = resolve(filename);
-  for (let i = 0; i < activeVFSList.length; i++) {
-    const vfs = activeVFSList[i];
-    if (vfs.shouldHandle(normalized)) {
-      return { vfs, exists: vfs.existsSync(normalized) };
-    }
-  }
-  return null;
-}
-
-function findVFSForPath(filename) {
-  const normalized = resolve(filename);
-  for (let i = 0; i < activeVFSList.length; i++) {
-    const vfs = activeVFSList[i];
-    if (vfs.shouldHandle(normalized)) {
-      return { vfs, normalized };
-    }
-  }
-  return null;
-}
-
 // Sync read: check exists first, fall through to ENOENT for mounted VFS.
 function findVFSWith(filename, syscall, fn) {
   const normalized = resolve(filename);
@@ -688,4 +669,5 @@ function createVfsHandlers() {
 module.exports = {
   registerVFS,
   deregisterVFS,
+  findVFSForPath,
 };
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
index 216e209d7322..ca605d2dc79e 100644
--- a/lib/internal/worker.js
+++ b/lib/internal/worker.js
@@ -210,7 +210,7 @@ class HeapProfileHandle {
 
 /**
  * A Worker constructed without an explicit `execArgv` already inherits the
- * parent's whole per-isolate options (including --vfs-mount) via
+ * parent's whole per-isolate options (including --vfs-mount/--vfs-load) via
  * the native Clone()-on-no-explicit-execArgv path. But one constructed with
  * an explicit `execArgv` gets a fresh, from-scratch options parse instead -
  * so without this, code running under a VFS mount could spawn an "escaped"
@@ -233,6 +233,11 @@ function withInheritedVfsFlags(execArgv) {
     }
   }
 
+  if (getOptionValue('--vfs-load') &&
+      !ArrayPrototypeSome(execArgv, (arg) => StringPrototypeStartsWith(arg, '--vfs-load'))) {
+    ArrayPrototypePush(toInject, '--vfs-load');
+  }
+
   if (toInject.length === 0) return execArgv;
   const result = ArrayPrototypeSlice(execArgv);
   ArrayPrototypePushApply(result, toInject);
diff --git a/src/node.cc b/src/node.cc
index b368c5873434..92d8256e4a7e 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -394,7 +394,12 @@ MaybeLocal<Value> StartExecution(Environment* env,
     return StartExecution(env, "internal/main/watch_mode");
   }
 
-  if (!first_argv.empty() && first_argv != "-") {
+  // --vfs-load makes the last --vfs-mount an entry point: with no positional
+  // argument, argv[1] defaults to that mount's root and its package.json
+  // "main"/index.js decides what runs (see patchProcessObject()), so route
+  // to run_main_module rather than falling through to the REPL/stdin.
+  if ((!first_argv.empty() && first_argv != "-") ||
+      env->options()->vfs_load) {
     return StartExecution(env, "internal/main/run_main_module");
   }
 
diff --git a/src/node_options.cc b/src/node_options.cc
index 66ffd968d870..aac3a985e8d5 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -215,8 +215,16 @@ void EnvironmentOptions::CheckOptions(std::vector<std::string>* errors,
   }
 #endif  // HAVE_OPENSSL
 
-  if (!experimental_vfs && !vfs_mounts.empty()) {
-    errors->push_back("--vfs-mount requires --experimental-vfs");
+  if (!experimental_vfs) {
+    if (!vfs_mounts.empty()) {
+      errors->push_back("--vfs-mount requires --experimental-vfs");
+    }
+    if (vfs_load) {
+      errors->push_back("--vfs-load requires --experimental-vfs");
+    }
+  }
+  if (vfs_load && vfs_mounts.empty()) {
+    errors->push_back("--vfs-load requires at least one --vfs-mount");
   }
 
   if (heap_snapshot_near_heap_limit < 0) {
@@ -633,6 +641,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "(option can be repeated; requires --experimental-vfs)",
             &EnvironmentOptions::vfs_mounts,
             kAllowedInEnvvar);
+  AddOption("--vfs-load",
+            "run the entry point and all module resolution against the last "
+            "--vfs-mount instead of the real file system (requires "
+            "--experimental-vfs and at least one --vfs-mount)",
+            &EnvironmentOptions::vfs_load,
+            kAllowedInEnvvar);
   AddOption("--experimental-quic",
 #ifndef OPENSSL_NO_QUIC
             "experimental QUIC support",
diff --git a/src/node_options.h b/src/node_options.h
index 10943da3d017..f99427cedbcc 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -134,6 +134,7 @@ class EnvironmentOptions : public Options {
   bool experimental_stream_iter = EXPERIMENTALS_DEFAULT_VALUE;
   bool experimental_vfs = EXPERIMENTALS_DEFAULT_VALUE;
   std::vector<std::string> vfs_mounts;
+  bool vfs_load = false;
   bool webstorage = HAVE_SQLITE;
   bool experimental_dtls = EXPERIMENTALS_DEFAULT_VALUE;
   bool experimental_quic = EXPERIMENTALS_DEFAULT_VALUE;
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index 099f8d2eaf05..a0dc8a6b2b3b 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -102,6 +102,12 @@ expected.beforePreExec = new Set([
   'NativeModule internal/modules/helpers',
   'NativeModule internal/modules/customization_hooks',
   'NativeModule internal/modules/package_json_reader',
+  // VFS-aware module-resolution primitives, used by every stat/package.json
+  // read, plus the tiny mount registry they consult. Both are lightweight and
+  // defer the internal/vfs machinery (setup, fd, providers) until a VFS is
+  // actually mounted, which never happens here.
+  'NativeModule internal/modules/vfs_resolution',
+  'NativeModule internal/vfs/registry',
   'Internal Binding module_wrap',
   'NativeModule internal/modules/cjs/loader',
   'NativeModule internal/modules/package_map',
diff --git a/test/parallel/test-vfs-cli-flag-addons.js b/test/parallel/test-vfs-cli-flag-addons.js
new file mode 100644
index 000000000000..c35ce6fb9cc6
--- /dev/null
+++ b/test/parallel/test-vfs-cli-flag-addons.js
@@ -0,0 +1,80 @@
+// Flags: --expose-internals
+'use strict';
+
+// Unit-tests internal/modules/vfs_addons's resolveAddonRealPath() directly
+// (rather than through an actual compiled native addon + --vfs child
+// process, which this environment can't build): a directory-backed mount
+// should resolve straight to the real underlying file, no copying; an
+// archive-backed mount should extract to a content-hashed real temp file,
+// reusing it on a repeated resolve of the same content.
+
+const common = require('../common');
+if (!common.hasCrypto) {
+  common.skip('missing crypto');
+}
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const zlib = require('zlib');
+
+const { VirtualFileSystem } = require('internal/vfs/file_system');
+const { RealFSProvider } = require('internal/vfs/providers/real');
+const { ZipProvider } = require('internal/vfs/providers/ziparchive');
+const { resolveAddonRealPath } = require('internal/modules/vfs_addons');
+
+tmpdir.refresh();
+
+// -- directory-backed: returns the real underlying path, no extraction ----
+
+{
+  const dir = path.join(tmpdir.path, 'dir-mount');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'addon.node'), 'fake addon bytes');
+
+  const provider = new RealFSProvider(dir);
+  const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
+  vfs.mount(dir);
+
+  const vfsPath = path.join(dir, 'addon.node');
+  const realPath = resolveAddonRealPath(vfsPath);
+  assert.strictEqual(realPath, path.join(dir, 'addon.node'));
+  assert.strictEqual(fs.readFileSync(realPath, 'utf8'), 'fake addon bytes');
+
+  // A path outside the mount is left for the caller to handle unchanged.
+  assert.strictEqual(resolveAddonRealPath(path.join(tmpdir.path, 'elsewhere.node')), null);
+
+  vfs.unmount();
+}
+
+// -- archive-backed: extracts to a content-hashed temp file ----------------
+
+(async () => {
+  const dir = path.join(tmpdir.path, 'zip-mount');
+  fs.mkdirSync(dir, { recursive: true });
+  const zipPath = path.join(dir, 'app.zip');
+  const content = Buffer.from('fake addon bytes from zip');
+  const entry = await zlib.ZipEntry.create('addon.node', content, { method: 'store' });
+  const chunks = [];
+  for await (const chunk of zlib.createZipArchive([entry])) chunks.push(chunk);
+  fs.writeFileSync(zipPath, Buffer.concat(chunks));
+
+  const zipFile = await zlib.ZipFile.open(zipPath);
+  const provider = new ZipProvider(zipFile);
+  const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
+  vfs.mount(zipPath);
+
+  const vfsPath = path.join(zipPath, 'addon.node');
+  const realPath = resolveAddonRealPath(vfsPath);
+
+  const expectedHash = crypto.createHash('sha256').update(content).digest('hex');
+  assert.strictEqual(path.basename(realPath), `${expectedHash}.node`);
+  assert.strictEqual(fs.readFileSync(realPath, 'utf8'), 'fake addon bytes from zip');
+
+  // Resolving the same content again reuses the same extracted file.
+  assert.strictEqual(resolveAddonRealPath(vfsPath), realPath);
+
+  vfs.unmount();
+  await zipFile.close();
+})().then(common.mustCall());
diff --git a/test/parallel/test-vfs-cli-flag-custom-provider.js b/test/parallel/test-vfs-cli-flag-custom-provider.js
new file mode 100644
index 000000000000..f75ea251e552
--- /dev/null
+++ b/test/parallel/test-vfs-cli-flag-custom-provider.js
@@ -0,0 +1,201 @@
+'use strict';
+
+// Exercises custom --vfs-mount providers registered via node:vfs's
+// registerProvider(), from a `-r` (CJS) or `--import` (ESM) preload, end to
+// end:
+//   1. a preloaded custom provider backs a --vfs-mount of its own file format,
+//   2. the built-in ZIP provider recognizes a ZIP by its bytes even when the
+//      file is not named `.zip` (byte sniffing, not extension),
+//   3. a custom provider is always tried before the built-in providers, so it
+//      can claim (or vet) a file the built-in would otherwise handle,
+//   4. a file no provider claims fails with a clear error,
+//   5. a custom provider can claim a *directory*, overriding the built-in
+//      RealFSProvider (the mechanism a read-recording provider would use), and
+//   6. a provider registered from an --import (ESM) preload backs a --vfs-load
+//      entry - i.e. mounting and entry resolution are deferred past --import.
+
+const common = require('../common');
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const { pathToFileURL } = require('url');
+const { spawnSync } = require('child_process');
+
+tmpdir.refresh();
+let fixtureId = 0;
+function fixturePath(name) {
+  return path.join(tmpdir.path, `${fixtureId++}-${name}`);
+}
+
+async function zipFromTree(files, dest) {
+  const entries = [];
+  for (const { 0: name, 1: content } of Object.entries(files)) {
+    entries.push(await zlib.ZipEntry.create(name, Buffer.from(content)));
+  }
+  const chunks = [];
+  for await (const chunk of zlib.createZipArchive(entries)) chunks.push(chunk);
+  fs.writeFileSync(dest, Buffer.concat(chunks));
+}
+
+// A CJS preload that registers a provider for a toy "CUSTOMFMT" file format:
+// the magic bytes followed by the JS source that becomes the mount's index.js.
+const customProviderModule = fixturePath('custom-provider.js');
+fs.writeFileSync(customProviderModule, `
+'use strict';
+const fs = require('fs');
+const vfs = require('node:vfs');
+const MAGIC = Buffer.from('CUSTOMFMT');
+
+vfs.registerProvider({
+  name: 'customfmt',
+  canHandle(resolvedPath, stats) {
+    if (!stats.isFile()) return false;
+    const fd = fs.openSync(resolvedPath, 'r');
+    try {
+      const buf = Buffer.alloc(MAGIC.length);
+      fs.readSync(fd, buf, 0, MAGIC.length, 0);
+      return buf.equals(MAGIC);
+    } finally {
+      fs.closeSync(fd);
+    }
+  },
+  create(resolvedPath) {
+    const body = fs.readFileSync(resolvedPath).subarray(MAGIC.length).toString('utf8');
+    const provider = new vfs.MemoryProvider();
+    provider.writeFileSync('/index.js', body);
+    return provider;
+  },
+});
+`);
+
+// A CJS preload whose provider claims *every* source - used to prove custom
+// providers win over the built-ins even for a real ZIP.
+const greedyProviderModule = fixturePath('greedy-provider.js');
+fs.writeFileSync(greedyProviderModule, `
+'use strict';
+const vfs = require('node:vfs');
+vfs.registerProvider({
+  name: 'greedy',
+  canHandle() { return true; },
+  create() {
+    const provider = new vfs.MemoryProvider();
+    provider.writeFileSync('/index.js', "console.log('greedy provider won');");
+    return provider;
+  },
+});
+`);
+
+// A CJS preload whose provider claims *directories*, overriding RealFSProvider.
+const dirProviderModule = fixturePath('dir-provider.js');
+fs.writeFileSync(dirProviderModule, `
+'use strict';
+const vfs = require('node:vfs');
+vfs.registerProvider({
+  name: 'dir-override',
+  canHandle(resolvedPath, stats) { return stats.isDirectory(); },
+  create() {
+    const provider = new vfs.MemoryProvider();
+    provider.writeFileSync('/index.js', "console.log('custom dir provider won');");
+    return provider;
+  },
+});
+`);
+
+// An ESM preload (loaded via --import) that registers a provider serving an
+// entry point. --import providers back a --vfs-load entry as well as data
+// mounts: mounting - and, for --vfs-load, entry resolution - is deferred until
+// after --import runs.
+const esmProviderModule = fixturePath('esm-provider.mjs');
+fs.writeFileSync(esmProviderModule, `
+import vfs from 'node:vfs';
+vfs.registerProvider({
+  name: 'esmfmt',
+  canHandle(resolvedPath, stats) {
+    return stats.isFile() && resolvedPath.endsWith('.esmfmt');
+  },
+  create() {
+    const provider = new vfs.MemoryProvider();
+    provider.writeFileSync('/index.js', "console.log('esm provider won');");
+    return provider;
+  },
+});
+`);
+
+function run(args) {
+  return spawnSync(
+    process.execPath,
+    ['--experimental-vfs', ...args],
+    { encoding: 'utf8' },
+  );
+}
+
+(async () => {
+  // 1. A preloaded custom provider backs a --vfs-mount of its own format.
+  {
+    const target = fixturePath('app.customfmt');
+    fs.writeFileSync(target, Buffer.concat([
+      Buffer.from('CUSTOMFMT'),
+      Buffer.from("console.log('hello from custom provider');"),
+    ]));
+    const res = run(['-r', customProviderModule, '--vfs-load', `--vfs-mount=${target}`]);
+    assert.strictEqual(res.status, 0, res.stderr);
+    assert.match(res.stdout, /hello from custom provider/);
+  }
+
+  // 2. The built-in ZIP provider recognizes a ZIP by its bytes, not its name:
+  //    a real ZIP archive named `.bundle` still mounts and runs.
+  {
+    const target = fixturePath('app.bundle');
+    await zipFromTree({ 'index.js': "console.log('hello from bundled zip');" }, target);
+    const res = run(['--vfs-load', `--vfs-mount=${target}`]);
+    assert.strictEqual(res.status, 0, res.stderr);
+    assert.match(res.stdout, /hello from bundled zip/);
+  }
+
+  // 3. A custom provider is tried before the built-ins: given a real ZIP, the
+  //    greedy custom provider still wins.
+  {
+    const target = fixturePath('real.zip');
+    await zipFromTree({ 'index.js': "console.log('built-in zip ran');" }, target);
+    const res = run(['-r', greedyProviderModule, '--vfs-load', `--vfs-mount=${target}`]);
+    assert.strictEqual(res.status, 0, res.stderr);
+    assert.match(res.stdout, /greedy provider won/);
+    assert.doesNotMatch(res.stdout, /built-in zip ran/);
+  }
+
+  // 4. A file no provider claims (not a ZIP, no custom provider) is rejected.
+  {
+    const target = fixturePath('mystery.bin');
+    fs.writeFileSync(target, Buffer.from('not an archive of any known kind'));
+    const res = run([`--vfs-mount=${target}`]);
+    assert.notStrictEqual(res.status, 0);
+    assert.match(res.stderr, /ERR_VFS_INVALID_TARGET/);
+  }
+
+  // 5. A custom provider can claim a directory, overriding RealFSProvider.
+  {
+    const dir = fixturePath('a-real-dir');
+    fs.mkdirSync(dir);
+    fs.writeFileSync(path.join(dir, 'index.js'), "console.log('real dir ran');");
+    const res = run(['-r', dirProviderModule, '--vfs-load', `--vfs-mount=${dir}`]);
+    assert.strictEqual(res.status, 0, res.stderr);
+    assert.match(res.stdout, /custom dir provider won/);
+    assert.doesNotMatch(res.stdout, /real dir ran/);
+  }
+
+  // 6. A provider registered from an --import (ESM) preload backs a --vfs-load
+  //    entry: both mounting and entry resolution are deferred until after
+  //    --import has run.
+  {
+    const target = fixturePath('app.esmfmt');
+    fs.writeFileSync(target, 'ignored by the provider');
+    const res = run([
+      '--import', pathToFileURL(esmProviderModule).href,
+      '--vfs-load', `--vfs-mount=${target}`,
+    ]);
+    assert.strictEqual(res.status, 0, res.stderr);
+    assert.match(res.stdout, /esm provider won/);
+  }
+})().then(common.mustCall());
diff --git a/test/parallel/test-vfs-cli-flag.js b/test/parallel/test-vfs-cli-flag.js
new file mode 100644
index 000000000000..301c41bc131b
--- /dev/null
+++ b/test/parallel/test-vfs-cli-flag.js
@@ -0,0 +1,212 @@
+'use strict';
+
+// Exercises the --vfs-mount / --vfs-load startup flags end to end, by actually
+// spawning `node --vfs-load --vfs-mount=<fixture>` against small CJS/ESM
+// fixture trees and ZIP archives built at test time: entry-point resolution,
+// package.json "type"/main-field/node_modules resolution happening entirely
+// inside the mount, the mount being scoped to its own target (not the whole
+// real filesystem), worker_threads inheriting the mount, and a clear error for
+// an invalid target.
+//
+// With --vfs-load, argv[1] is unconditionally the mount root - as with
+// `node <dir>` - so fixtures run via their own index.js / package.json
+// "main", and any positional arguments are the app's own (argv[2] onward),
+// never an entry-file override.
+
+const common = require('../common');
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const { spawnSync } = require('child_process');
+
+tmpdir.refresh();
+let fixtureId = 0;
+function nextDir(name) {
+  const dir = path.join(tmpdir.path, `${fixtureId++}-${name}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writeTree(dir, files) {
+  for (const { 0: name, 1: content } of Object.entries(files)) {
+    const filePath = path.join(dir, name);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+}
+
+async function zipFromTree(files, dest) {
+  const entries = [];
+  for (const { 0: name, 1: content } of Object.entries(files)) {
+    entries.push(await zlib.ZipEntry.create(name, Buffer.from(content)));
+  }
+  const chunks = [];
+  for await (const chunk of zlib.createZipArchive(entries)) chunks.push(chunk);
+  fs.writeFileSync(dest, Buffer.concat(chunks));
+}
+
+function runVfs(target, extraArgs = []) {
+  return spawnSync(
+    process.execPath,
+    ['--experimental-vfs', '--vfs-load', `--vfs-mount=${target}`, ...extraArgs],
+    { encoding: 'utf8' },
+  );
+}
+
+(async () => {
+  // -- Basic CJS entry: directory-backed and archive-backed -----------------
+  //
+  // No entry-file argument is ever passed: with --vfs active, argv[1] is
+  // unconditionally the mount root itself, so the mount's own index.js /
+  // package.json "main" decides what runs, exactly as `node <dir>` would.
+
+  const cjsFiles = {
+    'index.js': "console.log('hello from vfs cjs');",
+  };
+
+  {
+    const dir = nextDir('cjs-dir');
+    writeTree(dir, cjsFiles);
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'hello from vfs cjs');
+  }
+
+  {
+    const dir = nextDir('cjs-zip-src');
+    const zipPath = path.join(dir, 'app.zip');
+    await zipFromTree(cjsFiles, zipPath);
+    const result = runVfs(zipPath);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'hello from vfs cjs');
+  }
+
+  // -- Positional arguments are the app's own, passed straight through as -----
+  // -- argv[2] onward - never treated as an entry-point override. This is -----
+  // -- what lets a self-mounting shebang app                              -----
+  // -- (`#!/usr/bin/env -S node --vfs-load --vfs-mount`) take its own args. ---
+
+  {
+    const dir = nextDir('argv-passthrough');
+    writeTree(dir, {
+      'index.js': 'console.log(JSON.stringify(process.argv.slice(2)));',
+    });
+    const result = runVfs(dir, ['alpha', 'beta']);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.deepStrictEqual(JSON.parse(result.stdout.trim()), ['alpha', 'beta']);
+  }
+
+  // -- package.json "main" picks the entry file within the mount ------------
+
+  {
+    const dir = nextDir('main-field');
+    writeTree(dir, {
+      'package.json': JSON.stringify({ main: 'src/entry.js' }),
+      'src/entry.js': "console.log('ran package main');",
+    });
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'ran package main');
+  }
+
+  // -- ESM entry via package.json "type": "module" ---------------------------
+
+  {
+    const dir = nextDir('esm-dir');
+    writeTree(dir, {
+      'package.json': JSON.stringify({ type: 'module' }),
+      'index.js': "console.log('esm entry:', typeof import.meta.url);",
+    });
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'esm entry: string');
+  }
+
+  // -- Multi-file CJS app: relative require + node_modules resolution -------
+
+  {
+    const dir = nextDir('multi-file');
+    writeTree(dir, {
+      'index.js':
+        "const { greet } = require('./lib/helper.js');\n" +
+        "const pkg = require('mypkg');\n" +
+        "console.log(greet() + '-' + pkg.value);",
+      'lib/helper.js': "module.exports = { greet: () => 'hi' };",
+      'node_modules/mypkg/package.json': JSON.stringify({ name: 'mypkg', main: 'index.js' }),
+      'node_modules/mypkg/index.js': "module.exports = { value: 'pkg-value' };",
+    });
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'hi-pkg-value');
+  }
+
+  // -- Invalid target ---------------------------------------------------------
+
+  {
+    const missing = path.join(tmpdir.path, 'does-not-exist');
+    const result = runVfs(missing);
+    assert.notStrictEqual(result.status, 0);
+    assert.match(result.stderr, /ERR_VFS_INVALID_TARGET/);
+  }
+
+  // -- Sandbox is scoped to the mount, not the whole real filesystem ---------
+
+  {
+    const dir = nextDir('scoped-dir');
+    const outsideMarker = path.join(tmpdir.path, 'outside-marker.txt');
+    fs.writeFileSync(outsideMarker, 'real content outside the mount');
+    writeTree(dir, {
+      'index.js':
+        "const fs = require('fs');\n" +
+        `console.log(fs.readFileSync(${JSON.stringify(outsideMarker)}, 'utf8'));`,
+    });
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'real content outside the mount');
+  }
+
+  // -- worker_threads inherits the mount --------------------------------------
+  //
+  // The worker names its entry through `new Worker(__filename)`, resolved via
+  // the (VFS-aware) module loader - independent of the main thread's argv[1].
+
+  {
+    const dir = nextDir('worker-dir');
+    writeTree(dir, {
+      'marker.txt': 'inside the mount',
+      'index.js':
+        "const { Worker, isMainThread, parentPort } = require('worker_threads');\n" +
+        'if (isMainThread) {\n' +
+        '  const w = new Worker(__filename);\n' +
+        "  w.on('message', (msg) => { console.log(msg); });\n" +
+        '} else {\n' +
+        "  const fs = require('fs');\n" +
+        "  const path = require('path');\n" +
+        "  parentPort.postMessage(fs.readFileSync(path.join(__dirname, 'marker.txt'), 'utf8'));\n" +
+        '}',
+    });
+    const result = runVfs(dir);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert.strictEqual(result.stdout.trim(), 'inside the mount');
+  }
+
+  // -- --vfs-mount is gated behind --experimental-vfs -------------------------
+  //
+  // The startup flag is only allowed together with --experimental-vfs; without
+  // it, option validation rejects the invocation before anything runs.
+
+  {
+    const dir = nextDir('gated-dir');
+    writeTree(dir, { 'index.js': "console.log('should not run');" });
+    const result = spawnSync(
+      process.execPath,
+      [`--vfs-mount=${dir}`],
+      { encoding: 'utf8' },
+    );
+    assert.notStrictEqual(result.status, 0);
+    assert.match(result.stderr, /--vfs-mount requires --experimental-vfs/);
+    assert.strictEqual(result.stdout, '');
+  }
+})().then(common.mustCall());
diff --git a/test/parallel/test-vfs-mount-require.js b/test/parallel/test-vfs-mount-require.js
new file mode 100644
index 000000000000..b8a60fdd203d
--- /dev/null
+++ b/test/parallel/test-vfs-mount-require.js
@@ -0,0 +1,73 @@
+// Flags: --experimental-vfs
+'use strict';
+
+// Regression test: module resolution (require()/createRequire()) must work
+// through *any* mounted VFS - not just one mounted via the --vfs CLI flag.
+// internal/modules/vfs_resolution.js's native-bypass replacements
+// (internalModuleStat, package.json reading, legacyMainResolve, ...) look up
+// the active mount via internal/vfs/setup.js's general activeVFSList, the
+// same registry any vfs.mount() call - CLI-driven or plain userland code -
+// registers with. Before this, they only recognized the CLI's own mount,
+// so requiring a file out of a programmatically-mounted VFS (the pattern a
+// single-executable-application bootstrap script uses: mount an embedded
+// ZipBuffer, then createRequire() into it) would fail with MODULE_NOT_FOUND
+// even though plain fs.readFileSync() against the same path worked fine.
+
+const common = require('../common');
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const { createRequire } = require('module');
+const vfs = require('node:vfs');
+
+tmpdir.refresh();
+
+// -- archive-backed, mounted programmatically (no --vfs flag involved) ----
+
+(async () => {
+  const entries = [
+    await zlib.ZipEntry.create('app.js',
+                               Buffer.from("module.exports = require('./lib/helper.js').greet();")),
+    await zlib.ZipEntry.create('lib/helper.js',
+                               Buffer.from("module.exports = { greet: () => 'hi from zip' };")),
+  ];
+  const chunks = [];
+  for await (const chunk of zlib.createZipArchive(entries)) chunks.push(chunk);
+  const archive = Buffer.concat(chunks);
+
+  const zip = new zlib.ZipBuffer(archive);
+  const provider = new vfs.ZipProvider(zip);
+  const myVfs = vfs.create(provider);
+  myVfs.mount('/zip-app');
+
+  // Plain fs calls already worked before this fix; confirm they still do.
+  assert.strictEqual(fs.existsSync('/zip-app/app.js'), true);
+
+  // The actual regression: require() through the same mount.
+  const result = createRequire('/zip-app/_.js')('./app.js');
+  assert.strictEqual(result, 'hi from zip');
+
+  myVfs.unmount();
+})().then(common.mustCall());
+
+// -- directory-backed, mounted programmatically ----------------------------
+
+{
+  const dir = path.join(tmpdir.path, 'dir-app');
+  fs.mkdirSync(path.join(dir, 'lib'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'app.js'),
+                   "module.exports = require('./lib/helper.js').greet();");
+  fs.writeFileSync(path.join(dir, 'lib', 'helper.js'),
+                   "module.exports = { greet: () => 'hi from dir' };");
+
+  const provider = new vfs.RealFSProvider(dir);
+  const myVfs = vfs.create(provider);
+  myVfs.mount('/dir-app');
+
+  const result = createRequire('/dir-app/_.js')('./app.js');
+  assert.strictEqual(result, 'hi from dir');
+
+  myVfs.unmount();
+}