@napi-rs/cli 3.10.0 → 3.10.1

package/docs/wasi.md

@@ -336,6 +336,23 @@ Consumers that need deterministic cleanup before process exit should use the
 deferred loader and call its `dispose()` function, or the `dispose` returned by
 `createInstance()`.
 
+Every termination goes through the emnapi thread manager
+(`PThread.terminateWorker`) rather than a bare `worker.terminate()`. The manager
+counts a worker exit as expected only for terminations it performed itself and
+reports any other one as a worker failure — a throw that lands inside Node.js's
+`exit` emit and strands the promise the termination depends on. The manager is
+captured while the emnapi module is being created, before the wasm is loaded, so
+it is reachable even from the initialization rollback — the one path where
+instantiation never returned.
+
+Disposal holds the event loop open with a timer of its own until the
+terminations settle, so `await dispose()` resolves even as the last statement of
+a script. The pool workers cannot do that themselves: they are unreferenced so
+an idle binding never keeps a process alive, and emnapi unreferences them again
+whenever one reports that its thread is ready. The timer is released the moment
+the terminations settle, and a binding that is never disposed still does not
+hold an idle process open.
+
 When type generation is disabled, the generated browser root exposes the
 binding as its default export. `napi new` also removes the template's
 `index.d.ts` and declaration metadata instead of publishing stale template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/cli",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "description": "Cli tools for napi-rs",
   "author": "LongYinan <lynweklm@gmail.com>",
   "homepage": "https://napi.rs/",

package/src/api/__tests__/__snapshots__/templates.spec.ts.md

