fix: keep the Worker object rooted until its thread ends, and report the end as nsworkerended

terminate() reset the Worker object's persistent and dropped the registry
entry the moment it was called, while the thread was still winding down: the
wrapper stopped being reachable from native before it had finished, and
anything the worker had already queued on the parent's loop was discarded on
arrival. The root now survives terminate(); it is released by the worker
thread's own last act, which posts the end back to the parent's event loop.

That post no longer only clears. On the parent's thread it dispatches the
internal `nsworkerended` event on the Worker object and only then releases the
persistent and the registry entry, so the end of a worker is observable from
JS for the first time. The node:worker_threads shim listens for it, which is
what lets 'exit' be emitted exactly once for a worker's own close() as much as
for terminate(), and lets terminate() resolve at that point rather than off a
microtask — after every message and error the worker had already sent. A
parent that is itself tearing down clears its children directly and never
delivers the notification, matching iOS.

Android needed neither half of the iOS change's lifetime rework: the wrapper
is shared_ptr-owned by the registry and by the detached thread itself, its
poWorker_ has been a strong Persistent since construction, and the Worker
object is a plain FunctionTemplate instance ObjectManager never sees — so
there was no finalizer resurrection to take it off, and worker-thread posts
already reached the parent through a weak_ptr to its event loop rather than
through its isolate.

Mirrors NativeScript/ios#456.

Author: edusperoni

docs/worker-threads.md

@@ -54,7 +54,7 @@ means deliberately unsupported.
 | `threadName` | shim | Always `undefined`. |
 | `workerData` | shim | Always `null` — see below. |
 | `parentPort` | shim | `null` on the main isolate. Inside a worker, a `MessagePort`-shaped `EventTarget` over the worker's existing parent channel: `postMessage` forwards to the global `postMessage`, `message`/`messageerror` are re-dispatched from the worker global scope, `start()` and `close()` are no-ops. It is **not** a real port: not transferable, no queue of its own. |
-| `Worker` | shim | A class over the runtime's global `Worker` with a small Node-style emitter (`on`/`once`/`off`/`removeListener`) for `message`, `messageerror`, `error`, `online` and `exit`. `postMessage(value, transfer)` and `terminate()` forward. `online` is emitted off a microtask after construction, not from the thread. Unsupported options throw a `TypeError` naming the option: `workerData`, `env`, `eval`, `transferList`, and `stdin`/`stdout`/`stderr` when explicitly truthy. The runtime's own `Worker` options (`androidPriority`) ride along untouched — the native constructor ignores keys it does not know. |
+| `Worker` | shim | A class over the runtime's global `Worker` with a small Node-style emitter (`on`/`once`/`off`/`removeListener`) for `message`, `messageerror`, `error`, `online` and `exit`. `postMessage(value, transfer)` and `terminate()` forward. `online` is emitted off a microtask after construction, not from the thread. `exit` (always code `0`) fires exactly once, when the thread has ended, whether the worker was terminated or ended by its own `close()`; `terminate()` resolves at the same point. Unsupported options throw a `TypeError` naming the option: `workerData`, `env`, `eval`, `transferList`, and `stdin`/`stdout`/`stderr` when explicitly truthy. The runtime's own `Worker` options (`androidPriority`) ride along untouched — the native constructor ignores keys it does not know. |
 | `postMessageToThread` | throws | `Error: postMessageToThread is not supported in this runtime`. |
 | `moveMessagePortToContext` | throws | `Error: moveMessagePortToContext is not supported in this runtime`. |
 | `locks` | absent | Web Locks are not implemented; the property does not exist. |
@@ -72,12 +72,16 @@ Values are cloned on the way in and deserialized fresh on each read, so
 mutating the object you passed does not reach a reader, and two readers never
 share one object.
 
-### `exit` comes only from `terminate()`
+### `exit` fires when the thread has ended, always with code `0`
 
