@volter/world-runtime 2.0.24 → 2.0.26

package/dist/src/host-cli.js

@@ -13,6 +13,7 @@ import { keepProcessAlive } from '@volter/world-core/lifecycle';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { startColocatedHost } from "./host.js";
+import { publishHostReady } from "./host-ready.js";
 const argv = process.argv.slice(2);
 const opt = (name, fb = '') => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fb; };
 const isolation = opt('--isolation', 'shared');
@@ -85,10 +86,20 @@ const host = await startColocatedHost(specs, {
             recordGaveUp(e.twin, e.exits ?? 0, e.detail ?? '');
     },
 });
-for (const [id, port] of Object.entries(host.ports))
-    process.stdout.write(`ready id=${id} port=${port}\n`);
-process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 const shutdown = async () => { await host.stop(); process.exit(0); };
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
+const readyFile = opt('--ready-file');
+if (readyFile) {
+    try {
+        publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports);
+    }
+    catch (error) {
+        await host.stop();
+        throw error;
+    }
+}
+for (const [id, port] of Object.entries(host.ports))
+    process.stdout.write(`ready id=${id} port=${port}\n`);
+process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 await keepProcessAlive();

package/dist/src/host-ready.d.ts

@@ -0,0 +1,4 @@
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export declare function publishHostReady(path: string, boot: string, ports: Record<string, number>): void;
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export declare function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void>;

package/dist/src/host-ready.js

@@ -0,0 +1,48 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export function publishHostReady(path, boot, ports) {
+    if (!boot)
+        throw new Error('A co-located host readiness receipt requires its World boot identity.');
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export async function waitForHostReady(path, boot, ports, timeoutMs, abort) {
+    const started = Date.now();
+    for (;;) {
+        abort.throwIfAborted();
+        let bytes;
+        try {
+            bytes = readFileSync(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (bytes) {
+            if (bytes.byteLength > 256 * 1024)
+                throw new Error('The co-located host readiness receipt exceeds its bounds.');
+            const value = JSON.parse(bytes.toString('utf8'));
+            if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
+                throw new Error('The co-located host readiness receipt does not belong to this boot.');
+            }
+            const answered = value.ports;
+            if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
+                throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+            }
+            return;
+        }
+        if (Date.now() - started >= timeoutMs)
+            throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+        await new Promise((resolve, reject) => {
+            const cancel = () => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
+            const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
+            abort.addEventListener('abort', cancel, { once: true });
+            if (abort.aborted)
+                cancel();
+        });
+    }
+}

package/dist/src/host.js

@@ -23,6 +23,7 @@ import { Worker } from 'node:worker_threads';
 import { siblingScript } from "./sibling.js";
 import { importModule } from "./import-module.js";
 import { pathToFileURL } from 'node:url';
+import { parallelStartup } from "./startup.js";
 async function loadFactory(spec) {
     const mod = await importModule(spec.module);
     const factory = mod[spec.export];
@@ -60,26 +61,50 @@ export async function startColocatedHost(specs, options = {}) {
         process.on('unhandledRejection', onRejection);
         process.on('uncaughtException', onUncaught);
         const servers = [];
-        for (const spec of specs) {
-            const factory = await loadFactory(spec);
-            servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
+        const stop = async () => {
+            process.off('unhandledRejection', onRejection);
+            process.off('uncaughtException', onUncaught);
+            const stopped = await Promise.allSettled(servers.map(async (server) => {
+                let timeout;
+                try {
+                    await Promise.race([
+                        Promise.resolve().then(() => server.stop()),
+                        new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error(`Twin on port ${server.port} did not stop within ${STOP_TIMEOUT_MS} ms.`)), STOP_TIMEOUT_MS); }),
+                    ]);
+                }
+                finally {
+                    if (timeout !== undefined)
+                        clearTimeout(timeout);
+                }
+            }));
+            return stopped.filter((result) => result.status === 'rejected').map((result) => result.reason);
+        };
+        try {
+            await parallelStartup(specs, async (spec) => {
+                const factory = await loadFactory(spec);
+                const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
+                // Record the handle before validating it, so rollback also owns a bad factory result.
+                servers.push(server);
+                if (!Number.isInteger(server.port) || server.port < 1 || server.port > 65535 || (spec.port !== 0 && server.port !== spec.port)) {
+                    throw new Error(`Twin "${spec.id}" bound port ${server.port}, requested ${spec.port}.`);
+                }
+                ports[spec.id] = server.port;
+            });
+        }
+        catch (error) {
+            const cleanup = await stop();
+            if (cleanup.length)
+                throw new AggregateError([error, ...cleanup], 'Co-located host startup and rollback failed.');
+            throw error;
         }
         return {
             isolation,
             ports,
             stop: async () => {
-                process.off('unhandledRejection', onRejection);
-                process.off('uncaughtException', onUncaught);
-                // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
-                // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
-                // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
-                // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
-                // cleanup throws on a failed container removal — left siblings unstopped and the host
-                // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
-                await Promise.allSettled(servers.map((s) => Promise.race([
-                    Promise.resolve().then(() => s.stop()),
-                    new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
-                ])));
+                // Every stop runs, even when a sibling hangs or throws. Host shutdown
+                // still resolves within its budget so the owning runtime can retire it.
+                for (const error of await stop())
+                    onEvent({ twin: '(host)', kind: 'stop-failed', detail: String(error) });
             },
         };
     }
