@volter/world-runtime 3.0.37 → 3.0.39

package/dist/src/redirect-proxy.js

@@ -1,5 +1,6 @@
+import { errorMessage } from "./error-message.js";
 import { serveHttp } from '@volter/world-core/runtime';
-import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
+import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
 import { websocketRelay } from "./websocket-relay.js";
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
 // redirection works", tier 1). A local TLS-terminating forward proxy that maps vendor API hosts
@@ -26,6 +27,9 @@ import { lookup as dnsLookup } from 'node:dns/promises';
 import { BlockList, isIP, connect as netConnect, createServer as createNetServer } from 'node:net';
 import { networkInterfaces } from 'node:os';
 import { connect as tlsConnect } from 'node:tls';
+import { request as httpsRequest } from 'node:https';
+import { createServer as createHttpServer } from 'node:http';
+import { Readable } from 'node:stream';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 // The host→twin table is loaded through the shared inject-map module (one world-runtime home
@@ -33,6 +37,7 @@ import { join } from 'node:path';
 // never re-encode the vendor host predicates — they stay one source of truth with the Node
 // injector. External callers go through `proxyTargetFor`/`activeVendorMap`.
 import { loadInject } from "./inject-map.js";
+import { packFacts } from "./pack-facts.js";
 import { sessionTrustEnv } from "./ca-trust.js";
 /**
  * The body served when a host was MITM'd but no twin serves the PATH.
@@ -168,7 +173,7 @@ export async function guestDestination(host) {
         addresses = isIP(h) ? [h] : (await dnsLookup(h, { all: true })).map((r) => r.address);
     }
     catch (error) {
-        return { refused: `${host} does not resolve (${error.message})` };
+        return { refused: `${host} does not resolve (${errorMessage(error)})` };
     }
     const bad = addresses.find(isGuestForbiddenAddress);
     if (bad || !addresses.length)
@@ -277,7 +282,7 @@ export function leafCertFor(host, ca) {
  *  of which World to look at (`doctor`). Shared by every front that relays to twins. */
 export function twinUnreachableMessage(vendor, origin, err, world) {
     const cause = err.cause;
-    return `twin "${vendor}" at ${origin} is unreachable${world ? ` in World "${world}"` : ''}: ${err.message}${cause?.code ? ` (${cause.code})` : cause?.message ? ` (${cause.message})` : ''}; check \`volter-world doctor${world ? ` ${world}` : ''}\`\n`;
+    return `twin "${vendor}" at ${origin} is unreachable${world ? ` in World "${world}"` : ''}: ${errorMessage(err)}${cause?.code ? ` (${cause.code})` : cause?.message ? ` (${errorMessage(cause)})` : ''}; check \`volter-world doctor${world ? ` ${world}` : ''}\`\n`;
 }
 /** Start the ambient redirect proxy. Returns a handle with the listen port + the env to export.
  * - Plain `http://` proxied requests to a vendor host → forwarded to the twin.
@@ -308,6 +313,117 @@ export async function startRedirectProxy(options) {
     // Track raw client/upstream sockets so close() can forcibly drop tunnels (a blind tunnel to a slow
     // or real upstream would otherwise keep the server from closing).
     const openSockets = new Set();
+    const publicBuildRequest = (target, env) => {
+        const policy = worldNetworkPolicyFromEnv(env);
+        return !strictEgressEnabled(env) && !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, target);
+    };
+    // One upstream HTTP operation, shared by plain-proxy and decrypted CONNECT requests.
+    // It never follows redirects and never lends the upstream socket to the caller.
+    const externalRequest = async (target, method, incoming, body, signal) => {
+        const env = currentEnv();
+        const policy = worldNetworkPolicyFromEnv(env);
+        // the method is visible here: an egress grant reads, a write needs `writes`
+        if (!policy || !allowsWorldNetworkEgress(policy, target, method) || shouldBlockUntwinned(target, env))
+            throw new Error('World policy refuses the effective request');
+        const host = incoming.get('host');
+        if (host && new URL(`${target.protocol}//${host}`).host !== target.host)
+            throw new Error('request Host differs from authorized authority');
+        if (method === 'CONNECT' || incoming.has('upgrade'))
+            throw new Error('inspected egress cannot upgrade its transport');
+        if (!body && (Number(incoming.get('content-length') || 0) > 0 || incoming.has('transfer-encoding')))
+            throw new Error('transport cannot mediate this request body');
+        const headers = new Headers(incoming);
+        const hopHeaders = (headers.get('connection') ?? '').split(',').map(h => h.trim().toLowerCase()).filter(Boolean);
+        for (const h of [...hopHeaders, 'host', 'proxy-authorization', 'proxy-authenticate', 'proxy-connection', 'connection', 'keep-alive', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'x-twins-key', 'x-volter-twin-original-host'])
+            headers.delete(h);
+        return await new Promise((resolve, reject) => {
+            const upstream = httpsRequest({ hostname: target.hostname, port: Number(target.port || 443), servername: target.hostname,
+                path: target.pathname + target.search, method, headers: { ...Object.fromEntries(headers), host: target.host },
+                agent: false, ca: readFileSync(trust.SSL_CERT_FILE), signal, }, res => {
+                const out = new Headers();
+                const nominated = String(res.headers.connection ?? '').split(',').map(h => h.trim().toLowerCase());
+                for (const [key, value] of Object.entries(res.headers))
+                    if (value !== undefined && ![...nominated, 'connection', 'transfer-encoding', 'keep-alive', 'trailer', 'upgrade'].includes(key)) {
+                        for (const part of Array.isArray(value) ? value : [value])
+                            out.append(key, String(part));
+                    }
+                const empty = method === 'HEAD' || [204, 205, 304].includes(res.statusCode);
+                if (empty)
+                    res.resume();
+                note(`inspected egress ${method} ${target.origin}${target.pathname} -> ${res.statusCode}`);
+                resolve(new Response(empty ? null : Readable.toWeb(res), { status: res.statusCode, headers: out }));
+            });
+            upstream.on('socket', socket => { openSockets.add(socket); socket.on('close', () => openSockets.delete(socket)); });
+            upstream.on('error', reject);
+            upstream.on('upgrade', (_res, socket) => { socket.destroy(); reject(new Error('upstream upgrade refused')); });
+            if (body) {
+                const source = Readable.fromWeb(body);
+                source.on('error', error => upstream.destroy(error));
+                upstream.on('error', () => source.destroy());
+                source.pipe(upstream);
+            }
+            else
+                upstream.end();
+        });
+    };
+    // Use the HTTP parser for framing; never forward trailing bytes as a second raw request.
+    const usedPlainSockets = new WeakSet();
+    const inspectedPlain = createHttpServer((req, res) => {
+        if (usedPlainSockets.has(req.socket)) {
+            note('inspected egress refused extra plain request');
+            req.socket.destroy();
+            return;
+        }
+        usedPlainSockets.add(req.socket);
+        res.shouldKeepAlive = false;
+        res.setHeader('connection', 'close');
+        res.on('finish', () => req.socket.end());
+        const abort = new AbortController();
+        req.on('aborted', () => abort.abort());
+        res.on('close', () => { if (!res.writableFinished)
+            abort.abort(); });
+        void (async () => {
+            if (/\\/.test(req.url.split(/[?#]/, 1)[0]))
+                throw new Error('backslash in proxy target');
+            const target = new URL(req.url);
+            if (proxyTargetFor(target.hostname, currentEnv()) && !publicBuildRequest(target, currentEnv()))
+                throw new Error('inspected external request names a twinned host');
+            const headers = new Headers();
+            for (let i = 0; i < req.rawHeaders.length; i += 2)
+                headers.append(req.rawHeaders[i], req.rawHeaders[i + 1]);
+            const body = headers.has('transfer-encoding') || Number(headers.get('content-length') || 0) > 0 ? Readable.toWeb(req) : null;
+            const response = await externalRequest(target, req.method, headers, body, abort.signal);
+            res.statusCode = response.status;
+            for (const [key, value] of response.headers)
+                res.setHeader(key, value);
+            if (response.body) {
+                const stream = Readable.fromWeb(response.body);
+                stream.on('error', () => res.destroy());
+                res.on('close', () => stream.destroy());
+                stream.pipe(res);
+            }
+            else
+                res.end();
+        })().catch(error => { if (!res.headersSent) {
+            res.statusCode = 502;
+            res.end(note(`${error.message}\n`));
+        }
+        else
+            res.destroy(); });
+    });
+    inspectedPlain.maxRequestsPerSocket = 1;
+    inspectedPlain.on('dropRequest', (req, socket) => { note('inspected egress refused extra plain request'); socket.destroy(); });
+    inspectedPlain.on('clientError', (_error, socket) => socket.destroy());
+    // Bun's Node HTTP adapter parses only on a listening server, not a synthetic connection event.
+    // Relays below carry bytes solely to this local parser; only externalRequest opens public sockets.
+    await new Promise((resolve, reject) => {
+        inspectedPlain.once('error', reject);
+        inspectedPlain.listen(0, '127.0.0.1', resolve);
+    });
+    const inspectedAddress = inspectedPlain.address();
+    if (!inspectedAddress || typeof inspectedAddress === 'string')
+        throw new Error('inspected HTTP parser has no TCP address');
+    const inspectedPort = inspectedAddress.port;
     // The MITM TLS endpoint(s): a REAL listening TLS server PER vendor host (loopback, ephemeral port), each pinned
     // to that host's leaf cert. On CONNECT to a vendor host we tunnel the client's raw bytes to the matching per-host
     // server, which terminates TLS and forwards the decrypted request to the resolved twin. (One server per host
@@ -317,8 +433,9 @@ export async function startRedirectProxy(options) {
     // websocket is relayed message by message to the twin's own websocket at the same path.
     const tlsServers = new Map();
     const tlsPorts = new Map();
-    const ensureHostServer = async (vendorHost) => {
-        const existing = tlsPorts.get(vendorHost);
+    const ensureHostServer = async (vendorHost, guest = false, originPort = 443) => {
+        const serverKey = `${vendorHost}:${originPort}:${guest}`;
+        const existing = tlsPorts.get(serverKey);
         if (existing)
             return existing;
         const leaf = leafCertFor(vendorHost, ca);
@@ -326,6 +443,8 @@ export async function startRedirectProxy(options) {
             hostname: '127.0.0.1',
             port: 0,
             tls: { key: leaf.key, cert: leaf.cert },
+            // Carry a twin's declared transport cap through TLS termination; public grants add no cap.
+            maxRequestBodySize: packFacts()[proxyTargetFor(vendorHost, currentEnv())?.vendor ?? '']?.maxRequestBodySize,
             // A twin can think before its first byte (a git pack built from a cold cache took 19-28 s); Bun's 10 s idle
             // default cut those connections and the client read an empty reply. Bun's maximum, as reflect.ts serves.
             idleTimeout: 255,
@@ -336,13 +455,29 @@ export async function startRedirectProxy(options) {
                 // The request line is readable now, so resolve WITH the path: this is the point where a host two vendors
                 // share (www.googleapis.com → googleauth vs youtube) gets split correctly; on a shared host there IS a twin
                 // for the host and merely not for this path, and the bare message sends the next reader hunting.
-                const twin = proxyTargetFor(hostHeader, env, u.pathname) ?? proxyTargetFor(vendorHost, env, u.pathname);
+                const effective = new URL(`https://${vendorHost}:${originPort}${u.pathname}${u.search}`);
+                const publicBuild = publicBuildRequest(effective, env);
+                const twin = publicBuild ? null : proxyTargetFor(hostHeader, env, u.pathname) ?? proxyTargetFor(vendorHost, env, u.pathname);
                 if (!twin) {
                     // a host the World refuses (sealed, or outside its network policy): answered here, over the World's TLS, so
                     // a person's browser shows where it was sent and why nothing is there, not an empty tunnel error; nothing
                     // leaves the World
-                    if (shouldBlockUntwinned(`https://${hostHeader}`, env))
+                    const target = new URL(`https://${vendorHost}:${originPort}${u.pathname}${u.search}`);
+                    if (shouldBlockUntwinned(target.href, env))
                         return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'));
+                    if (!publicBuild && proxyTargetFor(vendorHost, env))
+                        return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'));
+                    const policy = worldNetworkPolicyFromEnv(env);
+                    if (policy && worldNetworkNeedsPathInspection(policy, target)) {
+                        if (guest)
+                            return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), 'guest inspected egress cannot preserve its checked destination pin');
+                        try {
+                            return await externalRequest(target, req.method, req.headers, req.body, req.signal);
+                        }
+                        catch (error) {
+                            return new Response(note(`inspected egress refused: ${error.message}\n`), { status: 502 });
+                        }
+                    }
                     const unreachable = unreachableHosts.get(hostHeader.toLowerCase());
                     if (unreachable)
                         return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), unreachable);
@@ -395,8 +530,8 @@ export async function startRedirectProxy(options) {
             }),
         });
         const p = hostServer.port ?? 0;
-        tlsServers.set(vendorHost, hostServer);
-        tlsPorts.set(vendorHost, p);
+        tlsServers.set(serverKey, hostServer);
+        tlsPorts.set(serverKey, p);
         return p;
     };
     // two listeners with one handler: the World's (host clients; a connection from elsewhere is still a guest's) and its
@@ -436,7 +571,7 @@ export async function startRedirectProxy(options) {
                 }
                 return;
             }
-            handlePlainProxyRequest(method, urlStr, version, headers, clientSocket, head, guest);
+            handlePlainProxyRequest(method, urlStr, version, headers, clientSocket, head, guest, buffered);
         };
         clientSocket.on('data', onData);
     };
@@ -496,12 +631,13 @@ export async function startRedirectProxy(options) {
             : netConnect(Number(origin.port || 80), connectHost, connected);
         openSockets.add(upstream);
         upstream.on('close', () => openSockets.delete(upstream));
-        upstream.on('error', (err) => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', vendor ? twinUnreachable(vendor, origin.origin, err) : note(`upstream ${origin.host} unreachable: ${err.message}\n`)));
+        upstream.on('error', (err) => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', vendor ? twinUnreachable(vendor, origin.origin, err) : note(`upstream ${origin.host} unreachable: ${errorMessage(err)}\n`)));
     };
-    const handlePlainProxyRequest = (method, urlStr, version, headers, socket, head, guest) => {
+    const handlePlainProxyRequest = (method, urlStr, version, headers, socket, head, guest, raw) => {
         try {
             const u = new URL(urlStr);
-            const twin = proxyTargetFor(u.hostname, currentEnv(), u.pathname);
+            const publicBuild = publicBuildRequest(u, currentEnv());
+            const twin = publicBuild ? null : proxyTargetFor(u.hostname, currentEnv(), u.pathname);
             const path = u.pathname + u.search;
             if (twin) {
                 const target = new URL(twin.origin);
@@ -513,7 +649,7 @@ export async function startRedirectProxy(options) {
             // No twin claims this PATH — but if the HOST is twinned (host-level candidacy), the path is
             // an unclaimed slice of a shared, virtualized host: refuse loudly (same rule as the MITM
             // handler's noTwinMessage), never pass through to the real vendor.
-            if (proxyTargetFor(u.hostname, currentEnv())) {
+            if (!publicBuild && proxyTargetFor(u.hostname, currentEnv())) {
                 writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)));
                 return;
             }
@@ -521,6 +657,25 @@ export async function startRedirectProxy(options) {
                 writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`));
                 return;
             }
+            const policy = worldNetworkPolicyFromEnv(currentEnv());
+            if (policy && worldNetworkNeedsPathInspection(policy, u)) {
+                if (guest) {
+                    writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'));
+                    return;
+                }
+                socket.pause();
+                const parser = netConnect(inspectedPort, '127.0.0.1', () => {
+                    parser.write(raw);
+                    socket.pipe(parser);
+                    parser.pipe(socket);
+                    socket.resume();
+                });
+                openSockets.add(parser);
+                parser.on('close', () => { openSockets.delete(parser); socket.destroy(); });
+                parser.on('error', () => socket.destroy());
+                socket.on('close', () => parser.destroy());
+                return;
+            }
             // Non-vendor: plain pass-through to the real host; for a World Machine, only off its host's own network, and to
             // the address checked (architecture, "The scoped proxy's local pass-through")
             if (guest) {
@@ -560,7 +715,7 @@ export async function startRedirectProxy(options) {
             // a destination that cannot be reached at all (a name that does not resolve, a refused port) is answered by the
             // caller's fallback when it has one, before the tunnel was ever established; otherwise the client's socket ends
             upstream.on('error', (error) => {
-                if (!connected && unreachable && unreachable(error.code ?? error.message))
+                if (!connected && unreachable && unreachable(error.code ?? errorMessage(error)))
                     return;
                 clientSocket.destroy();
             });
@@ -572,13 +727,23 @@ export async function startRedirectProxy(options) {
             note(`${connectHost}:${connectPort} did not answer (${reason})`);
             refusedPages.add(connectHost);
             unreachableHosts.set(connectHost, reason);
-            ensureHostServer(connectHost).then((port) => tunnel(port, '127.0.0.1')).catch(() => clientSocket.destroy());
+            ensureHostServer(connectHost, guest, connectPort).then((port) => tunnel(port, '127.0.0.1')).catch(() => clientSocket.destroy());
             return true;
         };
         // MITM vendor hosts → tunnel to the per-host listening https server (terminates TLS, forwards to
         // the twin). Non-vendor hosts → blind-tunnel to the REAL origin, untouched.
-        if (twin && connectHost) {
-            ensureHostServer(connectHost)
+        const scopedOrigin = connectHost && new URL(`https://${connectHost}:${connectPort}`);
+        const scopedPolicy = worldNetworkPolicyFromEnv(currentEnv());
+        const inspected = scopedOrigin && scopedPolicy && worldNetworkNeedsPathInspection(scopedPolicy, scopedOrigin);
+        const passthrough = scopedOrigin && scopedPolicy && worldNetworkUsesPassthrough(scopedPolicy, scopedOrigin);
+        if (passthrough && !twin)
+            note(`build TLS passthrough ${scopedOrigin.origin} (explicit origin scope)`);
+        if (inspected && guest && !twin) {
+            writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'));
+            return;
+        }
+        if ((twin || (!strictEgressEnabled(currentEnv()) && inspected)) && connectHost) {
+            ensureHostServer(connectHost, guest, connectPort)
                 .then((port) => tunnel(port, '127.0.0.1'))
                 .catch(() => clientSocket.destroy());
         }
@@ -590,7 +755,7 @@ export async function startRedirectProxy(options) {
             // line, as before
             if (connectPort === 443 && isDnsName(connectHost) && (refusedPages.has(connectHost) || refusedPages.size < REFUSED_PAGES_MAX)) {
                 refusedPages.add(connectHost);
-                ensureHostServer(connectHost)
+                ensureHostServer(connectHost, guest, connectPort)
                     .then((port) => tunnel(port, '127.0.0.1'))
                     .catch(() => clientSocket.destroy());
             }
@@ -651,6 +816,8 @@ export async function startRedirectProxy(options) {
                 }
                 catch { /* ignore */ }
             }