-The runtime has no thread-exit signal — nothing reports that a worker's isolate
-finished. `terminate()` therefore resolves with `0` and emits `exit` with code
-`0` on the way, and that is the only path that emits it. A worker that ends by
-its own `close()` produces no `exit`.
+`exit` is emitted once, from the runtime's end-of-worker notification, so every
+`message` and `error` the worker produced before it ended has been delivered
+first. Node reports the thread's exit code; this runtime has none to report, so
+the code is `0` whichever way the worker ended — `terminate()`, its own
+`close()`, an uncaught error or a missing entry. `terminate()` resolves with
+`0` at the same moment `exit` fires. A parent that is itself tearing down never
+delivers the notification, so a `terminate()` awaited from a dying isolate
+stays pending, as it does in Node when the parent process exits.
 
 ### A worker error carries no `error` object, and the worker scope's `onerror` is not an event
 
@@ -264,3 +268,40 @@ rather than raising a `DataCloneError`, which is long-standing behaviour app
 code relies on. Transfer is not part of that leniency — a port in a worker
 transfer list is validated exactly as it is everywhere else, since degrading a
 transfer would strand the port's sibling.
+
+## Worker lifetime
+
+**A `Worker` is held strongly by the runtime from the moment it is constructed
+until its thread ends**, the way a browser keeps a running worker's handle
+alive. Dropping every reference to one does not stop it: it keeps running, and
+it keeps dispatching `message` and `error` events at the handlers installed on
+it.
+
+```js
+(function () {
+  const worker = new Worker("./worker.js");
+  worker.onmessage = handle;   // still fires; nothing here holds `worker`
+  worker.postMessage("go");
+})();
+```
+
+Being a GC root also means a `Worker` is a well-behaved key: put one in a
+`WeakMap`, `WeakSet` or `WeakRef` and the entry survives for as long as the
+worker runs.
+
+The root is released when the worker ends — `terminate()`, or the worker's own
+`close()`. `terminate()` only starts the wind-down: the object stays rooted
+until the worker thread has actually finished and reported that to the parent.
+From then on the object is collectable like any other, and the runtime drops
+the native side with it. Nothing about a *finished* worker is kept alive.
+
+### `nsworkerended`
+
+When the worker's thread has finished, the runtime dispatches a plain `Event`
+named `nsworkerended` on the `Worker` object. It is **internal and
+non-standard** — the web has no end-of-worker event, and the name is
+deliberately outside the standard namespace. It exists so that
+`node:worker_threads` can report `'exit'` for a worker that ended by its own
+`close()`; app code should not rely on it. The event is best effort: a worker
+whose parent is already tearing down never delivers it, because the parent's
+own teardown disposes the worker anyway.

test-app/app/src/main/assets/app/mainpage.js

@@ -110,6 +110,8 @@ require('./tests/testCreateRequire');
 require('./tests/testNodeUrlModule');
 require('./tests/testImportMetaResolution');
 require('./tests/testWorkerEsmEntry');
+// Worker wrapper reachability across GC (strong while running, collectable after)
+require('./tests/testWorkerLifetime');
 // Fetches from the in-app loopback fixture server, so it goes last
 require('./tests/testEsmHttpLoader');
 // Node-API addon surface

test-app/app/src/main/assets/app/tests/messaging/deadlockChild.js

@@ -0,0 +1,5 @@
+onmessage = function (event) {
+    var port = event.data.port;
+    postMessage(port, [port]);
+    Atomics.store(event.data.flag, 0, 1);
+};

test-app/app/src/main/assets/app/tests/messaging/deadlockParent.js

@@ -0,0 +1,13 @@
+// Leaves a message that carries a port on this worker's own loop, undrained,
+// at the moment the parent terminates it: the port's sibling is port1, owned
+// by this worker. Spinning inside a timer callback keeps the loop from
+// draining while still letting terminate() interrupt the JS.
+var channel = new MessageChannel();
+var child = new Worker("./deadlockChild.js");
+var flag = new Int32Array(new SharedArrayBuffer(4));
+child.postMessage({ port: channel.port2, flag: flag }, [channel.port2]);
+setTimeout(function () {
+    while (Atomics.load(flag, 0) === 0) {}
+    postMessage("ready");
+    for (;;) {}
+}, 0);