@@ -96,6 +121,11 @@ export async function startColocatedHost(specs, options = {}) {
         let ready = false;
         worker.on('message', (msg) => {
             if (msg?.type === 'ready') {
+                if (typeof msg.port !== 'number' || !Number.isInteger(msg.port) || msg.port < 1 || msg.port > 65535 || (spec.port !== 0 && msg.port !== spec.port)) {
+                    rejectReady(new Error(`Twin "${spec.id}" bound port ${msg.port}, requested ${spec.port}.`));
+                    return;
+                }
+                ports[spec.id] = msg.port;
                 ready = true;
                 resolveReady();
             }
@@ -107,6 +137,8 @@ export async function startColocatedHost(specs, options = {}) {
         });
         worker.on('exit', (code) => {
             workers.delete(spec.id);
+            if (!ready)
+                rejectReady(new Error(`Twin "${spec.id}" exited before readiness (code ${code}).`));
             if (stopping.value || code === 0)
                 return;
             // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
@@ -115,8 +147,17 @@ export async function startColocatedHost(specs, options = {}) {
         });
         workers.set(spec.id, worker);
     });
-    for (const spec of specs)
-        await spawnWorker(spec);
+    try {
+        await parallelStartup(specs, async (spec) => spawnWorker(spec));
+    }
+    catch (error) {
+        stopping.value = true;
+        const stopped = await Promise.allSettled([...workers.values()].map((worker) => worker.terminate()));
+        const cleanup = stopped.filter((result) => result.status === 'rejected').map((result) => result.reason);
+        if (cleanup.length)
+            throw new AggregateError([error, ...cleanup], 'Co-located worker startup and rollback failed.');
+        throw error;
+    }
     return {
         isolation,
         ports,

package/dist/src/runtime.js

@@ -1,5 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
+import { parallelStartup } from "./startup.js";
+import { waitForHostReady } from "./host-ready.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
 import { spawn, spawnSync } from 'node:child_process';
@@ -110,16 +112,25 @@ async function untilReadyOrEnded(wait, ended, boot, what, log) {
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port, boot, ended, twin, what, log, early = false) {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port, boot, ended, twin, what, log, early = false, sharedSettle) {
     // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
     boot.signal.throwIfAborted();
     const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
     const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' : new Promise(() => undefined))) : new Promise(() => undefined);
     // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
     if (ended) {
-        const settled = await Promise.race([own, ended.then(() => 'ended'), new Promise((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+        let timer;
+        let settled;
+        try {
+            const settle = sharedSettle ?? new Promise((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+            settled = await Promise.race([own, ended.then(() => 'ended'), settle]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
         boot.signal.throwIfAborted();
         if (settled === 'own')
             return;
@@ -1304,8 +1315,11 @@ function versionSatisfies(actual, pin) {
  * all share the host child's pid — so pids/instance.json/downWorld need no special casing.
  */
 async function startColocatedServices(config, colocated, isolation, worldEnv, paths, allocatedPorts, boot) {
+    if (colocated.length === 0)
+        return [];
     const hostCli = siblingScript(import.meta.url, 'host-cli');
-    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+    const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
     const allocated = [];
     for (const service of colocated) {
         const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1341,7 +1355,17 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         exitState.value = { code, signal };
     });
     const command = [process.execPath, ...args];
-    for (const { service, port } of allocated) {
+    const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+    await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+        if (undeadPids([child.pid]).length)
+            recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+        try {
+            process.kill(-child.pid, 'SIGTERM');
+        }
+        catch { /* best effort cleanup */ }
+        throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
+    await parallelStartup(allocated, async ({ service, port }) => {
         const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
         await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
             if (undeadPids([child.pid]).length)
@@ -1352,19 +1376,28 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             catch { /* best effort cleanup */ }
             throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
         });
-    }
-    for (const [index, { service, port }] of allocated.entries()) {
-        // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-        await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-            if (undeadPids([child.pid]).length)
-                recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-            try {
-                process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* best effort cleanup */ }
-            throw error;
+    });
+    let hostSettleTimer;
+    const hostSettle = new Promise((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+    try {
+        await parallelStartup(allocated, async ({ service, port }) => {
+            // The host has completed every start. Each matching boot answer can now
+            // end its own settle; legacy twins share one full host guard.
+            await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+                if (undeadPids([child.pid]).length)
+                    recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch { /* best effort cleanup */ }
+                throw error;
+            });
         });
     }
+    finally {
+        if (hostSettleTimer !== undefined)
+            clearTimeout(hostSettleTimer);
+    }
     if (exitState.value !== null) {
         throw new Error(`The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
             + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`);

package/dist/src/startup.d.ts

@@ -0,0 +1,2 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export declare function parallelStartup<T>(items: readonly T[], start: (item: T, index: number) => Promise<void>): Promise<void>;

package/dist/src/startup.js

@@ -0,0 +1,24 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export async function parallelStartup(items, start) {
+    let next = 0;
+    let failed = false;
+    const errors = [];
+    await Promise.all(Array.from({ length: Math.min(8, items.length) }, async () => {
+        while (!failed) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            try {
+                await start(items[index], index);
+            }
+            catch (error) {
+                failed = true;
+                errors.push(error);
+            }
+        }
+    }));
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, 'Independent World startup operations failed.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.24",
+  "version": "2.0.26",
   "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",

package/src/host-cli.ts

@@ -13,6 +13,7 @@ import { keepProcessAlive } from '@volter/world-core/lifecycle';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { startColocatedHost, type ColocatedTwinSpec, type HostIsolation } from './host.ts';
+import { publishHostReady } from './host-ready.ts';
 
 const argv = process.argv.slice(2);
 const opt = (name: string, fb = ''): string => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1]! : fb; };
@@ -83,10 +84,14 @@ const host = await startColocatedHost(specs, {
     if (e.kind === 'gaveup') recordGaveUp(e.twin, e.exits ?? 0, e.detail ?? '');
   },
 });
-for (const [id, port] of Object.entries(host.ports)) process.stdout.write(`ready id=${id} port=${port}\n`);
-process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
-
 const shutdown = async () => { await host.stop(); process.exit(0); };
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
+const readyFile = opt('--ready-file');
+if (readyFile) {
+  try { publishHostReady(readyFile, process.env.VOLTER_WORLD_BOOT_ID ?? '', host.ports); }
+  catch (error) { await host.stop(); throw error; }
+}
+for (const [id, port] of Object.entries(host.ports)) process.stdout.write(`ready id=${id} port=${port}\n`);
+process.stdout.write(`host ready (${specs.length} twins, isolation=${isolation})\n`);
 await keepProcessAlive();

package/src/host-ready.ts

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
+export function publishHostReady(path: string, boot: string, ports: Record<string, number>): void {
+  if (!boot) throw new Error('A co-located host readiness receipt requires its World boot identity.');
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports })}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+/** Receipt admission is finite and cancellation-aware; stale or malformed state is never readiness. */
+export async function waitForHostReady(path: string, boot: string, ports: ReadonlyMap<string, number>, timeoutMs: number, abort: AbortSignal): Promise<void> {
+  const started = Date.now();
+  for (;;) {
+    abort.throwIfAborted();
+    let bytes: Buffer | undefined;
+    try { bytes = readFileSync(path); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    if (bytes) {
+      if (bytes.byteLength > 256 * 1024) throw new Error('The co-located host readiness receipt exceeds its bounds.');
+      const value = JSON.parse(bytes.toString('utf8')) as { version?: unknown; boot?: unknown; ports?: unknown } | null;
+      if (!value || value.version !== 1 || value.boot !== boot || !value.ports || typeof value.ports !== 'object' || Array.isArray(value.ports)) {
+        throw new Error('The co-located host readiness receipt does not belong to this boot.');
+      }
+      const answered = value.ports as Record<string, unknown>;
+      if (Object.keys(answered).length !== ports.size || [...ports].some(([id, port]) => !Object.hasOwn(answered, id) || answered[id] !== port)) {
+        throw new Error('The co-located host readiness receipt does not cover its declared ports.');
+      }
+      return;
+    }
+    if (Date.now() - started >= timeoutMs) throw new Error(`The co-located host did not complete every declared start within ${timeoutMs} ms.`);
+    await new Promise<void>((resolve, reject) => {
+      const cancel = (): void => { clearTimeout(timer); abort.removeEventListener('abort', cancel); reject(abort.reason); };
+      const timer = setTimeout(() => { abort.removeEventListener('abort', cancel); resolve(); }, Math.min(25, Math.max(1, timeoutMs - (Date.now() - started))));
+      abort.addEventListener('abort', cancel, { once: true });
+      if (abort.aborted) cancel();
+    });
+  }
+}

package/src/host.ts

@@ -23,6 +23,7 @@ import { Worker } from 'node:worker_threads';
 import { siblingScript } from './sibling.ts';
 import { importModule } from './import-module.ts';
 import { pathToFileURL } from 'node:url';
+import { parallelStartup } from './startup.ts';
 
 /** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
  *  factory (every pack ships one, e.g. `createStripeTwinServer`). `module` is anything import()
@@ -104,28 +105,43 @@ export async function startColocatedHost(
     process.on('uncaughtException', onUncaught);
 
     const servers: TwinServer[] = [];
-    for (const spec of specs) {
-      const factory = await loadFactory(spec);
-      servers.push(await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) }));
+    const stop = async (): Promise<unknown[]> => {
+      process.off('unhandledRejection', onRejection);
+      process.off('uncaughtException', onUncaught);
+      const stopped = await Promise.allSettled(servers.map(async (server) => {
+        let timeout: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await Promise.race([
+            Promise.resolve().then(() => server.stop()),
+            new Promise<never>((_, reject) => { timeout = setTimeout(() => reject(new Error(`Twin on port ${server.port} did not stop within ${STOP_TIMEOUT_MS} ms.`)), STOP_TIMEOUT_MS); }),
+          ]);
+        } finally { if (timeout !== undefined) clearTimeout(timeout); }
+      }));
+      return stopped.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason);
+    };
+    try {
+      await parallelStartup(specs, async (spec) => {
+        const factory = await loadFactory(spec);
+        const server = await factory({ port: spec.port, root: spec.root, readOnly: spec.readOnly, ...(spec.scenarioPath !== undefined ? { scenarioPath: spec.scenarioPath } : {}), ...(spec.database !== undefined ? { database: spec.database } : {}) });
+        // Record the handle before validating it, so rollback also owns a bad factory result.
+        servers.push(server);
+        if (!Number.isInteger(server.port) || server.port < 1 || server.port > 65535 || (spec.port !== 0 && server.port !== spec.port)) {
+          throw new Error(`Twin "${spec.id}" bound port ${server.port}, requested ${spec.port}.`);
+        }
+        ports[spec.id] = server.port;
+      });
+    } catch (error) {
+      const cleanup = await stop();
+      if (cleanup.length) throw new AggregateError([error, ...cleanup], 'Co-located host startup and rollback failed.');
+      throw error;
     }
     return {
       isolation,
       ports,
       stop: async () => {
-        process.off('unhandledRejection', onRejection);
-        process.off('uncaughtException', onUncaught);
-        // EVERY stop is invoked, IN PARALLEL, each under its own timeout, and no outcome —
-        // rejection, hang, or slowness — can prevent the others or wedge host.stop() itself.
-        // The awaited-sequential first cut re-created the SIGKILL escalation it was fixing
-        // through a new door (§9 round two H2, 2026-08-31: one pending/throwing stop — fly's
-        // cleanup throws on a failed container removal — left siblings unstopped and the host
-        // ignoring SIGTERM forever). The bound stays under downWorld's 5s SIGKILL grace.
-        await Promise.allSettled(servers.map((s) =>
-          Promise.race([
-            Promise.resolve().then(() => s.stop()),
-            new Promise((resolveTimeout) => setTimeout(resolveTimeout, STOP_TIMEOUT_MS).unref?.()),
-          ]),
-        ));
+        // Every stop runs, even when a sibling hangs or throws. Host shutdown
+        // still resolves within its budget so the owning runtime can retire it.
+        for (const error of await stop()) onEvent({ twin: '(host)', kind: 'stop-failed', detail: String(error) });
       },
     };
   }
@@ -143,8 +159,14 @@ export async function startColocatedHost(
       // below would emit a 2nd `spawn` for the same twin, which the isolation test asserts against.
       onEvent({ twin: spec.id, kind: 'spawn', detail: 'worker started' });
       let ready = false;
-      worker.on('message', (msg: { type?: string }) => {
-        if (msg?.type === 'ready') { ready = true; resolveReady(); }
+      worker.on('message', (msg: { type?: string; port?: number }) => {
+        if (msg?.type === 'ready') {
+          if (typeof msg.port !== 'number' || !Number.isInteger(msg.port) || msg.port < 1 || msg.port > 65535 || (spec.port !== 0 && msg.port !== spec.port)) {
+            rejectReady(new Error(`Twin "${spec.id}" bound port ${msg.port}, requested ${spec.port}.`)); return;
+          }
+          ports[spec.id] = msg.port;
+          ready = true; resolveReady();
+        }
       });
       worker.on('error', (err) => {
         onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
@@ -152,6 +174,7 @@ export async function startColocatedHost(
       });
       worker.on('exit', (code) => {
         workers.delete(spec.id);
+        if (!ready) rejectReady(new Error(`Twin "${spec.id}" exited before readiness (code ${code}).`));
         if (stopping.value || code === 0) return;
         // Minimal-primitive doctrine: no keep-alive supervisor. A crashed worker is NOT
         // respawned — record the give-up (host-cli persists it → doctor red) and stay dead.
@@ -160,7 +183,14 @@ export async function startColocatedHost(
       workers.set(spec.id, worker);
     });
 
-  for (const spec of specs) await spawnWorker(spec);
+  try { await parallelStartup(specs, async (spec) => spawnWorker(spec)); }
+  catch (error) {
+    stopping.value = true;
+    const stopped = await Promise.allSettled([...workers.values()].map((worker) => worker.terminate()));
+    const cleanup = stopped.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason);
+    if (cleanup.length) throw new AggregateError([error, ...cleanup], 'Co-located worker startup and rollback failed.');
+    throw error;
+  }
 
   return {
     isolation,

package/src/runtime.ts

@@ -1,5 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
+import { parallelStartup } from './startup.ts';
+import { waitForHostReady } from './host-ready.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
 import { spawn, spawnSync } from 'node:child_process';
@@ -104,16 +106,21 @@ async function untilReadyOrEnded<T>(wait: (abort: AbortSignal) => Promise<T>, en
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false): Promise<void> {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false, sharedSettle?: Promise<'alive'>): Promise<void> {
   // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
   boot.signal.throwIfAborted();
   const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
   const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' as const : new Promise<never>(() => undefined))) : new Promise<never>(() => undefined);
   // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
   if (ended) {
-    const settled = await Promise.race([own, ended.then(() => 'ended' as const), new Promise<'alive'>((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled: 'own' | 'ended' | 'alive';
+    try {
+      const settle = sharedSettle ?? new Promise<'alive'>((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+      settled = await Promise.race([own, ended.then(() => 'ended' as const), settle]);
+    } finally { if (timer !== undefined) clearTimeout(timer); }
     boot.signal.throwIfAborted();
     if (settled === 'own') return;
     if (settled === 'ended') throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
@@ -1321,8 +1328,10 @@ async function startColocatedServices(
   allocatedPorts: Set<number>,
   boot: BootContext,
 ): Promise<WorldServiceInstance[]> {
+  if (colocated.length === 0) return [];
   const hostCli = siblingScript(import.meta.url, 'host-cli');
-  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+  const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
   const allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage }> = [];
   for (const service of colocated) {
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1360,22 +1369,33 @@ async function startColocatedServices(
   });
 
   const command = [process.execPath, ...args];
-  for (const { service, port } of allocated) {
+  const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+  await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+    if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+    try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+    throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+  });
+  await parallelStartup(allocated, async ({ service, port }) => {
     const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
     await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
       if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
       try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
       throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
     });
-  }
-  for (const [index, { service, port }] of allocated.entries()) {
-    // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-    await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-      if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-      throw error;
+  });
+  let hostSettleTimer: ReturnType<typeof setTimeout> | undefined;
+  const hostSettle = new Promise<'alive'>((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+  try {
+    await parallelStartup(allocated, async ({ service, port }) => {
+      // The host has completed every start. Each matching boot answer can now
+      // end its own settle; legacy twins share one full host guard.
+      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+        throw error;
+      });
     });
-  }
+  } finally { if (hostSettleTimer !== undefined) clearTimeout(hostSettleTimer); }
   if (exitState.value !== null) {
     throw new Error(
       `The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`

package/src/startup.ts

@@ -0,0 +1,16 @@
+/** Finite independent boot operations. Stop scheduling on failure and join every operation already begun. */
+export async function parallelStartup<T>(items: readonly T[], start: (item: T, index: number) => Promise<void>): Promise<void> {
+  let next = 0;
+  let failed = false;
+  const errors: unknown[] = [];
+  await Promise.all(Array.from({ length: Math.min(8, items.length) }, async () => {
+    while (!failed) {
+      const index = next++;
+      if (index >= items.length) return;
+      try { await start(items[index]!, index); }
+      catch (error) { failed = true; errors.push(error); }
+    }
+  }));
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, 'Independent World startup operations failed.');
+}