@napi-rs/cli 3.10.0 → 3.10.2

package/src/api/templates/load-wasi-template.ts

@@ -129,6 +129,35 @@ function __disposeCurrentThreadHosts() {
   return `
 const __wasiDisposeSymbol = Symbol.for('${WASI_DISPOSE_SYMBOL}')
 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
@@ -138,6 +167,7 @@ let __emnapiWasmEnvCleanupRan = false
 let __emnapiWasmEnvCleanupDrained = false
 let __emnapiWasmEnvCleanupDrainPromise
 let __wasiDisposed = false
+let __wasiAsyncWorkDrainPromise
 let __wasiDisposePromise
 let __completeWasiDisposal = function () {}
 // Overridden by loader flavors that have a last-resort reclaim for a rollback
@@ -262,6 +292,24 @@ const __scheduleMacrotask = (function () {
   }
 })()
 
+// A real, *referenced* timer, for waits that must let the whole host make
+// progress between looks — the async-work drain polls the addon rather than
+// interleaving with the @emnapi/core dispatch, so a zero-delay macrotask there
+// would spin the loop instead of yielding it. Falls back to the macrotask
+// scheduler on a host without timers.
+function __scheduleTimer(callback, delay) {
+  const setTimer = globalThis.setTimeout
+  if (typeof setTimer !== 'function') {
+    __scheduleMacrotask(callback)
+    return
+  }
+  try {
+    setTimer(callback, delay)
+  } catch {
+    __scheduleMacrotask(callback)
+  }
+}
+
 // Turns to wait for while the addon still reports queued settlements. Reaching
 // zero is the only success. A counter still nonzero at this bound rejects the
 // disposal as retryable (\`ERR_NAPI_WASI_CLEANUP_PENDING\`) rather than
@@ -419,13 +467,209 @@ ${disposeCurrentThreadHosts}\
   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
+    },
+  )
+}
+
+// How often to re-read \`napi_wasm_async_work_pending\` while waiting. The wait
+// ends when the addon reports zero, so this only decides how promptly disposal
+// notices — not how long it waits.
+const __WASI_ASYNC_WORK_POLL_INTERVAL_MS = 1
+
+/**
+ * Settles this addon's outstanding \`napi_async_work\` before the teardown that
+ * would strand it.
+ *
+ * \`napi_prepare_wasm_env_cleanup\` does not cover async work, and nothing about
+ * it is observable from JavaScript: the threadless archive resolves
+ * \`napi_*_async_work\` through the \`@emnapi/core\` plugins, but the threaded one
+ * links the C \`async_work.c\` on the uv threadpool, so there the wasm neither
+ * imports nor exports those symbols and the only brackets a loader could watch
+ * (\`_emnapi_ctx_*_waiting_request_counter\`) are shared with threadsafe
+ * functions. The addon is the one place both flavors go through, so it answers
+ * for both, through the same kind of handshake the settlement drain uses:
+ *
+ *   - \`napi_wasm_cancel_pending_async_work()\` cancels what no thread has
+ *     started. Those completion callbacks run with \`napi_cancelled\`, which
+ *     napi-rs turns into a promise rejected with an \`AbortError\`.
+ *   - \`napi_wasm_async_work_pending()\` counts what is still owed a completion
+ *     callback. Work already executing refuses cancellation and stays counted
+ *     until it finishes normally — which it can, because this runs before the
+ *     barrier, before \`Context.destroy()\` and before anything is terminated.
+ *
+ * Both exports are optional: an addon built against a napi crate that predates
+ * them drains nothing and keeps the previous behavior, exactly as the
+ * \`napi_wasm_env_cleanup_pending\` handshake degrades.
+ *
+ * Returns nothing when there is nothing outstanding, which keeps disposal
+ * synchronous in the common case. The promise it returns otherwise never
+ * rejects.
+ *
+ * The wait has no deadline, and that is the point: giving up would destroy the
+ * environment with a completion callback still owed, which is the stranding
+ * this exists to prevent. A task whose \`execute\` never returns already keeps an
+ * *undisposed* process alive in exactly the same way, so disposal inherits that
+ * rather than inventing a bound it cannot honor.
+ *
+ * Safe to call from inside a completion callback, which is reachable: settling
+ * a task runs addon code that can re-enter JavaScript — a setter on the value
+ * being handed back, a threadsafe-function callback — and that JavaScript can
+ * call \`dispose()\`. Two things make it terminate rather than wait on itself:
+ *
+ *   - The addon keeps a work registered until its completion callback
+ *     *finishes*, so the count read here is at least one and this takes the
+ *     polling path instead of declaring the environment drained and tearing it
+ *     down from inside the frame that is still settling a promise.
+ *   - The poll is a timer, so it cannot run until the callback has returned to
+ *     the host — by which time that work has left the registry. The count the
+ *     next poll reads is the one taken after the callback finished.
+ *
+ * \`__disposeWasiBinding\` hands every caller the same in-flight promise, so the
+ * nested call joins this disposal rather than starting a second one.
+ */
+function __drainWasiAsyncWork() {
+  if (__wasiAsyncWorkDrainPromise !== undefined) {
+    return __wasiAsyncWorkDrainPromise
+  }
+  const exports = __napiInstance?.exports
+  const pending = exports?.napi_wasm_async_work_pending
+  const cancelPending = exports?.napi_wasm_cancel_pending_async_work
+  if (typeof pending !== 'function' || typeof cancelPending !== 'function') {
+    return
+  }
+
+  const readPending = () => {
+    try {
+      return pending()
+    } catch (error) {
+      // A trap is the only way this call fails: it reads a counter and cannot
+      // allocate or call back into JavaScript. A trapped instance can no longer
+      // run anything, so its outstanding work is unreachable by definition —
+      // there is nothing left to wait for, and refusing to dispose would only
+      // keep a dead instance and its stuck counter alive. Best-effort here is
+      // the honest answer, and it is what disposal did before this drain
+      // existed.
+      //
+      // Only a trap. Anything else means the export is not what this loader
+      // thinks it is, which is a defect worth surfacing rather than disposing
+      // over.
+      if (error instanceof globalThis.WebAssembly.RuntimeError) {
+        return 0
+      }
+      throw error
+    }
+  }
+
+  if (!readPending()) {
+    return
+  }
+  try {
+    cancelPending()
+  } catch {
+    // Cancellation is an optimization: it bounds the wait by the work already
+    // executing. Failing it only means waiting for the whole queue instead.
+  }
+  if (!readPending()) {
+    return
+  }
+
+  const drainPromise = __keepEventLoopAliveUntil(
+    (async () => {
+      while (readPending()) {
+        await new Promise((resolve) => {
+          __scheduleTimer(resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)
+        })
+      }
+    })(),
+  ).then(
+    () => {
+      __wasiAsyncWorkDrainPromise = undefined
+    },
+    (error) => {
+      // A wait that could not run is not a wait that finished. The only way
+      // here is a host whose timers and macrotask primitives all refuse, and
+      // the work is still outstanding — reporting success would destroy the
+      // environment over it, which is the stranding this exists to prevent.
+      // Reject instead: disposal stays retryable, and the context is not
+      // destroyed. Clearing the memo first is what makes the retry re-run this.
+      __wasiAsyncWorkDrainPromise = undefined
+      throw error
+    },
+  )
+  __wasiAsyncWorkDrainPromise = drainPromise
+  return drainPromise
+}
+
+/**
+ * \`@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)
@@ -455,7 +699,9 @@ function __terminateWasiWorkers() {
       )
     }
   }
-  return pending.length > 0 ? Promise.all(pending).then(finish) : finish()
+  return pending.length > 0
+    ? __keepEventLoopAliveUntil(Promise.all(pending)).then(finish)
+    : finish()
 }
 
 function __finishWasiDisposal() {
@@ -474,7 +720,7 @@ function __continueWasiDisposal() {
   return __finishWasiDisposal()
 }
 
-function __startWasiDisposal() {
+function __cleanUpWasmEnvForWasiDisposal() {
   // Run the pre-teardown barrier, then let the settlements it queued actually
   // reach JavaScript, and only then destroy the environment. Doing these two
   // back to back is what strands them.
@@ -486,6 +732,21 @@ function __startWasiDisposal() {
   return __continueWasiDisposal()
 }
 
+function __startWasiDisposal() {
+  // Outstanding \`napi_async_work\` goes first, while the environment is still
+  // completely live: the completion callbacks run addon code, and everything
+  // after this point takes that away from them — the barrier shuts the async
+  // runtime down, \`Context.destroy()\` stops JavaScript calls, and terminating
+  // the pool threads removes what would have reported the work finished.
+  const asyncWorkResult = __drainWasiAsyncWork()
+  if (__isThenable(asyncWorkResult)) {
+    return Promise.resolve(asyncWorkResult).then(
+      __cleanUpWasmEnvForWasiDisposal,
+    )
+  }
+  return __cleanUpWasmEnvForWasiDisposal()
+}
+
 /**
  * Disposes this generated WASI binding.
  *
@@ -627,29 +888,60 @@ function __retainFailedWasiRollback(cleanupErrors) {
  * bug with no upper bound, while the retained bookkeeping is bounded by the page.
  */
 function __rollbackWasiInitialization() {
-  const cleanupErrors = []
-  let drainResult
-  let settlementsUnreached = false
+  // The environment teardown this rollback performs, kept nested so it cannot
+  // be reached without the async-work drain below running first.
+  function __rollbackWasmEnvForWasiInitialization() {
+    const cleanupErrors = []
+    let drainResult
+    let settlementsUnreached = false
+    try {
+      __prepareWasmEnvCleanup()
+      drainResult = __drainWasmEnvCleanup()
+    } catch (cleanupError) {
+      cleanupErrors.push(cleanupError)
+      settlementsUnreached = true
+    }
+    if (__isThenable(drainResult)) {
+      return Promise.resolve(drainResult).then(
+        () => __destroyContextForWasiRollback(cleanupErrors),
+        (cleanupError) => {
+          cleanupErrors.push(cleanupError)
+          return __retainFailedWasiRollback(cleanupErrors)
+        },
+      )
+    }
+    if (settlementsUnreached) {
+      return __retainFailedWasiRollback(cleanupErrors)
+    }
+    return __destroyContextForWasiRollback(cleanupErrors)
+  }
+
+  // Same reason as \`__startWasiDisposal\`: a module-init hook can start async
+  // work before the load goes on to fail, and this rollback tears down exactly
+  // what those completions need. Settle them while everything is still live,
+  // before the barrier and the teardown above take that away.
+  //
+  // A drain that could not finish leaves async work possibly outstanding, and
+  // destroying the context over it would strand exactly what this rollback is
+  // there to settle. Stop short and retain instead — the same trade
+  // \`__rollbackWasmEnvForWasiInitialization\` makes for the settlement drain, so
+  // the context stays reclaimable by a retry or by this flavor's own
+  // last-resort teardown.
+  const __retainAfterAsyncWorkDrainFailure = (cleanupError) =>
+    __retainFailedWasiRollback([cleanupError])
+  let asyncWorkResult
   try {
-    __prepareWasmEnvCleanup()
-    drainResult = __drainWasmEnvCleanup()
+    asyncWorkResult = __drainWasiAsyncWork()
   } catch (cleanupError) {
-    cleanupErrors.push(cleanupError)
-    settlementsUnreached = true
+    return __retainAfterAsyncWorkDrainFailure(cleanupError)
   }
-  if (__isThenable(drainResult)) {
-    return Promise.resolve(drainResult).then(
-      () => __destroyContextForWasiRollback(cleanupErrors),
-      (cleanupError) => {
-        cleanupErrors.push(cleanupError)
-        return __retainFailedWasiRollback(cleanupErrors)
-      },
+  if (__isThenable(asyncWorkResult)) {
+    return Promise.resolve(asyncWorkResult).then(
+      __rollbackWasmEnvForWasiInitialization,
+      __retainAfterAsyncWorkDrainFailure,
     )
   }
-  if (settlementsUnreached) {
-    return __retainFailedWasiRollback(cleanupErrors)
-  }
-  return __destroyContextForWasiRollback(cleanupErrors)
+  return __rollbackWasmEnvForWasiInitialization()
 }
 `
 }
