@napi-rs/cli 3.10.5 → 3.10.7

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

@@ -5,8 +5,50 @@ import {
 } from './binding-target.js'
 
 const WASI_DISPOSE_SYMBOL = 'napi.rs.wasi.dispose'
+const WASI_THREAD_POOL_RECONCILE_SYMBOL = 'napi.rs.wasi.reconcileThreadPool'
 const WASI_ROLLBACK_REGISTRY_SYMBOL = 'napi.rs.wasi.rollback.registry.v1'
 
+/**
+ * Threaded loaders only: a view of the addon's crash flag for the pool workers.
+ *
+ * napi-async-runtime's shutdown waits run on the loader thread, inside the
+ * environment cleanup calls, and check one word of the shared wasm memory
+ * between 1 ms slices; once it is set they trap instead of waiting on a dead
+ * thread for good. napi's `napi_wasm_thread_crash_flag_address` export says
+ * where that word is. Each worker gets an `Int32Array` over it and raises it
+ * with `Atomics.store` when its wasm thread dies — right after the loader's own
+ * crash flag, where there is one. The store needs no instance, so a worker that
+ * fails while it loads, after the thread spawn that created it had already
+ * returned, raises it too.
+ *
+ * Read in `beforeInit`: before any registration code runs, and on Node before
+ * any pool worker exists (the pool is created on demand). An addon built with
+ * an older napi has no export, and a value that is not a 4-aligned address
+ * inside the memory is ignored: the view stays undefined and the waits stay
+ * unbounded, as before.
+ */
+const ADDON_CRASH_FLAG_CAPTURE = `// A view of the addon's crash flag, one word of the shared wasm memory, for the
+// pool workers: they raise it when their wasm thread dies, and the shutdown
+// waits inside the cleanup calls on this thread then trap instead of waiting on
+// the dead thread for good. Undefined for an addon built with an older napi.
+let __wasiAddonCrashFlag
+
+function __captureWasiAddonCrashFlag(instance) {
+  try {
+    const getAddress = instance.exports.napi_wasm_thread_crash_flag_address
+    if (typeof getAddress !== 'function') {
+      return
+    }
+    const address = getAddress() >>> 0
+    const buffer = __sharedMemory.buffer
+    if (address === 0 || address % 4 !== 0 || address + 4 > buffer.byteLength) {
+      return
+    }
+    __wasiAddonCrashFlag = new Int32Array(buffer, address, 1)
+  } catch {}
+}
+`
+
 /**
  * `Context.destroy()` disables JavaScript calls *before* it runs cleanup hooks
  * (`setStopping` -> `setCanCallIntoJs(false)` -> `runCleanup`), and the
@@ -88,7 +130,12 @@ function __wrapEmnapiContextDestroyForSettlement(
  * `__startWasiDisposal` / the rollback have already prepared and drained, so
  * one call there covers all three.
  */
