@gjsify/node-gi 0.25.1 → 0.26.0

package/gi.js

@@ -19,7 +19,18 @@ import * as native from './index.js';
 // setImmediate is a Node global but NOT a Deno global (Deno requires the explicit
 // node:timers import; Bun/Node re-export it there too), so import it for the
 // macrotask-deferred runAsync to work on all three runtimes.
-import { setImmediate } from 'node:timers';
+//
+// setInterval/clearInterval come from here for a second, load-bearing reason:
+// the RUNTIME's timers, never `globalThis.setInterval`. A GJS source running
+// through the bridge routinely replaces the global timers with GLib-backed ones
+// (`@gjsify/node-globals/register` swaps them for `GLib.timeout_add` wrappers) —
+// driving the GLib pump off a GLib timeout is a deadlock: the timer that is
+// supposed to dispatch GLib sources is itself a GLib source nobody dispatches.
+import { setImmediate, setInterval, clearInterval } from 'node:timers';
+// Same reasoning for `process`: `globalThis.process` may be the `@gjsify/process`
+// polyfill, whose EventEmitter never emits the runtime's 'beforeExit'. The
+// loop-liveness hooks below must attach to the real one or they silently never fire.
+import runtimeProcess from 'node:process';
 // The GJS Gio DBus surface (Gio.DBus.session/system, own_name/watch_name,
 // Gio.DBusProxy.makeProxyWrapper, Gio.DBusExportedObject) — ported to the L1 model.
 import { createGioDBus } from './overrides/gio-dbus.js';
