@volter/world-runtime 3.0.55 → 3.0.57

package/dist/src/consumers.d.ts

@@ -21,6 +21,15 @@ export declare function createConsumer(root: string, name: string, instanceCreat
 }): WorldConsumer;
 export declare function refreshConsumer(root: string, name: string, record: WorldConsumer): void;
 export declare function releaseConsumer(root: string, name: string, record: WorldConsumer): void;
+export type ConsumerProcessState = {
+    state: 'present' | 'absent';
+} | {
+    state: 'unknown';
+    reason: string;
+};
+/** Signal delivery cannot prove existence. Only a successful signal-0 probe or ESRCH
+ * answers it; permission and registry errors retain uncertainty, never cleanup authority. */
+export declare function consumerProcessState(pid: number): ConsumerProcessState;
 /** Inspection never deletes records or interprets incomplete coverage as no consumers. */
 export declare function worldConsumers(root: string, name: string, instanceCreatedAt?: string): {
     consumers: (WorldConsumer & {

package/dist/src/consumers.js

@@ -80,15 +80,18 @@ export function releaseConsumer(root, name, record) {
         rmSync(join(dir, `${record.id}.json`), { force: true });
     }
 }
-function alive(pid) {
-    if (!pid)
-        return false;
+/** Signal delivery cannot prove existence. Only a successful signal-0 probe or ESRCH
+ * answers it; permission and registry errors retain uncertainty, never cleanup authority. */
+export function consumerProcessState(pid) {
     try {
         process.kill(pid, 0);
-        return true;
+        return { state: 'present' };
     }
     catch (error) {
-        return error.code !== 'ESRCH';
+        const cause = error;
+        if (cause?.code === 'ESRCH')
+            return { state: 'absent' };
+        return { state: 'unknown', reason: cause?.code ?? cause?.message ?? String(error) };
     }
 }
 /** Inspection never deletes records or interprets incomplete coverage as no consumers. */
@@ -131,10 +134,18 @@ export function worldConsumers(root, name, instanceCreatedAt) {
             checkedOwner(r.owner);
             const age = Date.now() - Date.parse(r.heartbeatAt);
             const sameInstance = instanceCreatedAt === r.instanceCreatedAt;
-            const state = r.retirementUncertain || r.hostname !== hostname() || !sameInstance ? 'uncertain'
-                : !alive(r.runnerPid) && r.consumerPid === undefined ? 'uncertain'
-                    : !alive(r.runnerPid) && !alive(r.consumerPid) ? (r.completionRequired ? 'uncertain' : 'exited')
-                        : alive(r.runnerPid) && age >= -STALE_MS && age <= STALE_MS ? 'active' : 'uncertain';
+            // Never interpret another host's numeric PIDs as processes on this host.
+            const local = r.hostname === hostname() && sameInstance;
+            const runner = local ? consumerProcessState(r.runnerPid) : undefined;
+            const command = local && r.consumerPid !== undefined ? consumerProcessState(r.consumerPid) : undefined;
+            if (runner?.state === 'unknown')
+                warnings.push(`Consumer ${r.id}: runner ${r.runnerPid} existence unknown (${runner.reason}).`);
+            if (command?.state === 'unknown')
+                warnings.push(`Consumer ${r.id}: command ${r.consumerPid} existence unknown (${command.reason}).`);
+            const state = r.retirementUncertain || !local || runner?.state === 'unknown' || command?.state === 'unknown' ? 'uncertain'
+                : runner?.state === 'absent' && r.consumerPid === undefined ? 'uncertain'
+                    : runner?.state === 'absent' && command?.state === 'absent' ? (r.completionRequired ? 'uncertain' : 'exited')
+                        : runner?.state === 'present' && age >= -STALE_MS && age <= STALE_MS ? 'active' : 'uncertain';
             // Explicit fields only: malformed records must never leak arbitrary metadata into reports.
             consumers.push({ id: r.id, instanceCreatedAt: r.instanceCreatedAt, kind: r.kind, owner: r.owner,
                 uid: r.uid, hostname: r.hostname, runnerPid: r.runnerPid, consumerPid: r.consumerPid,

package/dist/src/runtime.js

@@ -38,7 +38,7 @@ import { readAppUrl } from "./app-url.js";
 import { inertInjectEnvWarnings } from "./inject-map.js";
 import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from "./redirect-proxy.js";
 import { CaTrustError, sessionTrustEnv } from "./ca-trust.js";
-import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers } from "./consumers.js";
+import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers, consumerProcessState } from "./consumers.js";
 import { assertLifecycleStartable, beginWorldLifecycle, handoffWorldLifecycle, recordWorldLifecycleEvent, releaseWorldLifecycle, retainWorldLifecycleForCleanup, hasWorldLifecycle, isWorldLifecycleRunning, lifecycleLogPath, releaseAbandonedWorldLifecycle, exitedWorldLifecyclePids } from "./lifecycle-record.js";
 // Births captured at actual spawn; retries never remeasure a retained PID.
 const spawnedIdentities = new Map();
@@ -510,6 +510,15 @@ function injectPreloadSpecifier() {
     // resolved on use: importing the runtime has no side effects in a host without module resolution
     return createRequire(import.meta.url).resolve('@volter/world-core/inject');
 }
+/** A World's NODE_OPTIONS: its own injector, then the launcher's options without an outer World's injector. One
+ * injector per process (the innermost World's, which already routes on to the outer World's twins); a second one
+ * patches the same doors twice, and tools that re-serialize NODE_OPTIONS (Next.js's build workers) merge the two
+ * `--require` paths into one filename. */
+function worldNodeOptions(inherited) {
+    const own = `--require ${injectPreloadSpecifier()}`;
+    const rest = (inherited ?? '').replace(/(^|\s)(?:--require|-r)[ =]\S*[\\/]world-core[\\/]inject\.cjs(?=\s|$)/g, ' ').trim();
+    return rest ? `${own} ${rest}` : own;
+}
 function writeProxyEnv(root, name, env) {
     writeTextAtomic(proxyEnvFile(root, name), `${JSON.stringify(env, null, 2)}\n`);
 }
@@ -2162,7 +2171,7 @@ export async function upWorld(configId, options = {}, abort) {
             // non-loopback host once this is set. Without it "sealed" only records intent and every
             // untwinned host is blind-tunneled to the real internet (TWIN-60).
             ...(mode === 'sealed' ? { VOLTER_WORLD_SEALED: '1', VOLTER_TWIN_STRICT_EGRESS: '1' } : {}),
-            NODE_OPTIONS: `--require ${injectPreloadSpecifier()}${inheritedEnv.NODE_OPTIONS ? ` ${inheritedEnv.NODE_OPTIONS}` : ''}`,
+            NODE_OPTIONS: worldNodeOptions(inheritedEnv.NODE_OPTIONS),
         };
         env.NO_PROXY = `127.0.0.1,localhost${env.NO_PROXY || inheritedEnv.NO_PROXY ? `,${env.NO_PROXY ?? inheritedEnv.NO_PROXY}` : ''}`;
         env.no_proxy = `127.0.0.1,localhost${env.no_proxy || inheritedEnv.no_proxy ? `,${env.no_proxy ?? inheritedEnv.no_proxy}` : ''}`;
@@ -3822,24 +3831,23 @@ export function retireWorldConsumers(name, root = process.cwd(), options = {}) {
         const chosen = consumers.filter(c => c.state === 'uncertain' && (options.consumer === undefined || c.id === options.consumer));
         if (options.consumer !== undefined && chosen.length === 0)
             throw new Error(`World "${name}" has no uncertain consumer ${options.consumer}`);
-        const gone = (pid) => { try {
-            process.kill(pid, 0);
-            return false;
-        }
-        catch (error) {
-            return error.code === 'ESRCH';
-        } };
         return chosen.map((c) => {
             const keep = (reason) => ({ id: c.id, owner: c.owner, retired: false, reason });
             if (c.hostname !== osHostname())
                 return keep(`recorded on host ${c.hostname}; retire it there`);
             if (c.instanceCreatedAt !== current.createdAt)
                 return keep('belongs to another instance of this World');
-            if (!gone(c.runnerPid))
+            const runner = consumerProcessState(c.runnerPid);
+            if (runner.state === 'unknown')
+                return keep(`runner ${c.runnerPid} existence is unknown (${runner.reason})`);
+            if (runner.state === 'present')
                 return keep(`runner ${c.runnerPid} is still alive`);
             if (c.consumerPid === undefined)
                 return keep('its command was never recorded as started, so its processes cannot be proven gone');
-            if (!gone(c.consumerPid))
+            const command = consumerProcessState(c.consumerPid);
+            if (command.state === 'unknown')
+                return keep(`command ${c.consumerPid} existence is unknown (${command.reason})`);
+            if (command.state === 'present')
                 return keep(`command ${c.consumerPid} is still alive`);
             const surviving = survivingOwnedGroups([c.consumerPid]);
             if (surviving.length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.55",
+  "version": "3.0.57",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.55",
-    "@volter/world-console": "3.0.50"
+    "@volter/world-core": "3.0.57",
+    "@volter/world-console": "3.0.52"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.55",
+    "@volter/world-core": "3.0.57",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/consumers.ts

@@ -91,10 +91,17 @@ export function releaseConsumer(root: string, name: string, record: WorldConsume
   } finally { rmSync(join(dir, `${record.id}.json`), { force: true }); }
 }
 
-function alive(pid: number | undefined): boolean {
-  if (!pid) return false;
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return (error as NodeJS.ErrnoException).code !== 'ESRCH'; }
+export type ConsumerProcessState = { state: 'present' | 'absent' } | { state: 'unknown'; reason: string };
+
+/** Signal delivery cannot prove existence. Only a successful signal-0 probe or ESRCH
+ * answers it; permission and registry errors retain uncertainty, never cleanup authority. */
+export function consumerProcessState(pid: number): ConsumerProcessState {
+  try { process.kill(pid, 0); return { state: 'present' }; }
+  catch (error) {
+    const cause = error as NodeJS.ErrnoException;
+    if (cause?.code === 'ESRCH') return { state: 'absent' };
+    return { state: 'unknown', reason: cause?.code ?? cause?.message ?? String(error) };
+  }
 }
 
 /** Inspection never deletes records or interprets incomplete coverage as no consumers. */
@@ -126,10 +133,16 @@ export function worldConsumers(root: string, name: string, instanceCreatedAt?: s
       checkedOwner(r.owner);
       const age = Date.now() - Date.parse(r.heartbeatAt);
       const sameInstance = instanceCreatedAt === r.instanceCreatedAt;
-      const state = r.retirementUncertain || r.hostname !== hostname() || !sameInstance ? 'uncertain'
-        : !alive(r.runnerPid) && r.consumerPid === undefined ? 'uncertain'
-          : !alive(r.runnerPid) && !alive(r.consumerPid) ? (r.completionRequired ? 'uncertain' : 'exited')
-          : alive(r.runnerPid) && age >= -STALE_MS && age <= STALE_MS ? 'active' : 'uncertain';
+      // Never interpret another host's numeric PIDs as processes on this host.
+      const local = r.hostname === hostname() && sameInstance;
+      const runner = local ? consumerProcessState(r.runnerPid) : undefined;
+      const command = local && r.consumerPid !== undefined ? consumerProcessState(r.consumerPid) : undefined;
+      if (runner?.state === 'unknown') warnings.push(`Consumer ${r.id}: runner ${r.runnerPid} existence unknown (${runner.reason}).`);
+      if (command?.state === 'unknown') warnings.push(`Consumer ${r.id}: command ${r.consumerPid} existence unknown (${command.reason}).`);
+      const state = r.retirementUncertain || !local || runner?.state === 'unknown' || command?.state === 'unknown' ? 'uncertain'
+        : runner?.state === 'absent' && r.consumerPid === undefined ? 'uncertain'
+          : runner?.state === 'absent' && command?.state === 'absent' ? (r.completionRequired ? 'uncertain' : 'exited')
+          : runner?.state === 'present' && age >= -STALE_MS && age <= STALE_MS ? 'active' : 'uncertain';
       // Explicit fields only: malformed records must never leak arbitrary metadata into reports.
       consumers.push({ id: r.id, instanceCreatedAt: r.instanceCreatedAt, kind: r.kind, owner: r.owner,
         uid: r.uid, hostname: r.hostname, runnerPid: r.runnerPid, consumerPid: r.consumerPid,

package/src/runtime.ts

@@ -41,7 +41,7 @@ import { inertInjectEnvWarnings } from './inject-map.ts';
 import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from './redirect-proxy.ts';
 import { CaTrustError, sessionTrustEnv, type CaTrustInputs } from './ca-trust.ts';
 import type { WorldConfig, WorldExternalReadyWhen, WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome, WorldRunRecord, WorldServiceConfig, WorldServiceInstance } from './schema.ts';
-import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers } from './consumers.ts';
+import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers, consumerProcessState } from './consumers.ts';
 import { assertLifecycleStartable, beginWorldLifecycle, handoffWorldLifecycle, recordWorldLifecycleEvent, releaseWorldLifecycle, retainWorldLifecycleForCleanup, hasWorldLifecycle, isWorldLifecycleRunning, lifecycleLogPath, releaseAbandonedWorldLifecycle, exitedWorldLifecyclePids } from './lifecycle-record.ts';
 
 // Births captured at actual spawn; retries never remeasure a retained PID.
@@ -553,6 +553,16 @@ function injectPreloadSpecifier(): string {
   return createRequire(import.meta.url).resolve('@volter/world-core/inject');
 }
 
+/** A World's NODE_OPTIONS: its own injector, then the launcher's options without an outer World's injector. One
+ * injector per process (the innermost World's, which already routes on to the outer World's twins); a second one
+ * patches the same doors twice, and tools that re-serialize NODE_OPTIONS (Next.js's build workers) merge the two
+ * `--require` paths into one filename. */
+function worldNodeOptions(inherited: string | undefined): string {
+  const own = `--require ${injectPreloadSpecifier()}`;
+  const rest = (inherited ?? '').replace(/(^|\s)(?:--require|-r)[ =]\S*[\\/]world-core[\\/]inject\.cjs(?=\s|$)/g, ' ').trim();
+  return rest ? `${own} ${rest}` : own;
+}
+
 function writeProxyEnv(root: string, name: string, env: Record<string, string>): void {
   writeTextAtomic(proxyEnvFile(root, name), `${JSON.stringify(env, null, 2)}\n`);
 }
@@ -2049,7 +2059,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       // non-loopback host once this is set. Without it "sealed" only records intent and every
       // untwinned host is blind-tunneled to the real internet (TWIN-60).
       ...(mode === 'sealed' ? { VOLTER_WORLD_SEALED: '1', VOLTER_TWIN_STRICT_EGRESS: '1' } : {}),
-      NODE_OPTIONS: `--require ${injectPreloadSpecifier()}${inheritedEnv.NODE_OPTIONS ? ` ${inheritedEnv.NODE_OPTIONS}` : ''}`,
+      NODE_OPTIONS: worldNodeOptions(inheritedEnv.NODE_OPTIONS),
     };
     env.NO_PROXY = `127.0.0.1,localhost${env.NO_PROXY || inheritedEnv.NO_PROXY ? `,${env.NO_PROXY ?? inheritedEnv.NO_PROXY}` : ''}`;
     env.no_proxy = `127.0.0.1,localhost${env.no_proxy || inheritedEnv.no_proxy ? `,${env.no_proxy ?? inheritedEnv.no_proxy}` : ''}`;
@@ -3618,14 +3628,17 @@ export function retireWorldConsumers(name: string, root = process.cwd(), options
     const { consumers } = worldConsumers(resolvedRoot, name, current.createdAt);
     const chosen = consumers.filter(c => c.state === 'uncertain' && (options.consumer === undefined || c.id === options.consumer));
     if (options.consumer !== undefined && chosen.length === 0) throw new Error(`World "${name}" has no uncertain consumer ${options.consumer}`);
-    const gone = (pid: number) => { try { process.kill(pid, 0); return false; } catch (error) { return (error as NodeJS.ErrnoException).code === 'ESRCH'; } };
     return chosen.map((c): ConsumerRetirement => {
       const keep = (reason: string): ConsumerRetirement => ({ id: c.id, owner: c.owner, retired: false, reason });
       if (c.hostname !== osHostname()) return keep(`recorded on host ${c.hostname}; retire it there`);
       if (c.instanceCreatedAt !== current.createdAt) return keep('belongs to another instance of this World');
-      if (!gone(c.runnerPid)) return keep(`runner ${c.runnerPid} is still alive`);
+      const runner = consumerProcessState(c.runnerPid);
+      if (runner.state === 'unknown') return keep(`runner ${c.runnerPid} existence is unknown (${runner.reason})`);
+      if (runner.state === 'present') return keep(`runner ${c.runnerPid} is still alive`);
       if (c.consumerPid === undefined) return keep('its command was never recorded as started, so its processes cannot be proven gone');
-      if (!gone(c.consumerPid)) return keep(`command ${c.consumerPid} is still alive`);
+      const command = consumerProcessState(c.consumerPid);
+      if (command.state === 'unknown') return keep(`command ${c.consumerPid} existence is unknown (${command.reason})`);
+      if (command.state === 'present') return keep(`command ${c.consumerPid} is still alive`);
       const surviving = survivingOwnedGroups([c.consumerPid]);
       if (surviving.length) return keep(`process group ${c.consumerPid} still has live members`);
       removeConsumerRecord(resolvedRoot, name, c.id);