-const createEmnapiContextLifecycle = (asyncRuntime: boolean) => {
+const createEmnapiContextLifecycle = (
+  asyncRuntime: boolean,
+  // Only the threaded Node loader defines the crash latch
+  // (`__hasWasiThreadCrashed`, `__disposeWasiBindingAfterThreadCrash`).
+  threadCrashLatch = false,
+) => {
   const currentThreadHosts = asyncRuntime
     ? `
 let __currentThreadHostsDisposer
@@ -122,9 +169,203 @@ function __disposeCurrentThreadHosts() {
 }
 `
     : ''
+  const currentThreadHostTimersAfterThreadCrash =
+    asyncRuntime && threadCrashLatch
+      ? `
+/**
+ * The CurrentThread timer host arms one referenced \`setTimeout\` per sleep in
+ * flight, so a long sleep holds the event loop open until it fires.
+ * \`__disposeCurrentThreadHosts\` releases them, but only
+ * \`__destroyEmnapiContext\` calls it, and the crash disposal never gets there:
+ * after a wasm thread died it must not enter wasm, and both the host
+ * unregister calls and a settled timer promise do. A dispose() that rejected
+ * after a crash then left the process alive until the longest sleep ended.
+ *
+ * So the loader keeps the package's own \`cancel\` for every timer in flight,
+ * and \`__releaseCurrentThreadHostTimers\` calls them after a crash. \`cancel\`
+ * is plain JavaScript: it clears the host timeout and resolves the package's
+ * promise. The promise the addon holds is the one below, and once released it
+ * never settles, so nothing is handed back to wasm. A sleep armed after that
+ * is never armed at all.
+ */
+const __currentThreadHostTimerCancels = new Set()
+let __currentThreadHostTimersReleased = false
+
+function __scheduleCurrentThreadHostTimer(schedule, cancel, id, ms) {
+  if (__currentThreadHostTimersReleased) {
+    return new Promise(() => {})
+  }
+  const scheduled = schedule(id, ms)
+  if (!__isThenable(scheduled)) {
+    return scheduled
+  }
+  const release = () => cancel(id)
+  __currentThreadHostTimerCancels.add(release)
+  const settle = (settleUnreleased) => (outcome) => {
+    __currentThreadHostTimerCancels.delete(release)
+    return __currentThreadHostTimersReleased
+      ? new Promise(() => {})
+      : settleUnreleased(outcome)
+  }
+  return Promise.resolve(scheduled).then(
+    settle((value) => value),
+    settle((error) => {
+      throw error
+    }),
+  )
+}
+
+/**
+ * The binding as \`installCurrentThreadHosts\` should see it: every export
+ * reads through, and \`registerTimerHost\` hands the addon a \`schedule\` that
+ * records its \`cancel\`. A binding without a callable \`registerTimerHost\` is
+ * passed through, so the package reports the mismatch as before.
+ */
+function __trackCurrentThreadHostTimers(binding) {
+  let registerTimerHost
+  try {
+    registerTimerHost = binding.registerTimerHost
+  } catch {
+    return binding
+  }
+  if (typeof registerTimerHost !== 'function') {
+    return binding
+  }
+  const view = Object.create(binding)
+  Object.defineProperty(view, 'registerTimerHost', {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    value: function (...args) {
+      const [, , schedule, cancel] = args
+      if (typeof schedule === 'function' && typeof cancel === 'function') {
+        args[2] = (id, ms) =>
+          __scheduleCurrentThreadHostTimer(schedule, cancel, id, ms)
+      }
+      return Reflect.apply(registerTimerHost, this, args)
+    },
+  })
+  return view
+}
+
+/**
+ * Clears every CurrentThread host timeout without entering wasm. Idempotent;
+ * a \`cancel\` that fails has already reported itself.
+ */
+function __releaseCurrentThreadHostTimers() {
+  __currentThreadHostTimersReleased = true
+  const releases = [...__currentThreadHostTimerCancels]
+  __currentThreadHostTimerCancels.clear()
+  for (const release of releases) {
+    try {
+      release()
+    } catch {}
+  }
+}
+`
+      : ''
   const disposeCurrentThreadHosts = asyncRuntime
     ? '  __disposeCurrentThreadHosts()\n'
     : ''
+  // After the in-flight check: a disposal that was already running when a
+  // thread died settles through the crash disposal itself, so every caller of
+  // it keeps getting the one promise it handed out.
+  const disposeAfterThreadCrash = threadCrashLatch
+    ? `  if (!__wasiDisposed && __hasWasiThreadCrashed()) {
+    return __disposeWasiBindingAfterThreadCrash()
+  }
+`
+    : ''
+  // A thread can die after the entry check above has passed. The disposal's
+  // polls and step boundaries check again, and a chain stopped that way — or
+  // failed any other way once a thread is dead — settles through the crash
+  // disposal. See `__abortWasiDisposalIfThreadCrashed`.
+  const abortDisposalAfterThreadCrash = (indent: string) =>
+    threadCrashLatch ? `${indent}__abortWasiDisposalIfThreadCrashed()\n` : ''
+  const settleDisposalAfterThreadCrash = (indent: string, exit: string) =>
+    threadCrashLatch
+      ? `${indent}if (__settleWasiDisposalAfterThreadCrash(resolveDispose, rejectDispose)) {
+${indent}  ${exit}
+${indent}}
+`
+      : ''
+  // The barrier's poll ends in `…_finish`, which joins the runtime's work. A
+  // dead thread's work never goes idle, so after a crash the join would block
+  // this thread for good: leave the barrier parked and stop the disposal.
+  const finishWasmEnvCleanupUnlessCrashed = threadCrashLatch
+    ? `  const finishCleanupUnlessCrashed = () => {
+    try {
+      __abortWasiDisposalIfThreadCrashed()
+    } catch (error) {
+      __finishParkedWasmEnvCleanup = undefined
+      throw error
+    }
+    finishCleanup()
+  }
+`
+    : ''
+  const finishWasmEnvCleanupAfterPoll = threadCrashLatch
+    ? 'finishCleanupUnlessCrashed'
+    : 'finishCleanup'
+  // The initialization rollback runs the same polls and steps. With the latch,
+  // its body keeps its own name and `__rollbackWasiInitialization` becomes the
+  // wrapper that stops it after a crash. See
+  // `__rollbackWasiInitializationAfterThreadCrash`.
+  const rollbackStepsName = threadCrashLatch
+    ? '__runWasiInitializationRollbackSteps'
+    : '__rollbackWasiInitialization'
+  const rollbackAfterThreadCrash = threadCrashLatch
+    ? `
+/**
+ * The rollback above, stopped when a wasm thread has died.
+ *
+ * Its polls wait for work the dead thread still counts, so they never end, and
+ * the barrier's \`…_finish\` and \`Context.destroy()\` would re-enter wasm
+ * and wait on that thread for good. While the rollback runs, the poll turns
+ * and step boundaries stop it (\`__abortWasiDisposalIfThreadCrashed\`), and a
+ * crash seen before, during or after it ends it through
+ * \`__rollbackWasiInitializationAfterThreadCrash\`. Without a crash the
+ * result — synchronous or not — is passed through unchanged.
+ */
+function __rollbackWasiInitialization() {
+  if (__hasWasiThreadCrashed()) {
+    return __rollbackWasiInitializationAfterThreadCrash()
+  }
+  __wasiInitializationRollbackActive = true
+  let result
+  try {
+    result = __runWasiInitializationRollbackSteps()
+  } catch (error) {
+    __wasiInitializationRollbackActive = false
+    if (__hasWasiThreadCrashed()) {
+      return __rollbackWasiInitializationAfterThreadCrash()
+    }
+    throw error
+  }
+  if (!__isThenable(result)) {
+    __wasiInitializationRollbackActive = false
+    return __hasWasiThreadCrashed()
+      ? __rollbackWasiInitializationAfterThreadCrash()
+      : result
+  }
+  return Promise.resolve(result).then(
+    (cleanupErrors) => {
+      __wasiInitializationRollbackActive = false
+      return __hasWasiThreadCrashed()
+        ? __rollbackWasiInitializationAfterThreadCrash()
+        : cleanupErrors
+    },
+    (error) => {
+      __wasiInitializationRollbackActive = false
+      if (__hasWasiThreadCrashed()) {
+        return __rollbackWasiInitializationAfterThreadCrash()
+      }
+      throw error
+    },
+  )
+}
+`
+    : ''
 
   return `
 const __wasiDisposeSymbol = Symbol.for('${WASI_DISPOSE_SYMBOL}')
@@ -188,7 +429,7 @@ let __completeWasiDisposal = function () {}
 // that stopped short of destroying the context. See
 // \`__rollbackWasiInitialization\`.
 let __retainWasiRollbackForRetry = function () {}
-${currentThreadHosts}
+${currentThreadHosts}${currentThreadHostTimersAfterThreadCrash}
 function __isThenable(value) {
   return (
     value !== null &&
@@ -653,6 +894,7 @@ function __prepareWasmEnvCleanupWithTurns() {
   // Publish the closer before yielding: from here until \`finishCleanup\` runs,
   // a caller that cannot yield is entitled to end this handshake itself.
   __finishParkedWasmEnvCleanup = finishCleanup
+${finishWasmEnvCleanupUnlessCrashed}\
   return (async () => {
     // Unbounded, exactly like the async-work drain below. The wait ends when
     // the addon reports its runtime work finished; the turns spent here are
@@ -660,6 +902,7 @@ function __prepareWasmEnvCleanupWithTurns() {
     const pace = __createWasmRuntimePollPace()
     for (;;) {
       await __yieldWasmRuntimePollTurn(pace)
+${abortDisposalAfterThreadCrash('      ')}\
       try {
         if (!workPending()) {
           return
@@ -670,7 +913,7 @@ function __prepareWasmEnvCleanupWithTurns() {
         return
       }
     }
-  })().then(finishCleanup, finishCleanup)
+  })().then(${finishWasmEnvCleanupAfterPoll}, ${finishWasmEnvCleanupAfterPoll})
 }
 
 // Turns to wait for while the addon still reports queued settlements. Reaching
@@ -994,6 +1237,7 @@ function __drainWasiAsyncWork() {
         await new Promise((resolve) => {
           __scheduleTimer(resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)
         })
+${abortDisposalAfterThreadCrash('        ')}\
       }
     })(),
   ).then(
@@ -1089,6 +1333,7 @@ function __finishWasiDisposal() {
 }
 
 function __continueWasiDisposal() {
+${abortDisposalAfterThreadCrash('  ')}\
   const destroyResult = __destroyEmnapiContext()
   if (__isThenable(destroyResult)) {
     return Promise.resolve(destroyResult).then(__finishWasiDisposal)
@@ -1097,6 +1342,7 @@ function __continueWasiDisposal() {
 }
 
 function __drainWasmEnvForWasiDisposal() {
+${abortDisposalAfterThreadCrash('  ')}\
   const drainResult = __drainWasmEnvCleanup()
   if (__isThenable(drainResult)) {
     return Promise.resolve(drainResult).then(__continueWasiDisposal)
@@ -1105,6 +1351,7 @@ function __drainWasmEnvForWasiDisposal() {
 }
 
 function __cleanUpWasmEnvForWasiDisposal() {
+${abortDisposalAfterThreadCrash('  ')}\
   // Run the pre-teardown barrier — yielding the turns its two-phase form asks
   // for, when the addon has one — then let the settlements it queued actually
   // reach JavaScript, and only then destroy the environment. Doing any two of
@@ -1141,6 +1388,7 @@ function __disposeWasiBinding() {
   if (__wasiDisposePromise) {
     return __wasiDisposePromise
   }
+${disposeAfterThreadCrash}\
   if (__wasiDisposed) {
     return Promise.resolve()
   }
@@ -1157,6 +1405,7 @@ function __disposeWasiBinding() {
   try {
     result = __startWasiDisposal()
   } catch (error) {
+${settleDisposalAfterThreadCrash('    ', 'return disposePromise')}\
     __wasiDisposePromise = undefined
     rejectDispose(error)
     return disposePromise
@@ -1168,6 +1417,7 @@ function __disposeWasiBinding() {
       resolveDispose(value)
     },
     (error) => {
+${settleDisposalAfterThreadCrash('      ', 'return')}\
       __wasiDisposePromise = undefined
       rejectDispose(error)
     },
@@ -1203,6 +1453,7 @@ function __finishWasiInitializationRollback(cleanupErrors) {
 }
 
 function __destroyContextForWasiRollback(cleanupErrors) {
+${abortDisposalAfterThreadCrash('  ')}\
   let destroyResult
   try {
     destroyResult = __destroyEmnapiContext()
@@ -1271,10 +1522,11 @@ function __retainFailedWasiRollback(cleanupErrors) {
  * goes away. That is the deliberate choice: a hung promise is a silent liveness
  * bug with no upper bound, while the retained bookkeeping is bounded by the page.
  */
-function __rollbackWasiInitialization() {
+function ${rollbackStepsName}() {
   // The environment teardown this rollback performs, kept nested so it cannot
   // be reached without the async-work drain below running first.
   function __rollbackWasmEnvForWasiInitialization() {
+${abortDisposalAfterThreadCrash('    ')}\
     const cleanupErrors = []
     let prepareResult
     try {
@@ -1300,6 +1552,7 @@ function __rollbackWasiInitialization() {
   // did not finish never gets here: it retains instead, exactly as a drain that
   // did not finish does.
   function __drainWasmEnvForWasiRollback(cleanupErrors) {
+${abortDisposalAfterThreadCrash('    ')}\
     let drainResult
     try {
       drainResult = __drainWasmEnvCleanup()
@@ -1346,6 +1599,7 @@ function __rollbackWasiInitialization() {
   }
   return __rollbackWasmEnvForWasiInitialization()
 }
+${rollbackAfterThreadCrash}\
 `
 }
 
@@ -1499,10 +1753,35 @@ const __workerPoolSize = Math.max(
         type: 'module',
       })
       __wasiWorkers.add(worker)