+            inspectedPlain.closeAllConnections();
+            inspectedPlain.close();
             guestServer.close();
             server.close(() => resolveClose());
         }),

package/dist/src/redis-backing.js

@@ -8,12 +8,17 @@
 // in a container is state outside it (a branch of the World would share the container's queue and cache). The
 // twin keeps each key a subject of the World (the Redis pack's storage module). It needs nothing
 // installed: no container runtime, no redis-server binary.
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
+import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from "./command-lifetime.js";
+import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, signalOwnedProcess } from "./process-receipt.js";
 import { spawn } from 'node:child_process';
+import { survivingOwnedGroups } from "./process-groups.js";
+import { errorMessage } from "./error-message.js";
 import { findInstalledPackage, packCli } from "./catalog.js";
 import { vendorPackageDir } from '@volter/world-core/runtime';
+const hosts = new Map();
 const PACKAGE = '@volter/twin-redis';
 const READY_TIMEOUT_MS = 60_000;
 /** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
@@ -34,8 +39,10 @@ function alive(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        throw error;
     }
 }
 function listening(port) {
@@ -52,8 +59,9 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function redisTwinUp(services, dataDir, cli, launch = {}) {
     for (const service of services) {
         const pidFile = pidPath(dataDir, service);
-        if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
-            continue;
+        if (hosts.has(pidFile) || existsSync(pidFile) || existsSync(spawnReceiptPath(pidFile))) {
+            await redisTwinDown([service], dataDir);
+        }
         // a port that already answers is another process's (another World's twin, a redis-server): serving there would
         // hand this World's app someone else's keys, so it is refused, never taken as ready
         if (await listening(service.hostPort))
@@ -67,23 +75,51 @@ export async function redisTwinUp(services, dataDir, cli, launch = {}) {
         // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
         // type transformation, not only stripping (the kernel declares constructor parameter properties)
         const runtime = typeof globalThis.Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
-        const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
-            env: launch.env ?? process.env,
-            detached: true,
-            windowsHide: true,
-            stdio: ['ignore', logFd, logFd],
-        });
-        child.unref();
-        closeSync(logFd);
-        writeFileSync(pidFile, `${child.pid}\n`);
-        const deadline = Date.now() + READY_TIMEOUT_MS;
-        while (!(await listening(service.hostPort)) || !alive(child.pid)) {
-            if (!alive(child.pid))
-                throw new Error(`redis exited before serving — see ${log}`);
+        let held;
+        try {
+            try {
+                const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+                    env: launch.env ?? process.env, detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd],
+                });
+                // Retain BEFORE descriptor close, birth capture or either publication can fail.
+                held = { child, lifetime: commandLifetime(child, launch.signal), closed: false };
+                const observed = held;
+                child.once('close', () => { observed.closed = true; });
+                child.on('error', () => { }); // lifetime joins spawn failure and close
+                hosts.set(pidFile, held);
+            }
+            finally {
+                closeSync(logFd);
+            }
+            if (!held.child.pid)
+                throw new Error('Redis child did not start');
+            const identity = await held.lifetime.identity;
+            if (!identity?.start)
+                throw new Error('Redis birth capture failed; retiring held child');
+            publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
+            publishProcessReceipt(pidFile, `${held.child.pid}\n`);
+            const deadline = Date.now() + READY_TIMEOUT_MS;
+            while (!(await listening(service.hostPort)) || !alive(held.child.pid)) {
+                if (!alive(held.child.pid))
+                    throw new Error(`redis exited before serving — see ${log}`);
+                launch.signal?.throwIfAborted();
+                if (Date.now() > deadline)
+                    throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+                await sleep(200);
+            }
             launch.signal?.throwIfAborted();
-            if (Date.now() > deadline)
-                throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
-            await sleep(200);
+            held.child.unref();
+        }
+        catch (error) {
+            if (held) {
+                try {
+                    await redisTwinDown([service], dataDir);
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], 'Redis startup and retirement failed; ownership retained');
+                }
+            }
+            throw error;
         }
     }
 }
@@ -101,24 +137,52 @@ export async function redisTwinStatus(services, dataDir) {
 export async function redisTwinDown(services, dataDir) {
     for (const service of services) {
         const pidFile = pidPath(dataDir, service);
-        if (!existsSync(pidFile))
-            continue;
-        const pid = Number(readFileSync(pidFile, 'utf8').trim());
-        if (alive(pid)) {
-            try {
-                process.kill(pid, 'SIGTERM');
-            }
-            catch { /* already gone */ }
-            const deadline = Date.now() + 5000;
-            while (alive(pid) && Date.now() < deadline)
-                await sleep(100);
-            if (alive(pid)) {
+        const recorded = readProcessReceipt(pidFile, text => {
+            const pid = Number(text.trim());
+            if (!Number.isInteger(pid) || pid <= 0)
+                throw new Error('Invalid Redis ownership PID');
+            return pid;
+        });
+        const identity = readSpawnReceipt(pidFile);
+        const held = hosts.get(pidFile);
+        if (recorded.error || identity.error)
+            process.stderr.write(`${errorMessage(new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; retrying established ownership'))}\n`);
+        if (held) {
+            const retired = () => held.closed && (!held.child.pid || !survivingOwnedGroups([held.child.pid]).length);
+            if (!retired()) {
+                held.child.ref();
+                held.lifetime.cancel('SIGTERM');
                 try {
-                    process.kill(pid, 'SIGKILL');
+                    await held.lifetime.finish();
+                }
+                catch (error) {
+                    if (!retired())
+                        throw error;
                 }
-                catch { /* raced */ }
             }
         }
+        else {
+            if (!recorded.present && !identity.present)
+                continue;
+            const pid = identity.value?.pid ?? recorded.value;
+            if (!pid)
+                throw new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; receipts retained');
+            if (recorded.value && identity.value && recorded.value !== identity.value.pid)
+                throw new Error('Redis ownership receipts disagree; retirement refused; receipts retained');
+            const live = () => survivingOwnedGroups([pid]).length > 0;
+            for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]]) {
+                if (!live())
+                    break;
+                await signalOwnedProcess(identity.value, signal, true);
+                const deadline = Date.now() + limit;
+                while (live() && Date.now() < deadline)
+                    await sleep(20);
+            }
+            if (live())
+                throw new Error('Redis retirement unconfirmed; receipts retained');
+        }
         rmSync(pidFile, { force: true });
