From ec4b4f5a642c06e1944baac223057091ddba2df1 Mon Sep 17 00:00:00 2001
From: Alessio Attilio <alessio.attilio@protonmail.com>
Date: Thu, 10 Sep 2026 13:14:20 +0200
Subject: [PATCH] vm: support shared microtask queues

Add `vm.MicrotaskQueue` and `options.microtaskQueue` to allow multiple
contexts to share an explicit V8 microtask queue and let users control
synchronous checkpoint draining.

Document how options.microtaskQueue and options.microtaskMode interact
across createContext, runInNewContext, and script.runInNewContext.
Update receiver type error expectation for runMicrotasks and add test
coverage for runInNewContext with microtask queues.

Fixes: https://github.com/nodejs/node/issues/65555
Signed-off-by: Alessio Attilio <alessio.attilio@protonmail.com>
Assisted-by: Antigravity
---
 doc/api/vm.md                                 |  97 +++++++++-
 lib/vm.js                                     |  36 +++-
 src/env_properties.h                          |   1 +
 src/node_contextify.cc                        |  98 ++++++++++-
 src/node_contextify.h                         |  36 +++-
 .../test-vm-shared-microtask-queue.js         | 165 ++++++++++++++++++
 6 files changed, 422 insertions(+), 11 deletions(-)
 create mode 100644 test/parallel/test-vm-shared-microtask-queue.js

diff --git a/doc/api/vm.md b/doc/api/vm.md
index 14cd1f269b12..0d74a4caba22 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -316,7 +316,19 @@ changes:
   * `microtaskMode` {string} If set to `afterEvaluate`, microtasks (tasks
     scheduled through `Promise`s and `async function`s) will be run immediately
     after the script has run. They are included in the `timeout` and
-    `breakOnSigint` scopes in that case.
+    `breakOnSigint` scopes in that case. If `microtaskQueue` (or
+    `contextMicrotaskQueue`) is also specified, evaluating the script will
+    drain that shared microtask queue (including any microtasks queued from
+    other contexts sharing the queue). If `microtaskQueue` is not specified, a
+    private microtask queue is created exclusively for this context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside the new context will be placed on
+    this queue. By default, microtasks placed on this queue are not
+    automatically drained when script evaluation finishes; they remain queued
+    until explicitly drained using [`microtaskQueue.runMicrotasks()`][], unless
+    `microtaskMode: 'afterEvaluate'` is also specified. An alias for this
+    option is `contextMicrotaskQueue`.
 * Returns: {any} the result of the very last statement executed in the script.
 
 This method is a shortcut to `script.runInContext(vm.createContext(options), options)`.
@@ -1318,6 +1330,37 @@ added:
 
 A `ModuleRequest` represents the request to import a module with given import attributes and phase.
 
+## Class: `vm.MicrotaskQueue`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Represents an explicit microtask queue that can be shared across multiple
+`vm.Context` instances and synchronously drained by the embedder.
+
+By default, passing a `vm.MicrotaskQueue` to [`vm.createContext()`][] attaches the
+context to that queue without automatically draining it after script evaluation;
+microtasks remain queued until explicitly drained using
+[`microtaskQueue.runMicrotasks()`][]. If automatic draining upon script completion
+is also desired, pass `microtaskMode: 'afterEvaluate'` alongside `microtaskQueue`.
+
+### `new vm.MicrotaskQueue()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Creates a new `vm.MicrotaskQueue` instance.
+
+### `microtaskQueue.runMicrotasks()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Synchronously runs all microtasks currently queued in this microtask queue.
+
 ## `vm.compileFunction(code[, params[, options]])`
 
 <!-- YAML
@@ -1474,6 +1517,19 @@ changes:
     scheduled through `Promise`s and `async function`s) will be run immediately
     after a script has run through [`script.runInContext()`][].
     They are included in the `timeout` and `breakOnSigint` scopes in that case.