@@ -977,11 +988,94 @@ function applicationRunAsync(handle) {
 // concurrent runAsync calls share one timer.
 let pumpTimer = null;
 let pumpRefCount = 0;
+// How many of those refs belong to the AUTO-armed pump (requireGi's permanent
+// hold on Bun/Deno). `pumpRefCount > pumpAutoRefs` therefore means an EXPLICIT
+// `startMainContextPump()` caller currently holds the pump.
+let pumpAutoRefs = 0;
+// Whether the pump timer currently HOLDS the runtime's event loop open (ref'd).
+let pumpHoldsRuntime = false;
+
+/** Dispatch every currently-ready GLib source, then return. */
+function drainReadySources() {
+  let guard = 0;
+  while (native.iterateMainContext(false) && guard++ < 100000) {
+    /* drain ready sources */
+  }
+}
+
+// Zero-N-API view over the JS-armed-work counter — `pendingView[0] > 0` is
+// `mainContextHasPending()` as a plain V8 memory read. The IDLE beat must not
+// enter the addon at all: on Deno, a single napi call from the pump tick during
+// the between-test-files GC window reproduces the #47 boxed-handle teardown
+// SIGSEGV (measured on the gtk-smoke leg: a query-only tick crashed 3/3, a tick
+// that never touches the addon exited 0, the full dispatching tick crashed
+// 10/10). So every read on the beat's idle path goes through this view.
+// Created LAZILY on the first pump arm (Bun/Deno only): the @gjsify/napi shim
+// loud-stubs external arraybuffers, and the gjs host never arms the pump.
+let pendingView = null;
+
+/**
+ * One pump beat: dispatch if the program owns GLib work, then re-evaluate the
+ * keep-alive hold. Both the gate and the hold read the SAME counter, so the
+ * auto-armed pump dispatches exactly when it also holds the loop open.
+ *
+ * DISPATCH is gated like the hold — on the program's OWN GLib work. An EXPLICIT
+ * `startMainContextPump()` holder gets unconditional dispatch (its documented
+ * contract: co-pump the context, whatever is in it). The AUTO-armed pump
+ * dispatches only while a JS-armed GI callback is outstanding (scope=async
+ * completions + scope=notified sources), so a FINISHED program stops touching
+ * the addon entirely instead of grinding through GDK/GIO's C-armed housekeeping
+ * sources forever.
+ *
+ * That silence is load-bearing on Deno: the documented #47 N-API teardown race
+ * is armed by the pump ENTERING the addon between test files (see pendingView
+ * above), while stopping/unref'ing the pump at teardown does NOT avoid it.
+ * Nothing is lost for a RUNNING program: any JS-observable progress path is
+ * counted (a Gio completion is scope=async, a `GLib.timeout_add` is
+ * scope=notified), and while one is outstanding the beat drains ALL ready
+ * sources, C-armed ones included.
+ */
+function pumpBeat() {
+  if (pumpRefCount > pumpAutoRefs || pendingView[0] > 0) {
+    drainReadySources();
+  }
+  syncPumpKeepAlive();
+}
+
+/**
+ * Keep-alive accounting — the portable twin of the uv auto-pump's ref/unref
+ * policy (`src/loop.cc`): scheduled GLib work (an armed timeout/idle) or an
+ * in-flight scope=async GI callback holds the runtime's event loop open;
+ * anything else lets it drain.
+ *
+ * Both halves are load-bearing. Permanently UNREF'd (the pre-fix behaviour) a
+ * program whose only pending work lives in GLib dies mid-flight — a bare
+ * `await` on a GLib timeout never settles and the runtime exits 0 with the
+ * program half-run. Permanently REF'd, a sync-only program would never exit.
+ *
+ * Consequence, identical to Node's auto-pump: a REPEATING GLib timeout has
+ * `setInterval` semantics and keeps the process alive, where `gjs -m` exits once
+ * the module settles. That is the one deliberate lifetime divergence from gjs,
+ * and it is now the SAME on node, bun and deno rather than node-only.
+ */
+function syncPumpKeepAlive() {
+  if (pumpTimer === null) return;
+  const hold = pendingView[0] > 0; // zero-N-API — see pendingView above
+  if (hold === pumpHoldsRuntime) return;
+  if (hold) pumpTimer.ref?.();
+  else pumpTimer.unref?.();
+  pumpHoldsRuntime = hold;
+}
 
 /**
  * Start co-pumping the default GLib main context from a runtime timer (Bun/Deno).
  * No-op on Node, where the libuv↔GLib bridge already co-pumps. Reference-counted;
  * returns a disposer that decrements the count (clearing the timer at zero).
+ *
+ * `requireGi` arms this automatically on Bun/Deno (the Node twin of
+ * `native.startMainLoop()`), so a plain `bun bundle.mjs` / `deno run bundle.mjs`
+ * dispatches GLib sources with no explicit loop — calling it by hand is only
+ * needed to hold the pump across a scope that must not depend on that.
  * @returns {() => void}
  */
 export function startMainContextPump() {
@@ -991,18 +1085,17 @@ export function startMainContextPump() {
   if (native.isNodeRuntime || native.RUNTIME === 'gjs') return () => {};
   pumpRefCount++;
   if (pumpTimer === null) {
-    // ~4 ms cadence: low latency without busy-spinning. Each tick drains every
+    if (pendingView === null) pendingView = native.makePumpPendingCount();
+    // ~4 ms cadence: low latency without busy-spinning. Each beat drains every
     // currently-ready source (iterateMainContext(false) returns false when none
-    // remain, bounding the inner loop), then yields to the runtime loop.
-    pumpTimer = setInterval(() => {
-      let guard = 0;
-      while (native.iterateMainContext(false) && guard++ < 100000) {
-        /* drain ready sources */
-      }
-    }, 4);
-    // Don't let the pump alone keep the process alive where the runtime allows it
-    // (Node/Bun expose Timeout.unref; Deno's numeric handle has none).
-    if (typeof pumpTimer.unref === 'function') pumpTimer.unref();
+    // remain, bounding the inner loop) — gated on the program's own GLib work
+    // for the auto-armed pump, see pumpBeat — then re-evaluates the hold.
+    pumpTimer = setInterval(pumpBeat, 4);
+    // Start UNREF'd: the pump alone must never keep a finished program alive.
+    // syncPumpKeepAlive() refs it for exactly as long as GLib has work.
+    pumpTimer.unref?.();
+    pumpHoldsRuntime = false;
+    syncPumpKeepAlive();
   }
   let disposed = false;
   return () => {
@@ -1019,6 +1112,7 @@ export function stopMainContextPump() {
   if (pumpRefCount === 0 && pumpTimer !== null) {
     clearInterval(pumpTimer);
     pumpTimer = null;
+    pumpHoldsRuntime = false;
   }
 }
 
@@ -2309,7 +2403,27 @@ export function requireGi(namespace, version) {
       // 'beforeExit' fires exactly when the loop runs empty: drain what is
       // ready and re-arm — if GLib still has scheduled work, the armed (ref'd)
       // uv timer revives the loop; otherwise the process exits normally.
-      process.on('beforeExit', () => native.pumpKick());
+      runtimeProcess.on('beforeExit', () => native.pumpKick());
+    } else if (native.RUNTIME !== 'gjs') {
+      // Bun/Deno: no libuv to hook, so the portable timer pump IS the auto-pump.
+      // Armed HERE, not left to the caller, so that `bun bundle.mjs` /
+      // `deno run bundle.mjs` behaves like `node bundle.mjs` and `gjs -m`:
+      // GLib sources dispatch with no explicit loop anywhere, and the pump's
+      // keep-alive accounting decides when the process may exit. Leaving it
+      // opt-in is what made the same bundle exit 0 MID-suite on bun/deno while
+      // node ran it to completion.
+      startMainContextPump(); // permanent +1 — the auto-pump is never disposed
+      // Tag that hold as the AUTO pump's: pumpBeat dispatches for it only while
+      // a JS-armed GI callback is outstanding, so a finished program produces
+      // no teardown churn (the deno #47 window) — explicit callers keep
+      // unconditional dispatch.
+      pumpAutoRefs++;
+      // The portable analogue of the Node pump's beforeExit kick. The runtime's
+      // loop just ran empty, which is exactly the moment an unref'd pump would
+      // let the process die with GLib work still outstanding: run one beat —
+      // if the program still owns GLib work it drains + re-refs (reviving the
+      // loop); if not, the beat stays silent and the process exits.
+      runtimeProcess.on('beforeExit', pumpBeat);
     }
     loopAttached = true;
   }

package/index.d.ts

@@ -418,6 +418,27 @@ export function startMainLoop(): void;
  */
 export function iterateMainContext(mayBlock?: boolean): boolean;
 
+/**
+ * Whether the default GLib main context holds work a *pumping* runtime must stay
+ * alive for: a scheduled source (an armed timeout/idle) or an in-flight
+ * scope=async GI callback. Pure GLib — the query half of the keep-alive contract
+ * the L1 `startMainContextPump` uses on Bun/Deno to decide whether its timer
+ * holds the runtime's event loop open. Node reads the same facts inline in the
+ * uv auto-pump.
+ */
+export function mainContextHasPending(): boolean;
+
+/**
+ * Create an `Int32Array(1)` view over the same JS-armed-work counter
+ * `mainContextHasPending()` reads (`view[0] > 0` is equivalent). Reading the
+ * view is a plain memory access — no call into the addon — which the Bun/Deno
+ * pump's idle beat depends on: on Deno, entering the addon from a timer tick
+ * during the between-test-files GC window reproduces the #47 boxed-handle
+ * teardown SIGSEGV. Lazy factory: the @gjsify/napi shim loud-stubs external
+ * arraybuffers and never arms the portable pump, so it must not run at Init.
+ */
+export function makePumpPendingCount(): Int32Array;
+
 /**
  * Drain ready GLib sources + re-arm the auto-pump's libuv wake-ups now (no-op
  * unless {@link startMainLoop} armed the pump on this env). The L1 layer wires
@@ -548,6 +569,8 @@ declare const native: {
   isVariantHandle: typeof isVariantHandle;
   startMainLoop: typeof startMainLoop;
   iterateMainContext: typeof iterateMainContext;
+  mainContextHasPending: typeof mainContextHasPending;
+  makePumpPendingCount: typeof makePumpPendingCount;
   pumpKick: typeof pumpKick;
   setMicrotaskDrain: typeof setMicrotaskDrain;
   connectSignal: typeof connectSignal;

package/index.js

@@ -661,6 +661,35 @@ export const startMainLoop = native.startMainLoop;
  */
 export const iterateMainContext = native.iterateMainContext;
 
+/**
+ * Whether the default GLib main context holds work a *pumping* runtime must stay
+ * alive for: a scheduled source (an armed timeout/idle — the prepare/query
+ * timeout hint is >= 0) or an in-flight scope=async GI callback. Pure GLib —
+ * the companion of {@link iterateMainContext} and the query half of the
+ * keep-alive contract the L1 `startMainContextPump` applies on Bun/Deno (Node
+ * reads the same facts inline in the uv auto-pump). A `false` answer is what
+ * lets a sync-only program exit immediately.
+ * @returns {boolean}
+ */
+export const mainContextHasPending = native.mainContextHasPending;
+
+/**
+ * Create an `Int32Array(1)` view over the SAME JS-armed-work counter
+ * {@link mainContextHasPending} reads — `view[0] > 0` ⇔
+ * `mainContextHasPending()`. The zero-N-API spelling: reading the view is a
+ * plain V8 memory access, no call into the addon. Load-bearing for the Bun/Deno
+ * pump's IDLE beat — on Deno, merely ENTERING the addon from a timer tick
+ * during the between-test-files GC window reproduces the #47 boxed-handle
+ * teardown SIGSEGV (measured: a query-only tick crashed 3/3 where a tick that
+ * never touches the addon exited 0), so the beat must be able to answer "is
+ * there work?" without a single native call. A lazy FACTORY rather than an
+ * Init-time export: the @gjsify/napi shim (the gjs-napi conformance oracle)
+ * loud-stubs `napi_create_external_arraybuffer`, and the gjs host never arms
+ * the portable pump — called only on the first Bun/Deno pump arm.
+ * @returns {Int32Array}
+ */
+export const makePumpPendingCount = native.makePumpPendingCount;
+
 /**
  * Drain ready GLib sources + re-arm the auto-pump's libuv wake-ups NOW (no-op
  * unless {@link startMainLoop} armed the pump, i.e. Node's main env). The L1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",

package/src/addon.cc

@@ -113,6 +113,8 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("isVariantHandle", Napi::Function::New(env, IsVariantHandle));
   exports.Set("startMainLoop", Napi::Function::New(env, StartMainLoop));
   exports.Set("iterateMainContext", Napi::Function::New(env, IterateMainContext));
+  exports.Set("mainContextHasPending", Napi::Function::New(env, MainContextHasPending));
+  exports.Set("makePumpPendingCount", Napi::Function::New(env, MakePumpPendingCount));
   exports.Set("pumpKick", Napi::Function::New(env, PumpKick));
   exports.Set("setMicrotaskDrain", Napi::Function::New(env, SetMicrotaskDrain));
   exports.Set("connectSignal", Napi::Function::New(env, ConnectSignal));

package/src/calls.cc

@@ -28,10 +28,23 @@ struct NodeGiCallback {
   ffi_closure* closure;  // from gi_callable_info_create_closure
   gpointer native;       // executable trampoline address
   GIScopeType scope;
-  // scope=async only: counted in the auto-pump's in-flight keep-alive (the
-  // pending completion keeps the Node process alive, like in-flight Node I/O).
-  // Released exactly once — at the trampoline's single invocation, or at free
-  // if the callback never fired (an error path).
+  // Counted in the auto-pump's in-flight keep-alive — the process stays alive
+  // while JS-armed GLib work is outstanding, like in-flight Node I/O.
+  //   • scope=async    — a one-shot completion (GAsyncReadyCallback), released
+  //     at the trampoline's single invocation.
+  //   • scope=notified — a callback GLib owns until its GDestroyNotify fires:
+  //     `GLib.timeout_add` / `GLib.idle_add` and friends. Released by
+  //     NodeGiCallbackFree, i.e. exactly when GLib drops the source (the
+  //     callback returned SOURCE_REMOVE, or `GLib.Source.remove` killed it).
+  // Either way released exactly once, also at free if it never fired.
+  //
+  // Counting the JS-ARMED sources is the point: a source armed from JS is
+  // program work the process must survive for, while a source armed inside C —
+  // GDK's frame clock, GIO's portal/a11y retries — is library plumbing that
+  // `gjs -m` would never stay alive for either. Keying the keep-alive on "the
+  // context has ANY scheduled source" instead made a finished GTK program
+  // immortal: GDK leaves a ~1 s repeating timeout armed, so the context reports
+  // work forever while nothing is ever ready to dispatch.
   bool pumpCounted = false;
 };
 
@@ -301,10 +314,14 @@ static NodeGiCallback* CreateCallback(Napi::Env env, Napi::Function fn, GICallab
   cb->env = env;
   cb->info = reinterpret_cast<GICallableInfo*>(gi_base_info_ref(callbackInfo));
   cb->scope = scope;
-  // An async-scope callback is a one-shot in-flight operation (GAsyncReadyCallback
-  // et al): count it in the auto-pump keep-alive so the Node process stays alive
-  // until the completion dispatches (no-op off-Node / on non-owner envs).
-  if (scope == GI_SCOPE_TYPE_ASYNC) cb->pumpCounted = NodeGiPumpAsyncBegin(env);
+  // Count the JS-armed GLib work in the auto-pump keep-alive so the process
+  // stays alive until it completes: a one-shot in-flight operation
+  // (GAsyncReadyCallback et al, scope=async) or a source GLib owns until its
+  // destroy-notify (`GLib.timeout_add`/`idle_add`, scope=notified). See the
+  // `pumpCounted` note above for why JS-armed is the right unit.
+  if (scope == GI_SCOPE_TYPE_ASYNC || scope == GI_SCOPE_TYPE_NOTIFIED) {
+    cb->pumpCounted = NodeGiPumpAsyncBegin(env);
+  }
   napi_create_reference(env, fn, 1, &cb->jsFn);
   cb->closure = gi_callable_info_create_closure(callbackInfo, &cb->cif, NodeGiCallbackTrampoline, cb);
   cb->native = gi_callable_info_get_closure_native_address(callbackInfo, cb->closure);

package/src/common.h

@@ -635,6 +635,12 @@ Napi::Value BindingGroupBindFull(const Napi::CallbackInfo& info);
 // loop.cc
 Napi::Value StartMainLoop(const Napi::CallbackInfo& info);
 Napi::Value IterateMainContext(const Napi::CallbackInfo& info);
+Napi::Value MainContextHasPending(const Napi::CallbackInfo& info);
+// Factory for an Int32Array(1) view over the JS-armed-work counter (see
+// loop.cc) — lets the L1 pump answer "does the program own GLib work?" WITHOUT
+// a napi call. Lazy (a factory, not an Init-time export): the @gjsify/napi shim
+// loud-stubs napi_create_external_arraybuffer and never arms the pump.
+Napi::Value MakePumpPendingCount(const Napi::CallbackInfo& info);
 Napi::Value PumpKick(const Napi::CallbackInfo& info);
 Napi::Value SetMicrotaskDrain(const Napi::CallbackInfo& info);
 
@@ -643,8 +649,10 @@ Napi::Value SetMicrotaskDrain(const Napi::CallbackInfo& info);
 // In-flight scope=async keep-alive: while a GI scope=async callback (e.g. a
 // GAsyncReadyCallback) is pending, the pump holds a libuv ref so a plain Node
 // script survives until the completion dispatches (the top-level-await case).
-// Begin returns whether the callback was counted (only on the pump-owning env,
-// i.e. Node's main env after startMainLoop); the caller must call End exactly
+// The counter itself is runtime-independent (Bun/Deno's portable pump reads it
+// via MainContextHasPending); only the libuv ref is Node-only. Begin returns
+// whether the callback was counted (false only for a foreign env, i.e. a worker
+// thread once Node's main env owns the pump); the caller must call End exactly
 // once for each counted callback. Main-thread only.
 bool NodeGiPumpAsyncBegin(napi_env env);
 void NodeGiPumpAsyncEnd();

package/src/loop.cc

@@ -550,14 +550,31 @@ static void PumpArmWakeups() {
     if (g_pump_async_pending > 0 && (timeout < 0 || timeout > 32)) timeout = 32;
   }
 
+  // WAKE-UP and HOLD are separate decisions.
+  //
+  // Wake-up: whenever GLib has a deadline, arm the mirrored uv timer for it, so
+  // libuv's poll sleep ends exactly when GLib next has work.
+  //
+  // Hold (uv_ref): ONLY while JS-armed GLib work is outstanding — the
+  // scope=async/notified counter. Ref'ing whenever a deadline exists (what this
+  // used to do) makes any C-armed toolkit timer immortalize the process: GDK
+  // keeps a ~1 s repeating timeout armed for the process's whole life, so
+  // `node --test test/gtk-smoke.test.mjs` never exited once the GTK stack had
+  // been initialized. `gjs -m` exits when the module settles regardless of what
+  // GLib still has scheduled; keying the hold on the program's OWN outstanding
+  // GLib work is as close to that as a libuv-driven process can get, and it is
+  // what keeps a top-level `await` on a GLib timeout alive (the timeout's
+  // GSourceFunc is a scope=notified callback, counted until GLib drops it).
   if (timeout >= 0) {
     uv_timer_start(&g_pump_timer, PumpTimerCb, static_cast<uint64_t>(timeout), 0);
-    if (!g_pump_timer_reffed) {
-      uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
-      g_pump_timer_reffed = TRUE;
-    }
-  } else if (g_pump_timer_reffed) {
+  } else {
     uv_timer_stop(&g_pump_timer);
+  }
+  const gboolean hold = g_pump_async_pending > 0 && timeout >= 0;
+  if (hold && !g_pump_timer_reffed) {
+    uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
+    g_pump_timer_reffed = TRUE;
+  } else if (!hold && g_pump_timer_reffed) {
     uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_timer));
     g_pump_timer_reffed = FALSE;
   }
@@ -632,15 +649,72 @@ static void PumpInit(uv_loop_t* loop) {
   g_pump_inited = TRUE;
 }
 
+// mainContextHasPending() -> boolean
+//
+// Is there JS-armed GLib work a *pumping* runtime must stay alive for? True
+// while a GI callback the program handed to GLib is outstanding — a scope=async
+// completion (a GAsyncReadyCallback) or a scope=notified source
+// (`GLib.timeout_add`/`idle_add`), counted in calls.cc and released when GLib
+// drops it. The query half of the keep-alive contract for the Bun/Deno pump
+// (L1 `startMainContextPump`); Node reads the same counter inline in
+// PumpArmWakeups and never calls this.
+//
+// It deliberately does NOT ask whether the context has any scheduled source.
+// That probe (`g_main_context_prepare` + `_query`, timeout >= 0) reports the
+// timers a TOOLKIT arms in C as well, and GDK keeps a ~1 s repeating timeout
+// armed for the process's whole life: a finished GTK program then answers
+// "pending" forever while nothing is ever ready to dispatch, and never exits.
+// `gjs -m` would not stay alive for those either — it exits once the module
+// settles. A `false` answer is also what lets a sync-only program exit
+// immediately: the pump alone must never keep a finished program alive.
+Napi::Value MainContextHasPending(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  return Napi::Boolean::New(env, g_pump_async_pending > 0);
+}
+
+// makePumpPendingCount() -> Int32Array(1) OVER g_pump_async_pending (external,
+// zero copy). The JS pump's beat reads this view instead of calling
+// MainContextHasPending(): on Deno, merely ENTERING the addon from the pump's
+// timer tick during the between-test-files GC window reproduces the #47
+// boxed-handle teardown SIGSEGV — measured on the gtk-smoke leg, a query-only
+// tick (one napi call, no dispatch) crashed 3/3 while a tick that never touches
+// the addon exited 0. A typed-array read is a plain JS memory access, so the
+// beat's idle path stays native-silent. No atomics: the counter is written only
+// from the JS thread (Begin/End are main-thread only) and read from JS.
+//
+// A FACTORY, deliberately not created at addon Init: the @gjsify/napi shim
+// (the gjs-napi conformance oracle runs node-gi under it) loud-stubs
+// napi_create_external_arraybuffer, and the gjs host never arms the portable
+// pump — L1 calls this lazily on the first Bun/Deno pump arm, so the stub is
+// never reached where the view is never needed.
+Napi::Value MakePumpPendingCount(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  static_assert(sizeof(g_pump_async_pending) == sizeof(int32_t),
+                "the JS Int32Array view requires a 32-bit counter");
+  // External buffer over static storage — no finalizer needed, the counter
+  // outlives every env.
+  Napi::ArrayBuffer buf =
+      Napi::ArrayBuffer::New(env, &g_pump_async_pending, sizeof(g_pump_async_pending));
+  return Napi::TypedArrayOf<int32_t>::New(env, 1, buf, 0, napi_int32_array);
+}
+
 // In-flight scope=async keep-alive: while any GI scope=async callback (a
 // GAsyncReadyCallback) is pending, REF the (always-active) prepare handle so the
 // libuv loop stays alive until the completion arrives — the exact analogue of
 // Node's own in-flight I/O keeping the process alive, and the reason a plain
 // top-level `await` on a Gio async op settles instead of exiting with an
-// unsettled-TLA error. Main-thread only; counted only for the pump-owning env.
+// unsettled-TLA error.
+//
+// The COUNTER is maintained on every runtime, not just Node: it is the
+// "in-flight async work" half of the keep-alive contract, and Bun/Deno's
+// portable pump reads it through MainContextHasPending() to decide whether its
+// timer holds the runtime's event loop open. Only the uv ref/unref half is
+// Node-only (it needs the uv handles the uv pump owns). Main-thread only —
+// where a pump env is known (Node), a foreign env is not counted.
 bool NodeGiPumpAsyncBegin(napi_env env) {
-  if (!g_pump_inited || env != g_loop_env) return false;
-  if (++g_pump_async_pending == 1 && !g_pump_prepare_reffed) {
+  if (g_loop_env != nullptr && env != g_loop_env) return false;
+  ++g_pump_async_pending;
+  if (g_pump_inited && g_pump_async_pending == 1 && !g_pump_prepare_reffed) {
     uv_ref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = TRUE;
   }
@@ -648,8 +722,9 @@ bool NodeGiPumpAsyncBegin(napi_env env) {
 }
 
 void NodeGiPumpAsyncEnd() {
-  if (!g_pump_inited || g_pump_async_pending == 0) return;
-  if (--g_pump_async_pending == 0 && g_pump_prepare_reffed) {
+  if (g_pump_async_pending == 0) return;
+  --g_pump_async_pending;
+  if (g_pump_inited && g_pump_async_pending == 0 && g_pump_prepare_reffed) {
     uv_unref(reinterpret_cast<uv_handle_t*>(&g_pump_prepare));
     g_pump_prepare_reffed = FALSE;
   }