+        rmSync(spawnReceiptPath(pidFile), { force: true });
+        hosts.delete(pidFile);
     }
 }

package/dist/src/reflect.js

@@ -1,3 +1,4 @@
+import { errorMessage } from "./error-message.js";
 import { serveHttp } from '@volter/world-core/runtime';
 import { websocketRelay } from "./websocket-relay.js";
 import { sessionTrustEnv } from "./ca-trust.js";
@@ -161,7 +162,7 @@ export async function startReflectFront(options) {
                         world = options.envLoader().VOLTER_WORLD;
                     }
                     catch { /* the answer still goes out */ }
-                    return new Response(twinUnreachableMessage(target.vendor, origin.origin, error instanceof Error ? error : new Error(String(error)), world), { status: 502 });
+                    return new Response(twinUnreachableMessage(target.vendor, origin.origin, error instanceof Error ? error : new Error(errorMessage(error)), world), { status: 502 });
                 }
             },
             upgrade: websocketRelay(req => {

package/dist/src/root.js

@@ -7,6 +7,7 @@
 // never in a pack, never an env var). `volter world deploy` performs landed entries against each
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
+import { errorMessage } from "./error-message.js";
 import { randomBytes } from 'node:crypto';
 import { packEntry } from "./catalog.js";
 import { existsSync, readFileSync } from 'node:fs';
@@ -126,7 +127,7 @@ export async function bindLegacyCredentials(worldRoot, current) {
             inventory = (await currentSealer().open(JSON.parse(heldInventory), INVENTORY_SLOT));
         }
         catch (error) {
-            console.error(`[credential] the inventory beside the World does not open (${error.message}): nothing is admitted until it does`);
+            console.error(`[credential] the inventory beside the World does not open (${errorMessage(error)}): nothing is admitted until it does`);
             return { bound: [], failed: [], refused: [], ready: false };
         }
     }
@@ -137,7 +138,7 @@ export async function bindLegacyCredentials(worldRoot, current) {
             return true;
         }
         catch (error) {
-            console.error(`[credential] the inventory could not be kept (${error.message})`);
+            console.error(`[credential] the inventory could not be kept (${errorMessage(error)})`);
             return false;
         }
     };