+      __shareWasiAddonCrashFlag(worker)
 ${workerFsHandler}
 ${workerErrorHandler}
       return worker
     },
+`
+    : ''
+  // The pool is created before the wasm is instantiated, so the workers that
+  // exist by `beforeInit` get the view there, after their 'load' message and
+  // before any 'start'; a worker created later gets it first thing. A message
+  // rather than worker options: a browser Worker has no `workerData`.
+  const addonCrashFlagSharing = threads
+    ? `${ADDON_CRASH_FLAG_CAPTURE}
+function __shareWasiAddonCrashFlag(worker) {
+  if (__wasiAddonCrashFlag === undefined) {
+    return
+  }
+  try {
+    worker.postMessage({ __napiRsAddonCrashFlag: __wasiAddonCrashFlag })
+  } catch {}
+}
+
+`
+    : ''
+  const captureAddonCrashFlag = threads
+    ? `      __captureWasiAddonCrashFlag(instance)
+      for (const worker of __wasiWorkers) {
+        __shareWasiAddonCrashFlag(worker)
+      }
 `
     : ''
 
@@ -1542,6 +1821,7 @@ ${threads ? '  shared: true,\n' : ''}\
 ${workerPoolSizeBinding}\
 let __emnapiContext
 ${createEmnapiContextLifecycle(asyncRuntime)}
+${addonCrashFlagSharing}\
 let __wasiModule
 let __napiModule
 
@@ -1575,6 +1855,7 @@ ${workerOption}\
     },
     beforeInit({ instance }) {
       __napiInstance = instance
+${captureAddonCrashFlag}\
       for (const name of Object.keys(instance.exports)) {
         if (name.startsWith('__napi_register__')) {
           instance.exports[name]()
@@ -3608,9 +3889,11 @@ export const createWasiBinding = (
 } = require('@napi-rs/async-runtime')
 `
     : ''