@@ -101,6 +101,35 @@ Generated by [AVA](https://avajs.dev).
     ␊
     const __wasiDisposeSymbol = Symbol.for('napi.rs.wasi.dispose')␊
     const __wasiWorkers = new Set()␊
+    // The thread manager has to be reachable *before* anything that can throw␊
+    // during load or registration. Initialization can fail after the pool has␊
+    // already spawned workers, and the rollback still has to mark their␊
+    // terminations as expected — but \`__napiModule\` is assigned only when␊
+    // instantiation RETURNS, so on exactly that path it is still undefined. A␊
+    // plugin factory runs while the emnapi module is being created, before the␊
+    // wasm is loaded and before any registration function runs, and its context␊
+    // carries the very same manager instance.␊
+    let __wasiThreadManager␊
+    ␊
+    function __captureWasiThreadManager(context) {␊
+      if (context && context.PThread) {␊
+        __wasiThreadManager = context.PThread␊
+      }␊
+      return {}␊
+    }␊
+    ␊
+    function __getWasiThreadManager() {␊
+      const manager =␊
+        __wasiThreadManager !== undefined␊
+          ? __wasiThreadManager␊
+          : __napiModule␊
+            ? __napiModule.PThread␊
+            : undefined␊
+      if (manager && typeof manager.terminateWorker === 'function') {␊
+        return manager␊
+      }␊
+      return undefined␊
+    }␊
     let __napiInstance␊
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
@@ -423,13 +452,80 @@ Generated by [AVA](https://avajs.dev).
       return destroyPromise␊
     }␊
     ␊
+    /**␊
+     * Holds the event loop open until \`work\` settles.␊
+     *␊
+     * Nothing else can: the pool workers are deliberately unreferenced so an idle␊
+     * binding cannot keep a process alive, and referencing them again for the␊
+     * termination does not hold either — emnapi unreferences a worker the moment it␊
+     * reports \`async-thread-ready\`, which for a worker that was still starting␊
+     * lands *after* the termination began. Without a handle of its own, an␊
+     * \`await dispose()\` with nothing else pending exits the process with its␊
+     * promise unsettled, and everything after the \`await\` is skipped.␊
+     *␊
+     * The timer is cleared as soon as the work settles, so this never outlives the␊
+     * disposal that asked for it.␊
+     */␊
+    function __keepEventLoopAliveUntil(work) {␊
+      const setTimer = globalThis.setInterval␊
+      const clearTimer = globalThis.clearInterval␊
+      if (typeof setTimer !== 'function' || typeof clearTimer !== 'function') {␊
+        return work␊
+      }␊
+      let timer␊
+      try {␊
+        timer = setTimer(function () {}, 50)␊
+      } catch {␊
+        return work␊
+      }␊
+      const release = function () {␊
+        try {␊
+          clearTimer(timer)␊
+        } catch {}␊
+      }␊
+      return work.then(␊
+        (value) => {␊
+          release()␊
+          return value␊
+        },␊
+        (error) => {␊
+          release()␊
+          throw error␊
+        },␊
+      )␊
+    }␊
+    ␊
+    /**␊
+     * \`@emnapi/wasi-threads\` counts a worker exit as expected only when its own␊
+     * thread manager performed the termination. A bare \`worker.terminate()\` reaches␊
+     * the manager's \`exit\` listener instead, which reports␊
+     * \`worker (tid = N) sent an error! ... stopped with exit code 1\` and rethrows␊
+     * inside the emit — aborting the \`once('exit')\` that backs the terminate␊
+     * promise, so disposal never settles and the process dies with an uncaught␊
+     * exception. Mark the termination through the manager first.␊
+     *␊
+     * The manager comes from \`__getWasiThreadManager\`, not from \`__napiModule\`:␊
+     * the initialization rollback runs on the one path where instantiation never␊
+     * returned, so \`__napiModule\` is still undefined there while the workers it␊
+     * spawned are already registered and loaded.␊
+     *␊
+     * Not \`terminateAllThreads()\`: that one recreates the pool it just shut down.␊
+     */␊
     function __terminateWasiWorkers() {␊
       const cleanupErrors = []␊
       const pending = []␊
+      const threadManager = __getWasiThreadManager()␊
     ␊
       for (const worker of __wasiWorkers) {␊
         let result␊
         try {␊
+          if (threadManager) {␊
+            threadManager.terminateWorker(worker)␊
+            // \`terminateWorker\` leaves behind a reporter that logs every message␊
+            // still queued on the port, which Node flushes on exit. Nothing is␊
+            // listening for those any more.␊
+            worker.onmessage = undefined␊
+          }␊
           result = worker.terminate()␊
         } catch (error) {␊
           cleanupErrors.push(error)␊
@@ -459,7 +555,9 @@ Generated by [AVA](https://avajs.dev).
           )␊
         }␊
       }␊
-      return pending.length > 0 ? Promise.all(pending).then(finish) : finish()␊
+      return pending.length > 0␊
+        ? __keepEventLoopAliveUntil(Promise.all(pending)).then(finish)␊
+        : finish()␊
     }␊
     ␊
     function __finishWasiDisposal() {␊
@@ -675,7 +773,7 @@ Generated by [AVA](https://avajs.dev).
         context: __emnapiContext,␊
         asyncWorkPoolSize: __asyncWorkPoolSize,␊
         reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
-        plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
+        plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊
           const worker = new Worker(new URL('./wasi-worker-browser.mjs', import.meta.url), {␊
@@ -814,6 +912,35 @@ Generated by [AVA](https://avajs.dev).
     ␊
     const __wasiDisposeSymbol = Symbol.for('napi.rs.wasi.dispose')␊
     const __wasiWorkers = new Set()␊
+    // The thread manager has to be reachable *before* anything that can throw␊
+    // during load or registration. Initialization can fail after the pool has␊
+    // already spawned workers, and the rollback still has to mark their␊
+    // terminations as expected — but \`__napiModule\` is assigned only when␊
+    // instantiation RETURNS, so on exactly that path it is still undefined. A␊
+    // plugin factory runs while the emnapi module is being created, before the␊
+    // wasm is loaded and before any registration function runs, and its context␊
+    // carries the very same manager instance.␊
+    let __wasiThreadManager␊
+    ␊
+    function __captureWasiThreadManager(context) {␊
+      if (context && context.PThread) {␊
+        __wasiThreadManager = context.PThread␊
+      }␊
+      return {}␊
+    }␊
+    ␊
+    function __getWasiThreadManager() {␊
+      const manager =␊
+        __wasiThreadManager !== undefined␊
+          ? __wasiThreadManager␊
+          : __napiModule␊
+            ? __napiModule.PThread␊
+            : undefined␊
+      if (manager && typeof manager.terminateWorker === 'function') {␊
+        return manager␊
+      }␊
+      return undefined␊
+    }␊
     let __napiInstance␊
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
@@ -1136,13 +1263,80 @@ Generated by [AVA](https://avajs.dev).
       return destroyPromise␊
     }␊
     ␊
+    /**␊
+     * Holds the event loop open until \`work\` settles.␊
+     *␊
+     * Nothing else can: the pool workers are deliberately unreferenced so an idle␊
+     * binding cannot keep a process alive, and referencing them again for the␊
+     * termination does not hold either — emnapi unreferences a worker the moment it␊
+     * reports \`async-thread-ready\`, which for a worker that was still starting␊
+     * lands *after* the termination began. Without a handle of its own, an␊
+     * \`await dispose()\` with nothing else pending exits the process with its␊
+     * promise unsettled, and everything after the \`await\` is skipped.␊
+     *␊
+     * The timer is cleared as soon as the work settles, so this never outlives the␊
+     * disposal that asked for it.␊
+     */␊
+    function __keepEventLoopAliveUntil(work) {␊
+      const setTimer = globalThis.setInterval␊
+      const clearTimer = globalThis.clearInterval␊
+      if (typeof setTimer !== 'function' || typeof clearTimer !== 'function') {␊
+        return work␊
+      }␊
+      let timer␊
+      try {␊
+        timer = setTimer(function () {}, 50)␊
+      } catch {␊
+        return work␊
+      }␊
+      const release = function () {␊
+        try {␊
+          clearTimer(timer)␊
+        } catch {}␊
+      }␊
+      return work.then(␊
+        (value) => {␊
+          release()␊
+          return value␊
+        },␊
+        (error) => {␊
+          release()␊
+          throw error␊
+        },␊
+      )␊
+    }␊
+    ␊
+    /**␊
+     * \`@emnapi/wasi-threads\` counts a worker exit as expected only when its own␊
+     * thread manager performed the termination. A bare \`worker.terminate()\` reaches␊
+     * the manager's \`exit\` listener instead, which reports␊
+     * \`worker (tid = N) sent an error! ... stopped with exit code 1\` and rethrows␊
+     * inside the emit — aborting the \`once('exit')\` that backs the terminate␊
+     * promise, so disposal never settles and the process dies with an uncaught␊
+     * exception. Mark the termination through the manager first.␊
+     *␊
+     * The manager comes from \`__getWasiThreadManager\`, not from \`__napiModule\`:␊
+     * the initialization rollback runs on the one path where instantiation never␊
+     * returned, so \`__napiModule\` is still undefined there while the workers it␊
+     * spawned are already registered and loaded.␊
+     *␊
+     * Not \`terminateAllThreads()\`: that one recreates the pool it just shut down.␊
+     */␊
     function __terminateWasiWorkers() {␊
       const cleanupErrors = []␊
       const pending = []␊
+      const threadManager = __getWasiThreadManager()␊
     ␊
       for (const worker of __wasiWorkers) {␊
         let result␊
         try {␊
+          if (threadManager) {␊
+            threadManager.terminateWorker(worker)␊
+            // \`terminateWorker\` leaves behind a reporter that logs every message␊
+            // still queued on the port, which Node flushes on exit. Nothing is␊
+            // listening for those any more.␊
+            worker.onmessage = undefined␊
+          }␊
           result = worker.terminate()␊
         } catch (error) {␊
           cleanupErrors.push(error)␊
@@ -1172,7 +1366,9 @@ Generated by [AVA](https://avajs.dev).
           )␊
         }␊
       }␊
-      return pending.length > 0 ? Promise.all(pending).then(finish) : finish()␊
+      return pending.length > 0␊
+        ? __keepEventLoopAliveUntil(Promise.all(pending)).then(finish)␊
+        : finish()␊
     }␊
     ␊
     function __finishWasiDisposal() {␊
@@ -1388,7 +1584,7 @@ Generated by [AVA](https://avajs.dev).
         context: __emnapiContext,␊
         asyncWorkPoolSize: __asyncWorkPoolSize,␊
         reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
-        plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
+        plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊
           const worker = new Worker(new URL('./wasi-worker-browser.mjs', import.meta.url), {␊
@@ -1546,6 +1742,35 @@ Generated by [AVA](https://avajs.dev).
     ␊
     const __wasiDisposeSymbol = Symbol.for('napi.rs.wasi.dispose')␊
     const __wasiWorkers = new Set()␊
+    // The thread manager has to be reachable *before* anything that can throw␊
+    // during load or registration. Initialization can fail after the pool has␊
+    // already spawned workers, and the rollback still has to mark their␊
+    // terminations as expected — but \`__napiModule\` is assigned only when␊
+    // instantiation RETURNS, so on exactly that path it is still undefined. A␊
+    // plugin factory runs while the emnapi module is being created, before the␊
+    // wasm is loaded and before any registration function runs, and its context␊
+    // carries the very same manager instance.␊
+    let __wasiThreadManager␊
+    ␊
+    function __captureWasiThreadManager(context) {␊
+      if (context && context.PThread) {␊
+        __wasiThreadManager = context.PThread␊
+      }␊
+      return {}␊
+    }␊
+    ␊
+    function __getWasiThreadManager() {␊
+      const manager =␊
+        __wasiThreadManager !== undefined␊
+          ? __wasiThreadManager␊
+          : __napiModule␊
+            ? __napiModule.PThread␊
+            : undefined␊
+      if (manager && typeof manager.terminateWorker === 'function') {␊
+        return manager␊
+      }␊
+      return undefined␊
+    }␊
     let __napiInstance␊
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
@@ -1868,13 +2093,80 @@ Generated by [AVA](https://avajs.dev).
       return destroyPromise␊
     }␊
     ␊
+    /**␊
+     * Holds the event loop open until \`work\` settles.␊
+     *␊
+     * Nothing else can: the pool workers are deliberately unreferenced so an idle␊
+     * binding cannot keep a process alive, and referencing them again for the␊
+     * termination does not hold either — emnapi unreferences a worker the moment it␊
+     * reports \`async-thread-ready\`, which for a worker that was still starting␊
+     * lands *after* the termination began. Without a handle of its own, an␊
+     * \`await dispose()\` with nothing else pending exits the process with its␊
+     * promise unsettled, and everything after the \`await\` is skipped.␊
+     *␊
+     * The timer is cleared as soon as the work settles, so this never outlives the␊
+     * disposal that asked for it.␊
+     */␊
+    function __keepEventLoopAliveUntil(work) {␊
+      const setTimer = globalThis.setInterval␊
+      const clearTimer = globalThis.clearInterval␊
+      if (typeof setTimer !== 'function' || typeof clearTimer !== 'function') {␊
+        return work␊
+      }␊
+      let timer␊
+      try {␊
+        timer = setTimer(function () {}, 50)␊
+      } catch {␊
+        return work␊
+      }␊
+      const release = function () {␊
+        try {␊
+          clearTimer(timer)␊
+        } catch {}␊
+      }␊
+      return work.then(␊
+        (value) => {␊
+          release()␊
+          return value␊
+        },␊
+        (error) => {␊
+          release()␊
+          throw error␊
+        },␊
+      )␊
+    }␊
+    ␊
+    /**␊
+     * \`@emnapi/wasi-threads\` counts a worker exit as expected only when its own␊
+     * thread manager performed the termination. A bare \`worker.terminate()\` reaches␊
+     * the manager's \`exit\` listener instead, which reports␊
+     * \`worker (tid = N) sent an error! ... stopped with exit code 1\` and rethrows␊
+     * inside the emit — aborting the \`once('exit')\` that backs the terminate␊
+     * promise, so disposal never settles and the process dies with an uncaught␊
+     * exception. Mark the termination through the manager first.␊
+     *␊
+     * The manager comes from \`__getWasiThreadManager\`, not from \`__napiModule\`:␊
+     * the initialization rollback runs on the one path where instantiation never␊
+     * returned, so \`__napiModule\` is still undefined there while the workers it␊
+     * spawned are already registered and loaded.␊
+     *␊
+     * Not \`terminateAllThreads()\`: that one recreates the pool it just shut down.␊
+     */␊
     function __terminateWasiWorkers() {␊
       const cleanupErrors = []␊
       const pending = []␊
+      const threadManager = __getWasiThreadManager()␊
     ␊
       for (const worker of __wasiWorkers) {␊
         let result␊
         try {␊
+          if (threadManager) {␊
+            threadManager.terminateWorker(worker)␊
+            // \`terminateWorker\` leaves behind a reporter that logs every message␊
+            // still queued on the port, which Node flushes on exit. Nothing is␊
+            // listening for those any more.␊
+            worker.onmessage = undefined␊
+          }␊
           result = worker.terminate()␊
         } catch (error) {␊
           cleanupErrors.push(error)␊
@@ -1904,7 +2196,9 @@ Generated by [AVA](https://avajs.dev).
           )␊
         }␊
       }␊
-      return pending.length > 0 ? Promise.all(pending).then(finish) : finish()␊
+      return pending.length > 0␊
+        ? __keepEventLoopAliveUntil(Promise.all(pending)).then(finish)␊
+        : finish()␊
     }␊
     ␊
     function __finishWasiDisposal() {␊
@@ -2120,7 +2414,7 @@ Generated by [AVA](https://avajs.dev).
         context: __emnapiContext,␊
         asyncWorkPoolSize: __asyncWorkPoolSize,␊
         reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
-        plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
+        plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊
           const worker = new Worker(new URL('./wasi-worker-browser.mjs', import.meta.url), {␊
@@ -2266,6 +2560,35 @@ Generated by [AVA](https://avajs.dev).
     ␊
     const __wasiDisposeSymbol = Symbol.for('napi.rs.wasi.dispose')␊
     const __wasiWorkers = new Set()␊
+    // The thread manager has to be reachable *before* anything that can throw␊
+    // during load or registration. Initialization can fail after the pool has␊
+    // already spawned workers, and the rollback still has to mark their␊
+    // terminations as expected — but \`__napiModule\` is assigned only when␊
+    // instantiation RETURNS, so on exactly that path it is still undefined. A␊
+    // plugin factory runs while the emnapi module is being created, before the␊
+    // wasm is loaded and before any registration function runs, and its context␊
+    // carries the very same manager instance.␊
+    let __wasiThreadManager␊
+    ␊
+    function __captureWasiThreadManager(context) {␊
+      if (context && context.PThread) {␊
+        __wasiThreadManager = context.PThread␊
+      }␊
+      return {}␊
+    }␊
+    ␊
+    function __getWasiThreadManager() {␊
+      const manager =␊
+        __wasiThreadManager !== undefined␊
+          ? __wasiThreadManager␊
+          : __napiModule␊
+            ? __napiModule.PThread␊
+            : undefined␊
+      if (manager && typeof manager.terminateWorker === 'function') {␊
+        return manager␊
+      }␊
+      return undefined␊
+    }␊
     let __napiInstance␊
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
@@ -2619,13 +2942,80 @@ Generated by [AVA](https://avajs.dev).
       return destroyPromise␊
     }␊
     ␊
+    /**␊
+     * Holds the event loop open until \`work\` settles.␊
+     *␊
+     * Nothing else can: the pool workers are deliberately unreferenced so an idle␊
+     * binding cannot keep a process alive, and referencing them again for the␊
+     * termination does not hold either — emnapi unreferences a worker the moment it␊
+     * reports \`async-thread-ready\`, which for a worker that was still starting␊
+     * lands *after* the termination began. Without a handle of its own, an␊
+     * \`await dispose()\` with nothing else pending exits the process with its␊
+     * promise unsettled, and everything after the \`await\` is skipped.␊
+     *␊
+     * The timer is cleared as soon as the work settles, so this never outlives the␊
+     * disposal that asked for it.␊
+     */␊
+    function __keepEventLoopAliveUntil(work) {␊
+      const setTimer = globalThis.setInterval␊
+      const clearTimer = globalThis.clearInterval␊
+      if (typeof setTimer !== 'function' || typeof clearTimer !== 'function') {␊
+        return work␊
+      }␊
+      let timer␊
+      try {␊
+        timer = setTimer(function () {}, 50)␊
+      } catch {␊
+        return work␊
+      }␊
+      const release = function () {␊
+        try {␊
+          clearTimer(timer)␊
+        } catch {}␊
+      }␊
+      return work.then(␊
+        (value) => {␊
+          release()␊
+          return value␊
+        },␊
+        (error) => {␊
+          release()␊
+          throw error␊
+        },␊
+      )␊
+    }␊
+    ␊
+    /**␊
+     * \`@emnapi/wasi-threads\` counts a worker exit as expected only when its own␊
+     * thread manager performed the termination. A bare \`worker.terminate()\` reaches␊
+     * the manager's \`exit\` listener instead, which reports␊
+     * \`worker (tid = N) sent an error! ... stopped with exit code 1\` and rethrows␊
+     * inside the emit — aborting the \`once('exit')\` that backs the terminate␊
+     * promise, so disposal never settles and the process dies with an uncaught␊
+     * exception. Mark the termination through the manager first.␊
+     *␊
+     * The manager comes from \`__getWasiThreadManager\`, not from \`__napiModule\`:␊
+     * the initialization rollback runs on the one path where instantiation never␊
+     * returned, so \`__napiModule\` is still undefined there while the workers it␊
+     * spawned are already registered and loaded.␊
+     *␊
+     * Not \`terminateAllThreads()\`: that one recreates the pool it just shut down.␊
+     */␊
     function __terminateWasiWorkers() {␊
       const cleanupErrors = []␊
       const pending = []␊
+      const threadManager = __getWasiThreadManager()␊
     ␊
       for (const worker of __wasiWorkers) {␊
         let result␊
         try {␊
+          if (threadManager) {␊
+            threadManager.terminateWorker(worker)␊
+            // \`terminateWorker\` leaves behind a reporter that logs every message␊
+            // still queued on the port, which Node flushes on exit. Nothing is␊
+            // listening for those any more.␊
+            worker.onmessage = undefined␊
+          }␊
           result = worker.terminate()␊
         } catch (error) {␊
           cleanupErrors.push(error)␊
@@ -2655,7 +3045,9 @@ Generated by [AVA](https://avajs.dev).
           )␊
         }␊
       }␊
-      return pending.length > 0 ? Promise.all(pending).then(finish) : finish()␊
+      return pending.length > 0␊
+        ? __keepEventLoopAliveUntil(Promise.all(pending)).then(finish)␊
+        : finish()␊
     }␊
     ␊
     function __finishWasiDisposal() {␊
@@ -2870,7 +3262,7 @@ Generated by [AVA](https://avajs.dev).
       } = __emnapiInstantiateNapiModuleSync(__wasmFile, {␊
         context: __emnapiContext,␊
         asyncWorkPoolSize: 0,␊
-        plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
+        plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         overwriteImports(importObject) {␊
           importObject.env = {␊

package/src/api/__tests__/templates.spec.ts

@@ -492,6 +492,111 @@ for (const { name, code, install } of asyncRuntimeLoaderCases) {
   })
 }
 
+// `@emnapi/wasi-threads` records a worker exit as expected only when ITS thread
+// manager performed the termination. A bare `worker.terminate()` reaches the
+// manager's own 'exit' listener, which reports the exit as a worker failure and
+// rethrows inside the emit — aborting the `once('exit')` that backs the
+// terminate promise, so `dispose()` never settles.
+for (const { name, code } of [
+  { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
+  { name: 'browser esm', code: createWasiBrowserBinding('test') },
+]) {
+  test(`pool workers are terminated through the thread manager: ${name}`, (t) => {
+    const start = code.indexOf('function __terminateWasiWorkers() {')
+    t.true(start > 0)
+    const body = code.slice(
+      start,
+      code.indexOf('function __finishWasiDisposal() {'),
+    )
+    const mark = body.indexOf('threadManager.terminateWorker(worker)')
+    const terminate = body.indexOf('result = worker.terminate()')
+    t.true(terminate > 0)
+    t.true(mark > 0, 'the termination has to be marked on the thread manager')
+    t.true(mark < terminate, 'and marked before the worker is terminated')
+    // Not `terminateAllThreads()`: it recreates the pool it just shut down.
+    t.false(body.includes('terminateAllThreads'))
+    // `terminateWorker` leaves a reporter behind that logs every message still
+    // queued on the port, which Node flushes on exit.
+    t.true(body.includes('worker.onmessage = undefined'))
+    // The manager is resolved through the helper, not read off `__napiModule`:
+    // the rollback runs on the one path where that binding was never assigned.
+    t.true(body.includes('const threadManager = __getWasiThreadManager()'))
+    t.false(body.includes('__napiModule.PThread'))
+  })
+}
+
+// The pool workers are unreferenced on purpose, and emnapi unreferences them
+// again when one reports `async-thread-ready`, so a pending termination has no
+// handle of its own to hold the loop open with.
+for (const { name, code } of [
+  { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
+  { name: 'browser esm', code: createWasiBrowserBinding('test') },
+]) {
+  test(`a pending termination holds the event loop open: ${name}`, (t) => {
+    const body = code.slice(
+      code.indexOf('function __terminateWasiWorkers() {'),
+      code.indexOf('function __finishWasiDisposal() {'),
+    )
+    t.true(
+      body.includes(
+        '__keepEventLoopAliveUntil(Promise.all(pending)).then(finish)',
+      ),
+      'the terminate promises have to be awaited under a keep-alive',
+    )
+    // …and the keep-alive is released the moment the work settles, so it can
+    // never outlive the disposal that asked for it.
+    const keepAlive = code.slice(
+      code.indexOf('function __keepEventLoopAliveUntil(work) {'),
+    )
+    t.true(keepAlive.indexOf('clearTimer(timer)') > 0)
+    t.true(keepAlive.indexOf('release()') < keepAlive.indexOf('return value'))
+    // Nothing puts the stubbed `ref` functions back: doing so is what raced
+    // emnapi's own unreference.
+    t.false(code.includes('__wasiWorkerRefRestorers'))
+    t.false(code.includes('__restoreWasiWorkerRef'))
+  })
+}
+
+test('the node loader keeps its pool workers unreferenced for life', (t) => {
+  const code = createWasiBinding('test', '@scope/test')
+  t.true(code.includes('worker[kPublicPort].ref = () => {}'))
+  t.true(code.includes('worker[kHandle].ref = () => {}'))
+  t.true(code.includes('worker.unref()'))
+  // An idle binding must not hold the process open, and disposal does not
+  // reverse that — `__keepEventLoopAliveUntil` covers the termination instead.
+  t.false(code.includes('.ref = publicPortRef'))
+  t.false(code.includes('.ref = handleRef'))
+})
+
+// `examples/custom-async-runtime` asserts a threadless loader never mentions
+// `Worker`, so nothing in the *shared* prelude may name the class — comments
+// included. That lane needs a wasm build to fail; this does not.
+for (const { name, code } of [
+  {
+    name: 'node cjs threadless',
+    code: createWasiBinding('test', '@scope/test', 4000, 65536, false),
+  },
+  {
+    name: 'browser esm threadless',
+    code: createWasiBrowserBinding(
+      'test',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      false,
+    ),
+  },
+  { name: 'deferred/workerd', code: createWasiDeferredBrowserBinding('test') },
+]) {
+  test(`threadless loaders never name Worker: ${name}`, (t) => {
+    t.notRegex(code, /\bWorker\b/)
+    t.notRegex(code, /node:worker_threads/)
+  })
+}
+
 test('asyncRuntime deferred loader registers per instance', (t) => {
   const code = asyncRuntimeDeferredCode
   assertValidJS(t, code, 'deferred asyncRuntime')