@@ -182,7 +183,7 @@ export async function bindLegacyCredentials(worldRoot, current) {
             bound.push(name);
         }
         catch (error) {
-            console.warn(`[credential] ${name}: not bound to its destination (${error.message})`);
+            console.warn(`[credential] ${name}: not bound to its destination (${errorMessage(error)})`);
             failed.push(name);
         }
     }
@@ -210,7 +211,7 @@ export async function bindLegacyCredentials(worldRoot, current) {
                 bound.push(name);
             }
             catch (error) {
-                console.warn(`[credential] ${name}: not moved to the vault (${error.message})`);
+                console.warn(`[credential] ${name}: not moved to the vault (${errorMessage(error)})`);
                 failed.push(name);
             }
         }
@@ -298,7 +299,7 @@ export async function rootCredentialInput(worldRoot, vendor, env = process.env)
             response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
         }
         catch (error) {
-            notes.push(`the vault at ${vault.addr} did not answer (${error.message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+            notes.push(`the vault at ${vault.addr} did not answer (${errorMessage(error)}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
         }
         if (response) {
             if (response.status === 403)
@@ -526,7 +527,7 @@ export async function refreshTwin(opts) {
         // failure — its reason and how many in a row — so the status door and the twin's status say so
         const held = store.read(marker);
         const previous = held !== null ? JSON.parse(held) : {};
-        const reason = error instanceof Error ? error.message : String(error);
+        const reason = errorMessage(error);
         store.write(marker, `${JSON.stringify({ ...previous, at: new Date().toISOString(), failed: { at, reason, count: (previous.failed?.count ?? 0) + 1 } })}\n`);
         throw error;
     }

package/dist/src/run-task-worker.js

@@ -1,4 +1,5 @@
 import { runWorldOwned } from "./runtime.js";
+import { errorMessage } from "./error-message.js";
 // Only this process owns the IPC endpoint; child stdio explicitly excludes fd 3. A lost
 // caller requests cancellation, including while startup is still settling. No service restarts.
 if (!process.send)
@@ -27,7 +28,7 @@ process.on('message', async (message) => {
         reply = { result: await runWorldOwned(request.configId, request.command, request.options, abort.signal) };
     }
     catch (error) {
-        reply = { error: error instanceof Error ? error.message : String(error) };
+        reply = { error: errorMessage(error) };
     }
     if ('error' in reply)
         process.stderr.write(`${reply.error}\n`);