+    If `microtaskQueue` is also specified, evaluating a script in this context
+    will drain that shared microtask queue (including any pending microtasks
+    scheduled by other contexts sharing the queue). If `microtaskQueue` is not
+    specified, a private microtask queue is created exclusively for this
+    context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside this context will be placed on this
+    queue, allowing multiple contexts to share the same microtask queue.
+    By default, microtasks placed on this queue are not automatically drained
+    when script evaluation finishes; they remain queued until explicitly drained
+    using [`microtaskQueue.runMicrotasks()`][], unless `microtaskMode: 'afterEvaluate'`
+    is also specified.
   * `importModuleDynamically`
     {Function|vm.constants.USE\_MAIN\_CONTEXT\_DEFAULT\_LOADER}
     Used to specify the how the modules should be loaded when `import()` is
@@ -1555,6 +1611,28 @@ Returns `true` if the given `object` object has been [contextified][] using
 [`vm.createContext()`][], or if it's the global object of a context created
 using [`vm.constants.DONT_CONTEXTIFY`][].
 
+## `vm.createMicrotaskQueue()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {vm.MicrotaskQueue}
+
+Creates a new [`vm.MicrotaskQueue`][] instance. Shortcut to
+`new vm.MicrotaskQueue()`.
+
+## `vm.isMicrotaskQueue(object)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `object` {any}
+* Returns: {boolean}
+
+Returns `true` if the given `object` is an instance of [`vm.MicrotaskQueue`][].
+
 ## `vm.measureMemory([options])`
 
 <!-- YAML
@@ -1822,7 +1900,18 @@ changes:
   * `microtaskMode` {string} If set to `afterEvaluate`, microtasks (tasks
     scheduled through `Promise`s and `async function`s) will be run immediately
     after the script has run. They are included in the `timeout` and
-    `breakOnSigint` scopes in that case.
+    `breakOnSigint` scopes in that case. If `microtaskQueue` is also specified,
+    evaluating the script will drain that shared microtask queue (including any
+    pending microtasks scheduled by other contexts sharing the queue). If
+    `microtaskQueue` is not specified, a private microtask queue is created
+    exclusively for this context.
+  * `microtaskQueue` {vm.MicrotaskQueue} A microtask queue created with
+    [`new vm.MicrotaskQueue()`][] or [`vm.createMicrotaskQueue()`][]. If
+    specified, microtasks scheduled inside the new context will be placed on
+    this queue. By default, microtasks placed on this queue are not
+    automatically drained when script evaluation finishes; they must be
+    explicitly drained using [`microtaskQueue.runMicrotasks()`][], unless
+    `microtaskMode: 'afterEvaluate'` is also specified.
 * Returns: {any} the result of the very last statement executed in the script.
 
 This method is a shortcut to