+  // The threaded loader has the thread crash latch, whose disposal releases
+  // the host timers it tracks. See \`__trackCurrentThreadHostTimers\`.
   const installAsyncRuntimeHosts = asyncRuntime
     ? `  __currentThreadHostsDisposer = __installCurrentThreadHosts(
-    __napiModule.exports,
+    ${threads ? '__trackCurrentThreadHostTimers(__napiModule.exports)' : '__napiModule.exports'},
   )
 `
     : ''
@@ -3694,7 +3977,13 @@ function __createWasiWorker(filename) {
       return new Worker(filename, {
         env: process.env,
         execArgv: __workerExecArgv,
-        workerData: { hostRoot: __hostRoot, rootDir: __rootDir },
+        workerData: {
+          hostRoot: __hostRoot,
+          rootDir: __rootDir,
+          crashFlag: __wasiThreadCrashFlag,
+          crashReport: __wasiThreadCrashReport,
+          addonCrashFlag: __wasiAddonCrashFlag,
+        },
       })
     } catch (error) {
       if (!error || error.code !== 'ERR_WORKER_INVALID_EXEC_ARGV') {
@@ -3711,6 +4000,505 @@ function __createWasiWorker(filename) {
 }
 `
     : ''
+  // The host timeouts a CurrentThread sleep armed, released without entering
+  // wasm on every crash path. See `__trackCurrentThreadHostTimers`.
+  const releaseCurrentThreadHostTimers = (indent: string) =>
+    threads && asyncRuntime
+      ? `${indent}__releaseCurrentThreadHostTimers()\n`
+      : ''
+  // The threaded context defers emnapi's calls into wasm through
+  // `__wasiSetImmediate`, which a crash disposal closes.
+  const emnapiContextOptions = threads
+    ? '{ autoDestroy: false, features: { setImmediate: __wasiSetImmediate } }'
+    : '{ autoDestroy: false }'
+  // Only the threaded flavor has pool workers whose wasm thread can die under
+  // this one. See `__disposeWasiBindingAtExit`.
+  const threadCrashLatch = threads
+    ? `
+// Set to 1 by a pool worker (see wasi-worker.mjs) right before it reports that
+// its wasm thread died. Shared memory, so this thread reads it synchronously even
+// while the worker's 'error' event is still queued behind the code that is
+// exiting right now.
+const __wasiThreadCrashFlag = new Int32Array(new SharedArrayBuffer(4))
+// Written by the first pool worker whose wasm thread dies, before it raises the
+// flag: its error and \`threadId\` (layout in wasi-worker.mjs). Read without
+// waiting for any event, see \`__readWasiThreadCrashReport\`.
+const __wasiThreadCrashReport = new SharedArrayBuffer(4096)
+let __wasiThreadCrashReportRead
+// The first error a pool worker reported through its 'error' event, and that
+// worker's \`threadId\`. See \`__getWasiThreadCrashError\`.
+let __wasiThreadCrashWorkerError
+let __wasiThreadCrashWorkerId
+let __wasiThreadCrashError
+// Raised while \`__runWasiInitializationRollbackSteps\` runs, so its polls and
+// steps stop after a crash the way a public disposal's do.
+let __wasiInitializationRollbackActive = false
+let __wasiThreadCrashed = false
+
+${ADDON_CRASH_FLAG_CAPTURE}
+/**
+ * Whether any wasm thread of this binding has died: a trap or an uncaught error
+ * in a pool worker, including one that failed to load after its thread spawn
+ * had already been reported as started.
+ *
+ * After that the shared wasm state cannot be trusted: a lock the dead thread
+ * held stays held, and a join or park that waits on it — the async runtime's
+ * \`finish_shutdown\` waiting for the dead thread's work to go idle — blocks
+ * this thread forever in a raw \`memory.atomic.wait32\`, which neither
+ * emnapi's crash check nor a signal can interrupt.
+ */
+function __hasWasiThreadCrashed() {
+  if (__wasiThreadCrashed || Atomics.load(__wasiThreadCrashFlag, 0) !== 0) {
+    return true
+  }
+  const manager = __getWasiThreadManager()
+  return Boolean(manager && manager._fatalError)
+}
+
+let __wasiThreadCrashDisposePromise
+// Raised by the crash disposal right before it terminates the workers. See
+// \`__wasiSetImmediate\`.
+let __wasiReentryClosed = false
+
+/**
+ * emnapi's \`features.setImmediate\` for this binding's context. emnapi defers
+ * its calls back into wasm through it: \`_emnapi_set_immediate\` (libuv handle
+ * closes, threadsafe-function finalizers), threadsafe-function dispatch
+ * (\`async-send\`) and the finalizer queue. One queued before a crash disposal
+ * terminates the workers still runs after it, and a worker terminated while it
+ * held a lock in the wasm heap (napi's heap-sync allocator lock spins and never
+ * gives up) leaves that call spinning on this thread for good. The binding is
+ * unusable after a crash disposal, so those calls are dropped.
+ *
+ * Known residual, still able to enter wasm after a crash disposal because emnapi
+ * offers no hook for them: the \`FinalizationRegistry\` callbacks that free
+ * external memory when GC collects a value (\`_free\`, the shared-buffer meta
+ * release), threadsafe-function dispatch of \`async-send\` type 1 and
+ * \`_emnapi_next_tick\` (both \`Promise.resolve().then\`), and every deferred
+ * call under emnapi 1.x, whose \`createContext\` ignores \`features\`.
+ */
+function __wasiSetImmediate(callback) {
+  return setImmediate(function () {
+    if (!__wasiReentryClosed) {
+      callback()
+    }
+  })
+}
+
+/**
+ * Stores the first error a pool worker reported, with the worker's id. Called
+ * from the loader's own 'error' listener, which runs before emnapi's.
+ */
+function __recordWasiThreadCrashError(error, workerId) {
+  if (__wasiThreadCrashWorkerError !== undefined || error === undefined) {
+    return
+  }
+  __wasiThreadCrashWorkerError = error
+  __wasiThreadCrashWorkerId = workerId
+  __fillWasiThreadCrashError()
+}
+
+/**
+ * The error in the shared crash report, rebuilt once it is complete: the
+ * worker writes it before it raises the flag, so it is there as soon as the
+ * crash is seen. Plain JavaScript over shared memory; never enters wasm.
+ */
+function __readWasiThreadCrashReport() {
+  if (__wasiThreadCrashReportRead !== undefined) {
+    return __wasiThreadCrashReportRead
+  }
+  try {
+    const header = new Int32Array(__wasiThreadCrashReport, 0, 3)
+    if (Atomics.load(header, 0) !== 2) {
+      return
+    }
+    const length = Atomics.load(header, 1)
+    const threadId = Atomics.load(header, 2)
+    let error
+    if (length > 0) {
+      // Copied out of shared memory: TextDecoder does not take a shared view.
+      const bytes = new Uint8Array(__wasiThreadCrashReport, 12, length).slice()
+      const report = JSON.parse(new TextDecoder().decode(bytes))
+      error = new Error(String(report.message))
+      if (typeof report.name === 'string') {
+        error.name = report.name
+      }
+      if (typeof report.stack === 'string') {
+        error.stack = report.stack
+      }
+    }
+    __wasiThreadCrashReportRead = { error, threadId }
+  } catch {
+    __wasiThreadCrashReportRead = { error: undefined, threadId: 0 }
+  }
+  return __wasiThreadCrashReportRead
+}
+
+/**
+ * The one error every crash path of this binding reports, created on first
+ * use.
+ *
+ * The shared flag is raised before this thread has processed the worker's
+ * 'error' event, and once the workers are terminated that event is often
+ * never delivered, so neither it nor emnapi's \`_fatalError\` can be counted
+ * on. The cause is filled in from the first source that has it: the error the
+ * 'error' listener kept, else the worker's shared crash report, else
+ * \`_fatalError\` — here, and again from the 'error' listener when it arrives
+ * later. Until then the error carries only its message.
+ */
+function __getWasiThreadCrashError() {
+  if (__wasiThreadCrashError === undefined) {
+    __wasiThreadCrashError = new Error(
+      'napi-rs: WASI binding cannot be disposed after a worker thread crashed',
+    )
+  }
+  __fillWasiThreadCrashError()
+  return __wasiThreadCrashError
+}
+
+function __fillWasiThreadCrashError() {
+  const crashError = __wasiThreadCrashError
+  if (crashError === undefined) {
+    return
+  }
+  try {
+    if (crashError.cause === undefined) {
+      let cause = __wasiThreadCrashWorkerError
+      if (cause === undefined) {
+        const report = __readWasiThreadCrashReport()
+        cause = report ? report.error : undefined
+      }
+      if (cause === undefined) {
+        const manager = __getWasiThreadManager()
+        cause = manager ? manager._fatalError : undefined
+      }
+      if (cause !== undefined && cause !== null) {
+        crashError.cause = cause
+      }
+    }
+    if (crashError.workerThreadId === undefined) {
+      let workerId = __wasiThreadCrashWorkerId
+      if (workerId === undefined) {
+        const report = __readWasiThreadCrashReport()
+        workerId = report && report.threadId > 0 ? report.threadId : undefined
+      }
+      if (workerId !== undefined) {
+        crashError.workerThreadId = workerId
+      }
+    }
+  } catch {}
+}
+
+/**
+ * Let the event loop drain after a wasm thread died, without entering wasm.
+ *
+ * emnapi's \`Context\` keeps a \`NodejsWaitingRequestCounter\` on Node: a
+ * \`MessagePort\` (\`refCounter.refHandle\`) that it refs when the count of
+ * in-flight async work and threadsafe-function requests leaves zero and unrefs
+ * when it comes back. The requests the dead thread held never complete, so the
+ * count never returns to zero and the port holds the process open for good.
+ * \`Context.destroy()\` would not release it either — and it runs cleanup
+ * hooks, which is exactly what must not happen now. So unref the port directly.
+ * The count is left as is: it stays above zero, so a later request never refs
+ * the port again.
+ *
+ * The field is private in emnapi's typings, so read it defensively; a context
+ * without it (a non-Node host, a future emnapi) is left alone.
+ */
+function __releaseEmnapiWaitingRequestHandle() {
+  try {
+    const refCounter = __emnapiContext && __emnapiContext.refCounter
+    const refHandle = refCounter && refCounter.refHandle
+    if (refHandle && typeof refHandle.unref === 'function') {
+      refHandle.unref()
+    }
+  } catch {}
+}
+
+/**
+ * The public disposer after a wasm thread died. The normal chain drains async
+ * work, runs the environment cleanup barrier and destroys the context — every
+ * one of those re-enters wasm, and the barrier's shutdown waits for the dead
+ * thread's work in the same raw atomic wait \`__disposeWasiBindingAtExit\`
+ * avoids. An app that handled the worker's error and then disposes would block
+ * there for good. Only stop the workers, then reject: the binding was not
+ * cleaned up and cannot be, so reporting success would be a lie. The context
+ * is not destroyed — only its waiting-request port is unrefed, so the process
+ * can exit on its own — and the 'exit' listener takes its short path too.
+ *
+ * Latched: every later call returns the same promise.
+ */
+function __disposeWasiBindingAfterThreadCrash() {
+  if (__wasiThreadCrashDisposePromise) {
+    return __wasiThreadCrashDisposePromise
+  }
+  __releaseEmnapiWaitingRequestHandle()
+${releaseCurrentThreadHostTimers('  ')}\
+  // No call into wasm after this: see \`__wasiSetImmediate\`.
+  __wasiReentryClosed = true
+  let workerResult
+  try {
+    workerResult = __terminateWasiWorkers()
+  } catch (terminateError) {
+    workerResult = Promise.reject(terminateError)
+  }
+  // Built at settlement, after the workers stopped: by then the 'error' event
+  // has usually delivered the worker's error.
+  __wasiThreadCrashDisposePromise = Promise.resolve(workerResult).then(
+    () => {
+      throw __getWasiThreadCrashError()
+    },
+    (terminateError) => {
+      throw __attachCleanupErrors(__getWasiThreadCrashError(), [
+        terminateError,
+      ])
+    },
+  )
+  return __wasiThreadCrashDisposePromise
+}
+
+/**
+ * Stops a public disposal that a thread crash overtook.
+ *
+ * The check at the top of \`__disposeWasiBinding\` only sees a crash that came
+ * first. A thread that dies once the chain is running leaves it polling for
+ * work the dead thread still counts — the async-work drain for
+ * \`napi_wasm_async_work_pending\`, the barrier's poll for
+ * \`napi_wasm_runtime_work_pending\` — and neither count ever reaches zero, so
+ * the poll's referenced timers keep the process alive forever with the
+ * disposal promise pending. Each poll turn and each step boundary calls this,
+ * and the throw ends the chain before anything re-enters wasm again; the
+ * disposer then settles it through \`__settleWasiDisposalAfterThreadCrash\`.
+ *
+ * The initialization rollback runs the same polls and steps, so they stop while
+ * it runs too; its wrapper, \`__rollbackWasiInitialization\`, then ends it
+ * through \`__rollbackWasiInitializationAfterThreadCrash\`. A bare poll with
+ * neither in flight is left alone.
+ */
+function __abortWasiDisposalIfThreadCrashed() {
+  if (
+    (__wasiDisposePromise !== undefined ||
+      __wasiInitializationRollbackActive) &&
+    __hasWasiThreadCrashed()
+  ) {
+    throw new Error(
+      'napi-rs: WASI disposal stopped because a worker thread crashed',
+    )
+  }
+}
+
+/**
+ * Settles an in-flight public disposal whose chain failed after a thread
+ * died — stopped by \`__abortWasiDisposalIfThreadCrashed\` or failing any other
+ * way — through the crash disposal: it releases the waiting-request port,
+ * terminates the workers and rejects with the same error an entry-time crash
+ * gets. \`__wasiDisposePromise\` stays set, so this caller, every caller that
+ * joined it and every later one hold the same promise. Returns false when no
+ * thread died, leaving the ordinary failure handling alone.
+ */
+function __settleWasiDisposalAfterThreadCrash(resolve, reject) {
+  if (!__hasWasiThreadCrashed()) {
+    return false
+  }
+  __disposeWasiBindingAfterThreadCrash().then(resolve, reject)
+  return true
+}
+
+/**
+ * Ends an initialization rollback after a wasm thread died, without entering
+ * wasm: the barrier, its finish and \`Context.destroy()\` are skipped, and the
+ * crash disposal releases the waiting-request port and terminates the workers,
+ * once. The initialization error itself is left to propagate: the crash error
+ * is returned as the rollback's cleanup error, so
+ * \`__completeWasiInitializationRollback\` attaches it — as the cause when the
+ * error has none — and keeps the record, since the context was not destroyed.
+ */
+function __rollbackWasiInitializationAfterThreadCrash() {
+  const crashError = __getWasiThreadCrashError()
+  // Its rejection is \`crashError\` itself, which the caller reports.
+  void __disposeWasiBindingAfterThreadCrash().catch(() => {})
+  return [crashError]
+}
+`
+    : ''
+  const skipTeardownAfterThreadCrash = threads
+    ? `  if (__hasWasiThreadCrashed()) {
+    // Never re-enter wasm after a thread died: the environment cleanup joins
+    // the dead thread's work and would hang the exit forever — SIGTERM
+    // included, since its JavaScript listener never gets a turn. Stop the
+    // workers and leave.
+${releaseCurrentThreadHostTimers('    ')}\
+    try {
+      void Promise.resolve(__terminateWasiWorkers()).catch(() => {})
+    } catch {}
+    return
+  }
+`
+    : ''
+  // Threaded flavor only: keeps emnapi's idle reuse pool at the addon's
+  // configured MultiThread worker count. See docs/wasi.md, "Thread pool
+  // preload".
+  const threadPoolReconcile = threads
+    ? `
+const __wasiThreadPoolReconcileSymbol = Symbol.for('${WASI_THREAD_POOL_RECONCILE_SYMBOL}')
+
+/**
+ * Takes a Worker out of emnapi's reuse pool, if it is still there. emnapi
+ * terminates a pooled Worker that failed to load but (up to
+ * @emnapi/wasi-threads 2.1.0) leaves it in the pool, where the next thread
+ * spawn would pop it. A newer emnapi removes it itself, so this is a no-op
+ * then.
+ */
+function __removeWasiPoolWorker(manager, worker) {
+  const index = manager.unusedWorkers.indexOf(worker)
+  if (index !== -1) {
+    manager.unusedWorkers.splice(index, 1)
+  }
+}
+
+/**
+ * Takes a Worker the thread manager just terminated out of \`__wasiWorkers\`
+ * once it has exited, not before. \`terminateWorker\` only starts Node's
+ * asynchronous \`worker.terminate()\` and drops its promise, so a disposal that
+ * begins before the exit has to find this Worker in the set and wait for it
+ * like any other. A second \`terminate()\` settles when the Worker has exited,
+ * the way \`__terminateWasiWorkers\` waits.
+ */
+function __untrackWasiWorkerOnExit(worker) {
+  const terminated = worker.terminate()
+  if (__isThenable(terminated)) {
+    Promise.resolve(terminated).then(
+      () => {
+        __wasiWorkers.delete(worker)
+      },
+      // Left tracked: disposal terminates it again and reports the error.
+      () => {},
+    )
+  } else {
+    __wasiWorkers.delete(worker)
+  }
+}
+
+/**
+ * Matches emnapi's idle reuse pool to the addon's configured MultiThread worker
+ * count, which the addon exports as \`napi_wasm_runtime_pool_workers\`
+ * (napi-async-runtime; 0 under CurrentThread). \`reuseWorker: true\` starts the
+ * pool empty, so without this every pool thread the first async call spawns
+ * boots a Worker and loads the wasm into it first. Here each missing Worker is
+ * created and starts loading now; a spawn later pops one that is already
+ * booting. Idle Workers above the count are terminated, last in first out,
+ * the way a spawn takes them. A Worker a spawn already took is not in the pool
+ * and is left alone.
+ *
+ * Runs once after a successful load and, when the loader wraps it, after every
+ * successful \`configureAsyncRuntime\`. Also reachable as
+ * binding[Symbol.for('${WASI_THREAD_POOL_RECONCILE_SYMBOL}')]().
+ * It never throws and never waits on a Worker: a Worker whose load fails is
+ * dropped from the pool when its load rejects. Nothing at all happens after a
+ * thread crash, once disposal started, or for an addon without the export.
+ */
+function __reconcileWasiThreadPool() {
+  try {
+    if (__wasiDisposed || __wasiDisposePromise || __hasWasiThreadCrashed()) {
+      return
+    }
+    const read = __napiInstance?.exports?.napi_wasm_runtime_pool_workers
+    if (typeof read !== 'function') {
+      return
+    }
+    const count = read() >>> 0
+    const manager = __getWasiThreadManager()
+    if (
+      !manager ||
+      !Array.isArray(manager.unusedWorkers) ||
+      typeof manager.allocateUnusedWorker !== 'function' ||
+      typeof manager.loadWasmModuleToWorker !== 'function'
+    ) {
+      return
+    }
+    // Both loops are bounded by the difference they start from, so a manager
+    // that does not update \`unusedWorkers\` the way emnapi does cannot spin.
+    for (let excess = manager.unusedWorkers.length - count; excess > 0; excess--) {
+      const worker = manager.unusedWorkers[manager.unusedWorkers.length - 1]
+      manager.terminateWorker(worker)
+      __removeWasiPoolWorker(manager, worker)
+      __untrackWasiWorkerOnExit(worker)
+      // Compatibility with @emnapi/wasi-threads 2.1.0 and older:
+      // \`terminateWorker\` installs a reporter that logs every emnapi message
+      // still queued on the port, so a Worker that finished loading just
+      // before it was terminated prints 'received "loaded" command from
+      // terminated worker'. Nothing listens for that Worker any more, and a
+      // newer emnapi ignores the late 'loaded' itself, so this is harmless
+      // there. \`__terminateWasiWorkers\` does the same.
+      worker.onmessage = undefined
+    }
+    for (let missing = count - manager.unusedWorkers.length; missing > 0; missing--) {
+      let worker
+      try {
+        // Through \`onCreateWorker\`: tracked in \`__wasiWorkers\`, unref'd, and
+        // handed the crash flags like any pool Worker.
+        worker = manager.allocateUnusedWorker()
+        manager
+          .loadWasmModuleToWorker(worker)
+          .then(undefined, () => __removeWasiPoolWorker(manager, worker))
+      } catch {
+        if (worker !== undefined) {
+          __removeWasiPoolWorker(manager, worker)
+          try {
+            manager.terminateWorker(worker)
+            __untrackWasiWorkerOnExit(worker)
+          } catch {}
+        }
+        return
+      }
+    }
+  } catch {}
+}
+
+function __publishWasiThreadPoolReconcile(exports) {
+  Object.defineProperty(exports, __wasiThreadPoolReconcileSymbol, {
+    configurable: false,
+    enumerable: false,
+    value: __reconcileWasiThreadPool,
+    writable: false,
+  })
+}
+${
+  asyncRuntime
+    ? `
+/**
+ * Replaces the addon's \`configureAsyncRuntime\` export, if it has one, with a
+ * wrapper that reconciles the pool after every successful call: a configure
+ * changes the count the pool was preloaded for. A configure that throws changed
+ * nothing, so its error propagates and the pool stays as it is. Matched by
+ * name, like the CurrentThread host install: it is the export
+ * napi-async-runtime's adapter defines, and an addon that defines its own under
+ * that name gets the same reconcile. Never fails the load.
+ */
+function __wrapWasiConfigureAsyncRuntime(binding) {
+  let configure
+  try {
+    configure = binding.configureAsyncRuntime
+  } catch {
+    return
+  }
+  if (typeof configure !== 'function') {
+    return
+  }
+  try {
+    binding.configureAsyncRuntime = function configureAsyncRuntime(...args) {
+      const result = Reflect.apply(configure, this, args)
+      try {
+        __reconcileWasiThreadPool()
+      } catch {}
+      return result
+    }
+  } catch {}
+}
+`
+    : ''
+}`
+    : ''
   const workerRuntimeImport = threads
     ? `  createOnMessage: __wasmCreateOnMessageForFsProxy,\n`
     : ''
@@ -3755,10 +4543,18 @@ function __createWasiWorker(filename) {
   // with threads there is no JavaScript seam at all, so `__drainWasiAsyncWork`
   // asks the addon instead.
   const emnapiPluginRequire = `  emnapiAsyncWorkPlugin: __emnapiAsyncWorkPlugin,\n  emnapiTSFNPlugin: __emnapiTSFNPlugin,\n`
+  const captureAddonCrashFlag = threads
+    ? '      __captureWasiAddonCrashFlag(instance)\n'
+    : ''
   const workerOption = threads
     ? `    onCreateWorker() {
       const worker = __createWasiWorker(__nodePath.join(__dirname, 'wasi-worker.mjs'))
       __wasiWorkers.add(worker)
+      // Registered before emnapi's own listeners, which rethrow the error.
+      worker.on('error', (error) => {
+        __wasiThreadCrashed = true
+        __recordWasiThreadCrashError(error, worker.threadId)
+      })
       worker.onmessage = ({ data }) => {
         __wasmCreateOnMessageForFsProxy(__nodeFs)(data)
       }
@@ -3813,6 +4609,8 @@ ${workerRuntimeImport}\
 const { createContext: __emnapiCreateContext } = require('@emnapi/runtime')
 ${asyncRuntimeImport}\
 ${workerExecArgv}\
+${threadCrashLatch}\
+${threadPoolReconcile}\
 
 const __cwd = process.cwd()
 const __rootDir = __nodePath.parse(__cwd).root
@@ -3855,7 +4653,7 @@ if (__nodeFs.existsSync(__wasmDebugFilePath)) {
 
 const __wasmFile = __nodeFs.readFileSync(__wasmFilePath)
 let __emnapiContext
-${createEmnapiContextLifecycle(asyncRuntime)}
+${createEmnapiContextLifecycle(asyncRuntime, threads)}
 const __wasiRollbackRegistrySymbol = Symbol.for('${WASI_ROLLBACK_REGISTRY_SYMBOL}')
 const __wasiRollbackRegistryKey =
   typeof __filename === 'string' ? __filename : __wasmFilePath
@@ -3959,6 +4757,7 @@ function __removeWasiExitListener() {
 
 function __disposeWasiBindingAtExit() {
   __wasiExitListenerRegistered = false
+${skipTeardownAfterThreadCrash}\
   // An 'exit' handler cannot yield, so it cannot wait for queued promise
   // settlements the way __startWasiDisposal does — the process is leaving and
   // those promises have no observer left anyway. Run the synchronous teardown
@@ -4033,7 +4832,7 @@ try {
   const __finishAutoDestroyCapture = __captureEmnapiAutoDestroyListener()
   try {
     __emnapiContext = __wrapEmnapiContextDestroyForSettlement(
-      __emnapiCreateContext({ autoDestroy: false }),
+      __emnapiCreateContext(${emnapiContextOptions}),
       __prepareWasmEnvCleanup,
       __isPreparingWasmEnvCleanup,
     )
@@ -4068,6 +4867,7 @@ ${workerOption}\
     },
     beforeInit({ instance }) {
       __napiInstance = instance
+${captureAddonCrashFlag}\
       for (const name of Object.keys(instance.exports)) {
         if (name.startsWith('__napi_register__')) {
           instance.exports[name]()
@@ -4076,7 +4876,9 @@ ${workerOption}\
     },
   }))
   __publishWasiDispose(__napiModule.exports)
+${threads ? '  __publishWasiThreadPoolReconcile(__napiModule.exports)\n' : ''}\
 ${installAsyncRuntimeHosts}\
+${threads && asyncRuntime ? '  __wrapWasiConfigureAsyncRuntime(__napiModule.exports)\n' : ''}\
   // The CommonJS tail below aliases \`__napiModule.exports\`; a named module
   // export does not travel with it, so carry the marker on the binding itself
   // too. Three things pin the stamp to exactly this spot:
@@ -4105,5 +4907,14 @@ ${installAsyncRuntimeHosts}\
   __runWasiInitializationRollback(rollback)
   throw rollback.error
 }
+${
+  threads
+    ? `// Preload the pool for the count the addon configured during registration.
+// See \`__reconcileWasiThreadPool\`.
+try {
+  __reconcileWasiThreadPool()
+} catch {}
 `
+    : ''
+}`
 }