[syrusakbary]

Part of the SDK fix for #547 (memory kept after Edge.js sandboxes close).

This PR now lands two changes:

1. Retire dedicated Node workers after their task (workerPerThread): the original scope, below.
2. Bound the dead guest memory each pool worker keeps (guestMemoryGcBudget): fix(js): bound the dead guest memory each pool worker keeps #584 was reviewed against this branch and merged into it. Its full description, tests and measurements are in fix(js): bound the dead guest memory each pool worker keeps #584; a summary is below.

Since #582 (the MarkIdle race fix) is now on main, main has been merged back into this branch to resolve the scheduler conflicts (see "Merge with main").

1. Retire dedicated Node workers after their task

Problem

globalThis.__wasmerWorkerPerThread gives every WASIX thread a dedicated worker that should stop when the thread exits. The browser worker does that. On main, the Node worker ignores retireAfterTask, so on Node:

• every guest leaks a worker;
• client close() waits forever for the dedicated workers, which never report retired.

On main, with the global set, 5 hello-world sandboxes leave 6 workers alive and close() never returns.

Change

• node-worker.ts now honours retireAfterTask from init. Once its task settles, it drops its shared objects, frees its SDK state, posts retired and exits. Exiting disposes the isolate together with the guest's memory.
• The adapter forwards retired to the pool only from the thread's exit event. Since fix(js): stop pool workers safely on kill, timeout, and close #578 the pool frees a retired worker's TLS and stack, which is safe only once the thread has stopped.
• Pool shutdown treats a worker that retires on its own like one that exits, instead of waiting out the 2 s deadline.
• New workerPerThread client option, so this mode no longer needs the global. The Swift WebKit SDK keeps setting the global.
• ThreadPool::new takes PoolOptions.

Measurements

macOS arm64, Node 26; issue loop with N=60, median of 3 runs.

	main	workerPerThread: true
plateau RSS	1209 MB	534 MB
idle 3 s RSS	1036 MB	441 MB, no dead guest memory
CPU per sandbox	164 ms	491 ms (a worker start per guest)

This mode is deterministic but expensive, so it stays opt-in. It is also the fallback for workers that cannot run a garbage collection (part 2). With the option on, the issue loop's close() takes 2–4 ms.

2. Bound the dead guest memory each pool worker keeps (from #584)

Each Edge.js run leaves a dead 52 MB shared WebAssembly.Memory in its pool worker, and only that worker's garbage collector can free it. The pool now decides when that happens.

• Budget. Each worker counts the guest memory of the threads it finished. On the pool's post-idle collection message it runs one full GC when one more guest could take the dead memory past guestMemoryGcBudget: default 192 MiB, 0 to disable.
• Idle collection. Otherwise the worker collects after about 1 s idle; any blocking task cancels that collection.
• Collector. Node gets one from Bun.gc, an exposed gc, or --expose-gc set for one throwaway vm context and reset at once, so gc never becomes visible to other code.
• No collector (browsers, frozen V8 flags): the worker asks the pool to retire it instead.
• Existing bug fixed. Every sandbox's main thread is PID 1 / TID 1, so overlapping guests overwrote each other's scheduler entry, and the earlier worker never got its post-idle collection. The scheduler now tracks per worker whether it ran a WASIX thread.

Measurements, with #582 (issue loop, wasmer/edgejs):

	main (before #582)	with #582 and this PR
plateau RSS, N=200	1190 MB	651 MB
max dead guest memory per worker	419 MB	157 MB
idle 3 s RSS (dead guest memories)	964 MB (5)	503 MB (0)
CPU per sandbox	153–164 ms	202–220 ms

Cost. With 52 MB Edge.js guests the budget collects every 3 guests, which costs about +56 ms CPU per sandbox. Most of that falls on the guest right after each GC. It should drop about 5× with the Edge.js build that keeps ICU and builtins out of linear memory (11 MB guests). Not measured: Linux, Windows, Node 24.

Merge with main

Merge commit 7a695e46, the only commit not reviewed in #582 or #584:

• Kept both sides of the two conflicts: the scheduler imports, and the local-only scheduler messages DrainWaitElapsed (fix(js): run back-to-back guests on the worker that just finished #582) and WorkerRetireRequested (fix(js): bound the dead guest memory each pool worker keeps #584).
• draining_workers() now also skips workers in retire_when_idle. Such a worker retires at its next Idle instead of taking the deferred spawn, which would otherwise wait up to 250 ms for it in vain.

Tests (on the merged head 7a695e46)

• node scripts/test-node.mjs: 16 groups, 63/63. This includes fix(js): run back-to-back guests on the worker that just finished #582's back-to-back test and the new worker-per-thread and guest-memory groups (Bun smoke included).
• tests/edgejs-http.test.mjs: 3/3, including "guest code never sees the hook that collects guest memory".
• npm run test:bindgen: pass.
• Wasm size: 5.09 MB raw, under the 5.10 MB budget with little headroom left.

🤖 Generated with Claude Code

[wasmer]

The latest updates on your Wasmer apps. Learn more about Wasmer for Github.

Project	Deployment	Actions	Commit	Updated (UTC)
wasmer-examples-wasmer-sh	Ready	Preview	7a695e4	Nov 7, 2026 8:34pm
wasmer-sh-service-worker	Ready	Preview	7a695e4	Nov 7, 2026 8:34pm