@@ -2577,6 +2666,8 @@ const { Script, SyntheticModule } = require('node:vm');
 [`Error`]: errors.md#class-error
 [`URL`]: url.md#class-url
 [`eval()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval
+[`microtaskQueue.runMicrotasks()`]: #microtaskqueuerunmicrotasks
+[`new vm.MicrotaskQueue()`]: #new-vmmicrotaskqueue
 [`optionsExpression`]: https://tc39.es/proposal-import-attributes/#sec-evaluate-import-call
 [`script.runInContext()`]: #scriptrunincontextcontextifiedobject-options
 [`script.runInThisContext()`]: #scriptruninthiscontextoptions
@@ -2584,9 +2675,11 @@ const { Script, SyntheticModule } = require('node:vm');
 [`sourceTextModule.linkRequests(modules)`]: #sourcetextmodulelinkrequestsmodules
 [`sourceTextModule.moduleRequests`]: #sourcetextmodulemodulerequests
 [`url.origin`]: url.md#urlorigin
+[`vm.MicrotaskQueue`]: #class-vmmicrotaskqueue
 [`vm.compileFunction()`]: #vmcompilefunctioncode-params-options
 [`vm.constants.DONT_CONTEXTIFY`]: #vmconstantsdont_contextify
 [`vm.createContext()`]: #vmcreatecontextcontextobject-options
+[`vm.createMicrotaskQueue()`]: #vmcreatemicrotaskqueue
 [`vm.runInContext()`]: #vmrunincontextcode-contextifiedobject-options
 [`vm.runInThisContext()`]: #vmruninthiscontextcode-options
 [contextified]: #what-does-it-mean-to-contextify-an-object
diff --git a/lib/vm.js b/lib/vm.js
index 2c7446af6076..76802533218e 100644
--- a/lib/vm.js
+++ b/lib/vm.js
@@ -32,6 +32,8 @@ const {
 
 const {
   ContextifyScript,
+  MicrotaskQueue: ContextifyMicrotaskQueue,
+  isMicrotaskQueue: _isMicrotaskQueue,
   makeContext,
   constants,
   measureMemory: _measureMemory,
@@ -82,6 +84,16 @@ function isContext(object) {
   return _isContext(object);
 }
 
+class MicrotaskQueue extends ContextifyMicrotaskQueue {}
+
+function createMicrotaskQueue() {
+  return new MicrotaskQueue();
+}
+
+function isMicrotaskQueue(object) {
+  return typeof object === 'object' && object !== null && _isMicrotaskQueue(object);
+}
+
 class Script extends ContextifyScript {
   constructor(code, options = kEmptyObject) {
     code = `${code}`;
@@ -202,6 +214,7 @@ function getContextOptions(options) {
     origin: options.contextOrigin,
     codeGeneration: undefined,
     microtaskMode: options.microtaskMode,
+    microtaskQueue: options.microtaskQueue ?? options.contextMicrotaskQueue,
   };
   if (contextOptions.name !== undefined)
     validateString(contextOptions.name, 'options.contextName');
@@ -235,6 +248,7 @@ function createContext(contextObject = { __proto__: ObjectPrototype }, options =
     origin,
     codeGeneration,
     microtaskMode,
+    microtaskQueue,
     importModuleDynamically,
   } = options;
 
@@ -255,12 +269,27 @@ function createContext(contextObject = { __proto__: ObjectPrototype }, options =
   validateOneOf(microtaskMode,
                 'options.microtaskMode',
                 ['afterEvaluate', undefined]);
-  const microtaskQueue = (microtaskMode === 'afterEvaluate');
+  if (microtaskQueue !== undefined && !isMicrotaskQueue(microtaskQueue)) {
+    throw new ERR_INVALID_ARG_TYPE(
+      'options.microtaskQueue',
+      'MicrotaskQueue',
+      microtaskQueue,
+    );
+  }
 
   const hostDefinedOptionId =
     getHostDefinedOptionId(importModuleDynamically, name);
 
-  const result = makeContext(contextObject, name, origin, strings, wasm, microtaskQueue, hostDefinedOptionId);
+  const result = makeContext(
+    contextObject,
+    name,
+    origin,
+    strings,
+    wasm,
+    microtaskQueue ?? (microtaskMode === 'afterEvaluate'),
+    hostDefinedOptionId,
+    microtaskMode === 'afterEvaluate',
+  );
   // Register the context scope callback after the context was initialized.
   registerImportModuleDynamically(result, importModuleDynamically);
   return result;
@@ -413,6 +442,9 @@ module.exports = {
   compileFunction,
   measureMemory,
   constants: vmConstants,
+  MicrotaskQueue,
+  createMicrotaskQueue,
+  isMicrotaskQueue,
 };
 
 // The vm module is patched to include vm.Module, vm.SourceTextModule
diff --git a/src/env_properties.h b/src/env_properties.h
index 886d4adba9fc..42fd55201f50 100644
--- a/src/env_properties.h
+++ b/src/env_properties.h
@@ -460,6 +460,7 @@
   V(lock_info_template, v8::DictionaryTemplate)                                \
   V(lock_query_template, v8::DictionaryTemplate)                               \
   V(message_port_constructor_template, v8::FunctionTemplate)                   \
+  V(microtask_queue_constructor_template, v8::FunctionTemplate)                \
   V(module_wrap_constructor_template, v8::FunctionTemplate)                    \
   V(mx_record_template, v8::DictionaryTemplate)                                \
   V(naptr_record_template, v8::DictionaryTemplate)                             \
diff --git a/src/node_contextify.cc b/src/node_contextify.cc
index 8f9dddf53cae..c2f925714717 100644
--- a/src/node_contextify.cc
+++ b/src/node_contextify.cc
@@ -153,10 +153,10 @@ ContextifyContext* ContextifyContext::New(Environment* env,
 
   const SnapshotData* snapshot_data = env->isolate_data()->snapshot_data();
 
-  MicrotaskQueue* queue =
-      options->own_microtask_queue
-          ? options->own_microtask_queue.get()
-          : env->isolate()->GetCurrentContext()->GetMicrotaskQueue();
+  MicrotaskQueue* queue = options->own_microtask_queue.get();
+  if (queue == nullptr) queue = options->shared_microtask_queue.get();
+  if (queue == nullptr)
+    queue = env->isolate()->GetCurrentContext()->GetMicrotaskQueue();
 
   Local<Context> v8_context;
   if (!(CreateV8Context(env->isolate(), object_template, snapshot_data, queue)
@@ -178,7 +178,9 @@ ContextifyContext::ContextifyContext(Environment* env,
                                      ContextOptions* options)
     : microtask_queue_(options->own_microtask_queue
                            ? options->own_microtask_queue.release()
-                           : nullptr) {
+                           : nullptr),
+      shared_microtask_queue_(std::move(options->shared_microtask_queue)),
+      drain_after_evaluate_(options->drain_after_evaluate) {
   CppgcMixin::Wrap(this, env, wrapper);
 
   context_.Reset(env->isolate(), v8_context);
@@ -414,7 +416,7 @@ void ContextifyContext::MakeContext(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   ContextOptions options;
 
-  CHECK_EQ(args.Length(), 7);
+  CHECK_GE(args.Length(), 7);
   Local<Object> sandbox;
   if (args[0]->IsObject()) {
     sandbox = args[0].As<Object>();
@@ -445,11 +447,20 @@ void ContextifyContext::MakeContext(const FunctionCallbackInfo<Value>& args) {
   if (args[5]->IsBoolean() && args[5]->BooleanValue(env->isolate())) {
     options.own_microtask_queue =
         MicrotaskQueue::New(env->isolate(), MicrotasksPolicy::kExplicit);
+    options.drain_after_evaluate = true;
+  } else if (args[5]->IsObject()) {
+    ContextifyMicrotaskQueue* queue;
+    ASSIGN_OR_RETURN_UNWRAP_CPPGC(&queue, args[5].As<Object>());
+    options.shared_microtask_queue = queue->microtask_queue();
   }
 
   CHECK(args[6]->IsSymbol());
   options.host_defined_options_id = args[6].As<Symbol>();
 
+  if (args.Length() > 7 && args[7]->IsBoolean()) {
+    options.drain_after_evaluate = args[7]->BooleanValue(env->isolate());
+  }
+
   TryCatchScope try_catch(env);
   ContextifyContext* context_ptr =
       ContextifyContext::New(env, sandbox, &options);
@@ -2027,6 +2038,79 @@ static void MeasureMemory(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(promise);
 }
 
+void ContextifyMicrotaskQueue::CreatePerIsolateProperties(
+    IsolateData* isolate_data, Local<ObjectTemplate> target) {
+  Isolate* isolate = isolate_data->isolate();
+  Local<String> class_name = FIXED_ONE_BYTE_STRING(isolate, "MicrotaskQueue");
+
+  Local<FunctionTemplate> tmpl = NewFunctionTemplate(isolate, New);
+  tmpl->InstanceTemplate()->SetInternalFieldCount(
+      ContextifyMicrotaskQueue::kInternalFieldCount);
+  tmpl->SetClassName(class_name);
+  SetProtoMethod(isolate, tmpl, "runMicrotasks", RunMicrotasks);
+
+  target->Set(isolate, "MicrotaskQueue", tmpl);
+  SetMethod(isolate, target, "isMicrotaskQueue", IsMicrotaskQueue);
+  isolate_data->set_microtask_queue_constructor_template(tmpl);
+}
+
+void ContextifyMicrotaskQueue::RegisterExternalReferences(
+    ExternalReferenceRegistry* registry) {
+  registry->Register(New);
+  registry->Register(RunMicrotasks);
+  registry->Register(IsMicrotaskQueue);
+}
+
+ContextifyMicrotaskQueue* ContextifyMicrotaskQueue::New(Environment* env,
+                                                        Local<Object> object) {
+  DCHECK_NOT_NULL(env->isolate()->GetCppHeap());
+  return cppgc::MakeGarbageCollected<ContextifyMicrotaskQueue>(
+      env->cppgc_allocation_handle(), env, object);
+}
+
+void ContextifyMicrotaskQueue::New(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  CHECK(args.IsConstructCall());
+  New(env, args.This());
+}
+
+ContextifyMicrotaskQueue::ContextifyMicrotaskQueue(Environment* env,
+                                                   Local<Object> object)
+    : microtask_queue_(
+          MicrotaskQueue::New(env->isolate(), MicrotasksPolicy::kExplicit)) {
+  CppgcMixin::Wrap(this, env, object);
+}
+
+bool ContextifyMicrotaskQueue::InstanceOf(Environment* env,
+                                          const Local<Value>& value) {
+  return !value.IsEmpty() && value->IsObject() &&
+         env->microtask_queue_constructor_template()->HasInstance(value);
+}
+
+void ContextifyMicrotaskQueue::RunMicrotasks(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  if (!ContextifyMicrotaskQueue::InstanceOf(env, args.This())) {
+    THROW_ERR_INVALID_THIS(env,
+                           "MicrotaskQueue methods can only be called on "
+                           "MicrotaskQueue instances.");
+    return;
+  }
+  ContextifyMicrotaskQueue* queue;
+  ASSIGN_OR_RETURN_UNWRAP_CPPGC(&queue, args.This());
+  queue->microtask_queue_->PerformCheckpoint(args.GetIsolate());
+}
+
+void ContextifyMicrotaskQueue::IsMicrotaskQueue(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  bool is_queue =
+      args.Length() > 0 && args[0]->IsObject() && InstanceOf(env, args[0]) &&
+      CppgcMixin::Unwrap<ContextifyMicrotaskQueue>(args[0].As<Object>()) !=
+          nullptr;
+  args.GetReturnValue().Set(is_queue);
+}
+
 void CreatePerIsolateProperties(IsolateData* isolate_data,
                                 Local<ObjectTemplate> target) {
   Isolate* isolate = isolate_data->isolate();
@@ -2034,6 +2118,7 @@ void CreatePerIsolateProperties(IsolateData* isolate_data,
   ContextifyContext::CreatePerIsolateProperties(isolate_data, target);
   ContextifyScript::CreatePerIsolateProperties(isolate_data, target);
   ContextifyFunction::CreatePerIsolateProperties(isolate_data, target);
+  ContextifyMicrotaskQueue::CreatePerIsolateProperties(isolate_data, target);
 
   SetMethod(isolate, target, "runInterruptible", RunInterruptible);
 
@@ -2083,6 +2168,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   ContextifyContext::RegisterExternalReferences(registry);
   ContextifyScript::RegisterExternalReferences(registry);
   ContextifyFunction::RegisterExternalReferences(registry);
+  ContextifyMicrotaskQueue::RegisterExternalReferences(registry);
 
   registry->Register(CompileFunctionForCJSLoader);
   registry->Register(RunInterruptible);
diff --git a/src/node_contextify.h b/src/node_contextify.h
index 1066633daf65..63fcc0dfecf1 100644
--- a/src/node_contextify.h
+++ b/src/node_contextify.h
@@ -19,6 +19,8 @@ struct ContextOptions {
   v8::Local<v8::Boolean> allow_code_gen_strings;
   v8::Local<v8::Boolean> allow_code_gen_wasm;
   std::unique_ptr<v8::MicrotaskQueue> own_microtask_queue;
+  std::shared_ptr<v8::MicrotaskQueue> shared_microtask_queue;
+  bool drain_after_evaluate = false;
   v8::Local<v8::Symbol> host_defined_options_id;
   bool vanilla = false;
 };
@@ -122,7 +124,9 @@ class ContextifyContext final : CPPGC_MIXIN(ContextifyContext) {
   }
 
   inline v8::MicrotaskQueue* microtask_queue() const {
-    return microtask_queue_.get();
+    if (!drain_after_evaluate_) return nullptr;
+    if (microtask_queue_) return microtask_queue_.get();
+    return shared_microtask_queue_.get();
   }
 
   template <typename T>
@@ -187,6 +191,36 @@ class ContextifyContext final : CPPGC_MIXIN(ContextifyContext) {
 
   v8::TracedReference<v8::Context> context_;
   std::unique_ptr<v8::MicrotaskQueue> microtask_queue_;
+  std::shared_ptr<v8::MicrotaskQueue> shared_microtask_queue_;
+  bool drain_after_evaluate_ = false;
+};
+
+class ContextifyMicrotaskQueue final : CPPGC_MIXIN(ContextifyMicrotaskQueue) {
+ public:
+  SET_CPPGC_NAME(ContextifyMicrotaskQueue)
+  DEFAULT_CPPGC_TRACE()
+  SET_NO_MEMORY_INFO()
+
+  ContextifyMicrotaskQueue(Environment* env, v8::Local<v8::Object> object);
+  ~ContextifyMicrotaskQueue() override = default;
+
+  static ContextifyMicrotaskQueue* New(Environment* env,
+                                       v8::Local<v8::Object> object);
+  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static bool InstanceOf(Environment* env, const v8::Local<v8::Value>& value);
+  static void RunMicrotasks(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void IsMicrotaskQueue(const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static void CreatePerIsolateProperties(IsolateData* isolate_data,
+                                         v8::Local<v8::ObjectTemplate> target);
+  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
+
+  inline std::shared_ptr<v8::MicrotaskQueue> microtask_queue() const {
+    return microtask_queue_;
+  }
+
+ private:
+  std::shared_ptr<v8::MicrotaskQueue> microtask_queue_;
 };
 
 class ContextifyScript final : CPPGC_MIXIN(ContextifyScript) {
diff --git a/test/parallel/test-vm-shared-microtask-queue.js b/test/parallel/test-vm-shared-microtask-queue.js
new file mode 100644
index 000000000000..eafe458cf66a
--- /dev/null
+++ b/test/parallel/test-vm-shared-microtask-queue.js
@@ -0,0 +1,165 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const vm = require('vm');
+
+// 1. Creation and type checking
+{
+  const queue1 = new vm.MicrotaskQueue();
+  const queue2 = vm.createMicrotaskQueue();
+
+  assert(vm.isMicrotaskQueue(queue1));
+  assert(vm.isMicrotaskQueue(queue2));
+  assert(queue1 instanceof vm.MicrotaskQueue);
+  assert(queue2 instanceof vm.MicrotaskQueue);
+
+  assert.strictEqual(vm.isMicrotaskQueue({}), false);
+  assert.strictEqual(vm.isMicrotaskQueue(null), false);
+  assert.strictEqual(vm.isMicrotaskQueue(undefined), false);
+  assert.strictEqual(vm.isMicrotaskQueue(42), false);
+  assert.strictEqual(vm.isMicrotaskQueue('queue'), false);
+
+  assert.throws(() => {
+    vm.MicrotaskQueue();
+  }, {
+    name: 'TypeError',
+    message: "Class constructor MicrotaskQueue cannot be invoked without 'new'",
+  });
+
+  assert.throws(() => {
+    queue1.runMicrotasks.call({});
+  }, {
+    name: 'TypeError',
+    message: 'Illegal invocation',
+  });
+}
+
+// 2. Options validation
+{
+  assert.throws(() => {
+    vm.createContext({}, { microtaskQueue: {} });
+  }, {
+    code: 'ERR_INVALID_ARG_TYPE',
+    name: 'TypeError',
+  });
+
+  assert.throws(() => {
+    vm.runInNewContext('1 + 1', {}, { microtaskQueue: 'invalid' });
+  }, {
+    code: 'ERR_INVALID_ARG_TYPE',
+    name: 'TypeError',
+  });
+}
+
+// 3. The exact issue #65555 HTML Window and same-agent iframe checkpoint model
+{
+  function run(options, drain = () => {}) {
+    const trace = [];
+    const record = (entry) => trace.push(entry);
+    const window = vm.createContext({ record }, options);
+    const iframe = vm.createContext({ record }, options);
+
+    vm.runInContext(`
+      const pending = new Promise((resolve) => {
+        globalThis.resolve = resolve;
+      });
+      pending.then(() => {
+        record('win-rxn');
+        Promise.resolve().then(() => record('win-follow-up'));
+      });
+    `, window);
+
+    vm.runInContext(`
+      const pending = new Promise((resolve) => {
+        globalThis.resolve = resolve;
+      });
+      pending.then(() => record('iframe-rxn'));
+    `, iframe);
+
+    window.resolveIframe = iframe.resolve;
+    vm.runInContext('resolve(); resolveIframe();', window);
+    drain(iframe);
+
+    return trace;
+  }
+
+  const expected = ['win-rxn', 'iframe-rxn', 'win-follow-up'];
+
+  // Default contexts share Node's queue, but have not drained before returning
+  assert.deepStrictEqual(run(), []);
+
+  // afterEvaluate gives every context a separate queue, draining Window prematurely
+  assert.deepStrictEqual(
+    run(
+      { microtaskMode: 'afterEvaluate' },
+      (iframe) => vm.runInContext('', iframe),
+    ),
+    ['win-rxn', 'win-follow-up', 'iframe-rxn'],
+  );
+
+  // Shared microtask queue achieves the HTML specification order
+  const queue = vm.createMicrotaskQueue();
+  assert.deepStrictEqual(
+    run(
+      { microtaskQueue: queue },
+      () => queue.runMicrotasks(),
+    ),
+    expected,
+  );
+}
+
+// 4. Shared microtask queue with microtaskMode: 'afterEvaluate'
+{
+  const queue = new vm.MicrotaskQueue();
+  const trace = [];
+  const record = (entry) => trace.push(entry);
+
+  const contextA = vm.createContext({ record }, {
+    microtaskQueue: queue,
+    microtaskMode: 'afterEvaluate',
+  });
+  const contextB = vm.createContext({ record }, {
+    microtaskQueue: queue,
+  });
+
+  vm.runInContext(`
+    Promise.resolve().then(() => record('A'));
+  `, contextA);
+
+  vm.runInContext(`
+    Promise.resolve().then(() => record('B'));
+  `, contextB);
+
+  // Context A has afterEvaluate, so evaluation drains the shared queue
+  assert.deepStrictEqual(trace, ['A']);
+
+  // Context B does not have afterEvaluate, so microtasks stay until explicitly drained
+  assert.deepStrictEqual(trace, ['A']);
+  queue.runMicrotasks();
+  assert.deepStrictEqual(trace, ['A', 'B']);
+}
+
+// 5. runInNewContext and script.runInNewContext support microtaskQueue
+{
+  const queue = new vm.MicrotaskQueue();
+  const trace = [];
+  const record = (entry) => trace.push(entry);
+
+  vm.runInNewContext(`
+    Promise.resolve().then(() => record('runInNewContext'));
+  `, { record }, { microtaskQueue: queue });
+
+  assert.deepStrictEqual(trace, []);
+  queue.runMicrotasks();
+  assert.deepStrictEqual(trace, ['runInNewContext']);
+
+  const script = new vm.Script(`
+    Promise.resolve().then(() => record('script.runInNewContext'));
+  `);
+  script.runInNewContext({ record }, { contextMicrotaskQueue: queue });
+
+  assert.deepStrictEqual(trace, ['runInNewContext']);
+  queue.runMicrotasks();
+  assert.deepStrictEqual(trace, ['runInNewContext', 'script.runInNewContext']);
+}