@@ -777,14 +1069,27 @@ const __workerPoolSize = Math.max(
   const memoryName = threads ? '__sharedMemory' : '__wasmMemory'
   const asyncWorkPoolOption = `    asyncWorkPoolSize: ${threads ? '__asyncWorkPoolSize' : 0},
 `
-  // Every build links a "basic" emnapi archive without the C async-work and
-  // threadsafe-function implementations (the `emnapi-napi-rs(-mt)` archives shipped by the emnapi package), so the
-  // JavaScript implementations must be provided through the emnapi plugins in
-  // both threading modes. Without threads the C code would be unconditional
-  // `napi_generic_failure` stubs; with threads it would shadow the
-  // `@emnapi/core` threaded TSFN/async-work protocol the plugins implement.
+  // Which archive a build links decides who implements async work and
+  // threadsafe functions — see `emnapi_link_library` in
+  // `crates/build/src/wasi.rs`. Without threads it is `emnapi-basic-napi-rs`,
+  // the "basic" model: both stay wasm imports, and the `@emnapi/core`
+  // JavaScript plugins below are what resolves them; without the plugins
+  // instantiation fails with a LinkError naming the missing import. With
+  // threads it is `emnapi-napi-rs-mt`, the full composition, whose C
+  // `async_work.c` / `threadsafe_function.c` run on the uv threadpool inside
+  // the wasm — it imports none of those symbols, so the plugins are inert
+  // there. They are passed in both modes because only the archive knows which
+  // applies, and a plugin nothing imports costs nothing.
+  //
+  // This is why the async-work drain on the disposal path cannot live here:
+  // with threads there is no JavaScript seam at all, so `__drainWasiAsyncWork`
+  // asks the addon instead.
   const emnapiPluginImport = `  emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,\n  emnapiTSFNPlugin as __emnapiTSFNPlugin,\n`
-  const emnapiPluginOption = `    plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],\n`
+  const emnapiPluginOption = `    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],\n`
   const workerOption = threads
     ? `    onCreateWorker() {
       const worker = new Worker(new URL('./wasi-worker-browser.mjs', import.meta.url), {
@@ -1394,6 +1699,101 @@ function __drainWasmEnvCleanup(__instance) {
   })()
 }
 
+// A real, *referenced* timer for the async-work wait below, which polls the
+// addon rather than interleaving with the @emnapi/core dispatch: a zero-delay
+// macrotask there would spin the loop instead of yielding it. Falls back to the
+// macrotask scheduler on a host without timers.
+function __scheduleTimer(__callback, __delay) {
+  const __setTimer = globalThis.setTimeout
+  if (typeof __setTimer !== 'function') {
+    __scheduleMacrotask(__callback)
+    return
+  }
+  try {
+    __setTimer(__callback, __delay)
+  } catch {
+    __scheduleMacrotask(__callback)
+  }
+}
+
+// How often to re-read \`napi_wasm_async_work_pending\` while waiting. The wait
+// ends when the addon reports zero, so this only decides how promptly disposal
+// notices — not how long it waits.
+const __WASI_ASYNC_WORK_POLL_INTERVAL_MS = 1
+
+/**
+ * Settles this instance's outstanding \`napi_async_work\` before the teardown
+ * that would strand it.
+ *
+ * The same hole the eager loaders had, and the same fix: the environment
+ * cleanup barrier covers promise settlements queued on the threadsafe-function
+ * queue and says nothing about \`napi_async_work\`, so destroying the context
+ * with a work still outstanding leaves its completion callback with nowhere to
+ * run and its promise unsettled forever.
+ *
+ * This flavor is threadless, so \`compute\` runs on the JavaScript thread inside
+ * the macrotask that dequeued it: while this is running, any outstanding work
+ * is queued rather than executing, and \`napi_wasm_cancel_pending_async_work\`
+ * can take all of it. The poll is still what decides when the drain is done —
+ * cancellation delivers those completions from a later macrotask, not
+ * synchronously.
+ *
+ * Per instance, from that instance's own exports: two instances of this loader
+ * have separate registries and must not wait on each other.
+ *
+ * Both exports are optional, so an addon built against a napi crate that
+ * predates them keeps the previous behavior.
+ *
+ * Returns nothing when there is nothing outstanding, which keeps disposal
+ * synchronous in the common case. No deadline: giving up would destroy the
+ * environment with a completion callback still owed.
+ */
+function __drainInstanceAsyncWork(__instance) {
+  const __exports = __instance?.exports
+  const __pending = __exports?.napi_wasm_async_work_pending
+  const __cancelPending = __exports?.napi_wasm_cancel_pending_async_work
+  if (typeof __pending !== 'function' || typeof __cancelPending !== 'function') {
+    return
+  }
+
+  const __readPending = () => {
+    try {
+      return __pending()
+    } catch (__error) {
+      // A trap is the only way this call fails: it reads a counter and cannot
+      // allocate or call back into JavaScript. A trapped instance can no longer
+      // run anything, so its outstanding work is unreachable by definition and
+      // best-effort is the honest answer. Anything else means the export is not
+      // what this loader thinks it is — a defect worth surfacing.
+      if (__error instanceof globalThis.WebAssembly.RuntimeError) {
+        return 0
+      }
+      throw __error
+    }
+  }
+
+  if (!__readPending()) {
+    return
+  }
+  try {
+    __cancelPending()
+  } catch {
+    // Cancellation only bounds the wait. Failing it means waiting for the queue
+    // to run instead, which the poll below already does.
+  }
+  if (!__readPending()) {
+    return
+  }
+
+  return (async () => {
+    while (__readPending()) {
+      await new Promise((__resolve) => {
+        __scheduleTimer(__resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)
+      })
+    }
+  })()
+}
+
 function __createLifecycleReentryError(__operation) {
   const __error = new Error(
     __operation +
@@ -1890,7 +2290,15 @@ ${instanceHostState}\
     if (__lifecycleState !== 'failed') {
       __lifecycleState = 'disposal'
     }
-    // Settle what the barrier cancelled before the environment stops
+    // Outstanding async work first, while the environment is still completely
+    // live: its completion callbacks run addon code, and the barrier and
+    // \`Context.destroy()\` below each take that away. Undefined unless work is
+    // outstanding.
+    const __asyncWorkDrained = __drainInstanceAsyncWork(__napiInstance)
+    if (__asyncWorkDrained) {
+      await __asyncWorkDrained
+    }
+    // Then settle what the barrier cancelled, before the environment stops
     // accepting JavaScript calls. Undefined unless something is queued, so
     // an idle disposal is not delayed by a single turn.
     const __drained = __prepareForDisposal()
@@ -2047,6 +2455,14 @@ ${installInstanceHosts}\
     // so a failure before beforeInit costs no extra turn.
     let __settlementsUnreached = false
     try {
+      // Registration can start async work too, and this path destroys the same
+      // environment its completions need. A drain that cannot finish leaves the
+      // work outstanding, so it counts as settlements unreached and stops the
+      // rollback short of destroying, exactly like a failed barrier drain.
+      const __asyncWorkDrained = __drainInstanceAsyncWork(__napiInstance)
+      if (__asyncWorkDrained) {
+        await __asyncWorkDrained
+      }
       const __drained = __prepareForDisposal()
       if (__drained) {
         await __drained
@@ -2530,17 +2946,34 @@ function __createWasiWorker(filename) {
       }
     })(),
     reuseWorker: true,
-    plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],
+    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],
 `
     : `    asyncWorkPoolSize: 0,
-    plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],
+    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],
 `
-  // Every build links a "basic" emnapi archive without the C async-work and
-  // threadsafe-function implementations (the `emnapi-napi-rs(-mt)` archives shipped by the emnapi package), so the
-  // JavaScript implementations must be provided through the emnapi plugins in
-  // both threading modes. Without threads the C code would be unconditional
-  // `napi_generic_failure` stubs; with threads it would shadow the
-  // `@emnapi/core` threaded TSFN/async-work protocol the plugins implement.
+  // Which archive a build links decides who implements async work and
+  // threadsafe functions — see `emnapi_link_library` in
+  // `crates/build/src/wasi.rs`. Without threads it is `emnapi-basic-napi-rs`,
+  // the "basic" model: both stay wasm imports, and the `@emnapi/core`
+  // JavaScript plugins below are what resolves them; without the plugins
+  // instantiation fails with a LinkError naming the missing import. With
+  // threads it is `emnapi-napi-rs-mt`, the full composition, whose C
+  // `async_work.c` / `threadsafe_function.c` run on the uv threadpool inside
+  // the wasm — it imports none of those symbols, so the plugins are inert
+  // there. They are passed in both modes because only the archive knows which
+  // applies, and a plugin nothing imports costs nothing.
+  //
+  // This is why the async-work drain on the disposal path cannot live here:
+  // with threads there is no JavaScript seam at all, so `__drainWasiAsyncWork`
+  // asks the addon instead.
   const emnapiPluginRequire = `  emnapiAsyncWorkPlugin: __emnapiAsyncWorkPlugin,\n  emnapiTSFNPlugin: __emnapiTSFNPlugin,\n`
   const workerOption = threads
     ? `    onCreateWorker() {
@@ -2571,6 +3004,10 @@ function __createWasiWorker(filename) {
         }
 
         worker.unref()
+        // These stubs stay in place for the worker's whole life, disposal
+        // included: \`__keepEventLoopAliveUntil\` is what holds the process open
+        // while a termination is pending, precisely because a worker's own
+        // references cannot be relied on for it.
       }
       return worker
     },

package/src/utils/__tests__/reconciliation.spec.ts

@@ -117,7 +117,11 @@ test('resolveProcessExecutionIdentityForLocking re-probes until the identity is
       reads += 1
       return reads < 3 ? incompleteIdentity : completeIdentity
     },
-    { expiresAt: performance.now() + 150, timeout: 150 },
+    // A sub-second budget flakes on loaded CI runners: two 20ms retry delays
+    // plus event-loop lag can exceed it before the third read (seen on
+    // windows-msvc with ~300ms timer starvation). The nominal runtime stays
+    // ~40ms; the budget only bounds how long failures are ridden out.
+    { expiresAt: performance.now() + 2_000, timeout: 2_000 },
   )
 
   t.true(resolution.complete)
@@ -132,7 +136,10 @@ test('resolveProcessExecutionIdentityForLocking resolves incomplete past the wai
       reads += 1
       return incompleteIdentity
     },
-    { expiresAt: performance.now() + 150, timeout: 150 },
+    // Reads past the first happen on 20ms retry delays; the budget must
+    // tolerate event-loop lag on loaded CI runners so at least one re-probe
+    // (reads > 1 below) is guaranteed.
+    { expiresAt: performance.now() + 1_000, timeout: 1_000 },
   )
 
   t.false(resolution.complete)