@volter/world-runtime 3.0.38 → 3.0.39

package/src/cli-commands.ts

@@ -61,10 +61,10 @@ function printHelp(): void {
                                                   # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
                                                   # Deterministic: same repo + same pack catalog => identical bytes.
                                                   # init DIAGNOSES; it never boots — it prints the exact next commands
-  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--root <repo>]
+  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--json] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — each mounted twin's grade, as the catalog records it (R17)
-  volter-world down <name> [--grace-ms <ms>] [--purge] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
+  volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
                                                                           # --purge: after teardown, delete the instance dir (and per-service twin data) too — see docs/concepts/data-and-keys.md
   volter-world status <name> [--json] [--root <repo>]
   volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]  # resolve attachments whose runner, command and process group are gone
@@ -98,14 +98,15 @@ function printHelp(): void {
                                                   # fails loudly with the registration recipe. A world that boots
                                                   # the app itself declares an "app" service (type "process") —
                                                   # its URL answers without any registration
-  volter-world log <name> [service...] [--no-follow] [--json] [--requests] [--root <repo>]   # the log of changes (alias: tail)
+  volter-world log <name> [service...] [--no-follow] [--json] [--requests] [--logs] [--root <repo>]   # the log of changes (alias: tail)
                                                   # merged, occurredAt-ordered feed of the twins' action ledgers — one
                                                   # \`HH:MM:SS.mmm <service> <operation> <subjectId>\` line per action;
                                                   # follows until Ctrl-C (--no-follow: dump and exit; --json: raw JSONL;
                                                   # --requests: also merge the request journals — reads/404s,
                                                   # plus WHICH credential arrived in WHICH header/query param, named +
                                                   # fingerprinted, never the value — kept by every twin and link
-                                                  # unless VOLTER_TWIN_REQUEST_JOURNAL=0)
+                                                  # unless VOLTER_TWIN_REQUEST_JOURNAL=0; --logs: also read the services'
+                                                  # process output verbatim, labeled stdout — not shape-only journals)
   volter-world seed <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
                                                   # pull from the placeholder remote: the seed entry runs with every twin's
                                                   # window open, so the defaults land as observed state (diff empty, nothing pending)
@@ -266,9 +267,16 @@ export async function main(): Promise<void> {
     const graceArg = optionValue(rest, '--grace-ms');
     if (graceArg && !(Number(graceArg) >= 0)) throw new Error(`volter-world down: invalid --grace-ms "${graceArg}" (want a non-negative number)`);
     const purge = rest.includes('--purge');
+    if (rest.some(arg => arg === '--if-created-at' || arg.startsWith('--if-created-at='))) throw new Error('volter-world down: use --if-instance with the token returned by your own boot');
+    // absent flag: no ownership expectation (optionValue's '' fallback would read as an empty, refused token)
+    const ifInstance = rest.some(arg => arg === '--if-instance' || arg.startsWith('--if-instance='));
+    const expectedInstance = ifInstance ? optionValue(rest, '--if-instance') : undefined;
+    if (ifInstance
+      && (!expectedInstance || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(expectedInstance))) throw new Error('volter-world down: invalid --if-instance token');
     const result = await downWorld(subject, root, {
       ...(graceArg ? { graceMs: Number(graceArg) } : {}),
       ...(purge ? { purge: true } : {}),
+      ...(expectedInstance === undefined ? {} : { expectedInstance }),
     });
     process.stdout.write(result.externalErrors.length ? `World ${result.name}: teardown incomplete; lifecycle evidence retained\n`
       : `Stopped world ${result.name}${result.stopped.length ? `: ${result.stopped.join(', ')}` : ''}\n`);
@@ -278,6 +286,7 @@ export async function main(): Promise<void> {
       for (const message of result.externalErrors) process.stderr.write(`External teardown failed: ${message}\n`);
     }
     if (result.purged) {
+      for (const message of result.externalAbandoned ?? []) process.stdout.write(`Surrendered unavailable backend record (external stop unverified): ${message}\n`);
       process.stdout.write(`Purged instance data: ${result.purged}\n`);
     } else if (purge && result.externalErrors.length) {
       process.stdout.write(`Refused to purge instance data: an external service's teardown failed (see above) — its down command/discovered env must survive.\n`);
@@ -587,6 +596,7 @@ export async function main(): Promise<void> {
       follow: !rest.includes('--no-follow'),
       json: rest.includes('--json'),
       requests: rest.includes('--requests'),
+      logs: rest.includes('--logs'),
       signal: controller.signal,
     });
     return;
@@ -594,10 +604,12 @@ export async function main(): Promise<void> {
 
   if (cmd === 'seed' || cmd === 'reset') {
     if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world ${cmd} <world> [--entry <file>] [--cwd <dir>])`);
+    if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Reset accepts --env-out=<new-output-path>.');
+    const envFile = optionValue(rest, '--env-out') || undefined;
     const entry = optionValue(rest, '--entry') || undefined;
     const cwd = optionValue(rest, '--cwd') || undefined;
     const json = rest.includes('--json');
-    const outcome = cmd === 'seed' ? await seedWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) }) : await resetWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) });
+    const outcome = cmd === 'seed' ? await seedWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) }) : await resetWorld(subject, { root, ...(envFile ? { envFile } : {}), ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) });
     if (json) process.stdout.write(`${JSON.stringify({ world: outcome.world, entry: outcome.entry, exitCode: outcome.exitCode, observed: outcome.observed }, null, 2)}\n`);
     else process.stdout.write(`${cmd === 'reset' ? 'Reset' : 'Seeded'} world ${subject} from the placeholder remote (${outcome.entry})\n${Object.entries(outcome.observed).map(([s, n]) => `  ${s}: ${n} observed`).join('\n')}\n${outcome.exitCode === 0 ? '' : `  seed entry exited ${outcome.exitCode}\n`}`);
     process.exitCode = outcome.exitCode === 0 ? 0 : 1;
@@ -610,14 +622,14 @@ export async function main(): Promise<void> {
     if (!subject || !name) throw new Error('volter-world branch: usage: volter-world branch <world> <name> [--env-out=<path>]');
     const envFile = optionValue(rest, '--env-out') || undefined;
     const { instance, forked } = await branchWorld(subject, name, { root, forceEnvOutput: rest.includes('--force'), ...(envFile ? { envFile } : {}) });
-    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name, base: subject, forked }, null, 2)}\n`);
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name, instance: instance.instance, createdAt: instance.createdAt, base: subject, forked }, null, 2)}\n`);
     else { process.stdout.write(`Branched world ${name} from ${subject}\n${Object.entries(forked).map(([s, states]) => `  ${s}: mirror forked (${states.join(', ')})`).join('\n')}\n`); printReady(instance); }
     return;
   }
   if (cmd === 'checkout') {
     if (!subject) throw new Error('volter-world checkout: missing world name');
     const instance = await checkoutWorld(subject, { root });
-    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name }, null, 2)}\n`); else printReady(instance);
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name, instance: instance.instance, createdAt: instance.createdAt }, null, 2)}\n`); else printReady(instance);
     return;
   }
   if (cmd === 'fetch') {
@@ -975,7 +987,7 @@ export async function main(): Promise<void> {
     if (!envFile) throw new Error('volter-world run: missing required --env-out=<path>');
     const name = optionValue(worldArgs, '--name') || undefined;
     const mode = optionValue(worldArgs, '--mode', 'local') as 'local' | 'share' | 'sealed';
-    const result = await runWorld(subject, rest.slice(split + 1), { root, name, mode, envFile, forceEnvOutput: worldArgs.includes('--force'), owner: ownerOption(worldArgs), keep: worldArgs.includes('--keep'), verbose: worldArgs.includes('--verbose') });
+    const result = await runWorld(subject, rest.slice(split + 1), { root, cwd: process.cwd(), name, mode, envFile, forceEnvOutput: worldArgs.includes('--force'), owner: ownerOption(worldArgs), keep: worldArgs.includes('--keep'), verbose: worldArgs.includes('--verbose') });
     if (result.exitCode !== 0) {
       const detail = result.outcome.error ? `could not start (${result.outcome.error})`
         : result.outcome.signal ? `was terminated by ${result.outcome.signal}`
@@ -1027,7 +1039,7 @@ export async function main(): Promise<void> {
   if (cmd === 'unshare') {
     if (!subject) throw new Error('volter-world unshare: missing world name');
     const service = optionValue(rest, '--service') || undefined;
-    const result = unshareWorld(subject, { root, service });
+    const result = await unshareWorld(subject, { root, service });
     process.stdout.write(`Unshared world ${subject}${service ? `/${service}` : ''}\n`);
     if (result.escalated.length) process.stdout.write(`Escalated to SIGKILL (tunnel ignored SIGTERM past the grace): ${result.escalated.join(', ')}\n`);
     return;

package/src/cli.ts

@@ -2,12 +2,13 @@
 // volter-world: each command loads only what it needs. `up` (./up-cli.ts) starts the World's owner process
 // before any other command's modules load; every other command is ./cli-commands.ts.
 import { optionValue } from './cli-args.ts';
+import { errorMessage } from './error-message.ts';
 
 const [cmd, subject, ...rest] = process.argv.slice(2);
 const run = cmd === 'up' && subject !== '--help' && subject !== '-h'
   ? import('./up-cli.ts').then(({ upCommand }) => upCommand(subject, rest, optionValue(rest, '--root', process.cwd())))
   : import('./cli-commands.ts').then(({ main }) => main());
 run.catch((error) => {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(`${errorMessage(error)}\n`);
   process.exit(1);
 });

package/src/command-lifetime.d.mts

@@ -0,0 +1,12 @@
+import type { ChildProcess } from 'node:child_process';
+import type { SpawnIdentity } from './process-receipt.js';
+export const COMMAND_GRACE_MS: number;
+export const COMMAND_CONFIRM_MS: number;
+export const commandProcessGroup: boolean;
+export class CommandRetirementError extends Error {}
+export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean): {
+  identity: Promise<SpawnIdentity | undefined>;
+  cancel(signal: NodeJS.Signals): void;
+  readonly forwarded: NodeJS.Signals | undefined;
+  finish(): Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+};

package/src/command-lifetime.mjs

@@ -0,0 +1,90 @@
+import { offSignal } from './signals.mjs';
+import { survivingOwnedGroups } from './process-groups.mjs';
+import { childIdentity, signalOwnedProcess, signalChild } from './process-signal.mjs';
+
+export const COMMAND_GRACE_MS = 5_000;
+export const COMMAND_CONFIRM_MS = 1_000;
+export const commandProcessGroup = process.platform !== 'win32';
+export class CommandRetirementError extends Error {}
+
+/** The child owns a private POSIX group. A bounded retirement requires both closed output and
+ * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
+export function commandLifetime(child, abort, preserveOnSuccess = false) {
+  const identity = child.pid && commandProcessGroup ? childIdentity(child) : Promise.resolve(undefined);
+  let signalFailure;
+  let pendingSignals = 0;
+  let forwarded;
+  let code = null;
+  let exitSignal = null;
+  let exited = false;
+  let closed = false;
+  let deadline = 0;
+  let escalated = false;
+  let timer;
+  let resolveFinished;
+  let rejectFinished;
+  const finished = new Promise((resolve, reject) => { resolveFinished = resolve; rejectFinished = reject; });
+  finished.catch(() => {});
+  const signal = (value) => {
+    if (!child.pid) return;
+    try {
+      if (signalChild(child, value, commandProcessGroup)) return;
+      if (!commandProcessGroup || !alive()) return;
+      // The leader has exited: this is now retained numeric group ownership.
+      pendingSignals++;
+      void identity.then(birth => signalOwnedProcess(birth, value, true))
+        .catch(error => { signalFailure = error; })
+        .finally(() => { pendingSignals--; check(); });
+    } catch (error) { signalFailure = error; }
+  };
+  const alive = () => {
+    if (!child.pid) return false;
+    return survivingOwnedGroups([child.pid]).length > 0;
+  };
+  const detach = () => {
+    if (timer) clearInterval(timer);
+    offSignal('SIGINT', onInt);
+    offSignal('SIGTERM', onTerm);
+    abort?.removeEventListener('abort', onAbort);
+  };
+  const check = () => {
+    if (pendingSignals) return;
+    if (exited && closed && ((preserveOnSuccess && code === 0 && !forwarded) || !alive())) {
+      detach(); resolveFinished(); return;
+    }
+    if (deadline && Date.now() >= deadline) {
+      if (!escalated) { escalated = true; signal('SIGKILL'); deadline = Date.now() + COMMAND_CONFIRM_MS; }
+      else {
+        detach();
+        child.stdout?.destroy(); child.stderr?.destroy();
+        rejectFinished(new CommandRetirementError('Command retirement could not be confirmed; ownership and cleanup evidence retained', { cause: signalFailure }));
+      }
+    }
+  };
+  const watch = () => {
+    if (!deadline) deadline = Date.now() + COMMAND_GRACE_MS;
+    timer ??= setInterval(check, 20);
+    check();
+  };
+  const cancel = (value) => { forwarded ??= value; signal(value); watch(); };
+  const onInt = () => cancel('SIGINT');
+  const onTerm = () => cancel('SIGTERM');
+  const onAbort = () => cancel(abort?.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM');
+  process.on('SIGINT', onInt);
+  process.on('SIGTERM', onTerm);
+  abort?.addEventListener('abort', onAbort, { once: true });
+  if (abort?.aborted) onAbort();
+  child.once('exit', (value, signalValue) => {
+    code = value; exitSignal = signalValue; exited = true;
+    if (!(preserveOnSuccess && code === 0 && !forwarded)) signal('SIGTERM');
+    watch();
+  });
+  child.once('error', () => { if (!child.pid) { exited = true; watch(); } });
+  child.once('close', () => { closed = true; check(); });
+  return {
+    identity,
+    cancel,
+    get forwarded() { return forwarded; },
+    async finish() { await finished; await identity; return { code, signal: exitSignal }; },
+  };
+}

package/src/command-lifetime.ts

@@ -1,79 +1 @@
-import { offSignal } from './signals.ts';
-import type { ChildProcess } from 'node:child_process';
-import { survivingOwnedGroups } from './process-groups.ts';
-
-export const COMMAND_GRACE_MS = 5_000;
-export const commandProcessGroup = process.platform !== 'win32';
-export class CommandRetirementError extends Error {}
-
-/** The child owns a private POSIX group. A bounded retirement requires both closed output and
- * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
-export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess = false) {
-  let forwarded: NodeJS.Signals | undefined;
-  let code: number | null = null;
-  let exitSignal: NodeJS.Signals | null = null;
-  let exited = false;
-  let closed = false;
-  let deadline = 0;
-  let escalated = false;
-  let timer: ReturnType<typeof setInterval> | undefined;
-  let resolveFinished!: () => void;
-  let rejectFinished!: (error: Error) => void;
-  const finished = new Promise<void>((resolve, reject) => { resolveFinished = resolve; rejectFinished = reject; });
-  finished.catch(() => {});
-  const signal = (value: NodeJS.Signals): void => {
-    if (!child.pid) return;
-    try {
-      if (commandProcessGroup) process.kill(-child.pid, value);
-      else child.kill(value);
-    } catch { /* retirement is proved below, never inferred from signal delivery */ }
-  };
-  const alive = (): boolean => {
-    if (!child.pid) return false;
-    return survivingOwnedGroups([child.pid]).length > 0;
-  };
-  const detach = () => {
-    if (timer) clearInterval(timer);
-    offSignal('SIGINT', onInt);
-    offSignal('SIGTERM', onTerm);
-    abort?.removeEventListener('abort', onAbort);
-  };
-  const check = () => {
-    if (exited && closed && ((preserveOnSuccess && code === 0 && !forwarded) || !alive())) {
-      detach(); resolveFinished(); return;
-    }
-    if (deadline && Date.now() >= deadline) {
-      if (!escalated) { escalated = true; signal('SIGKILL'); deadline = Date.now() + 1_000; }
-      else {
-        detach();
-        child.stdout?.destroy(); child.stderr?.destroy();
-        rejectFinished(new CommandRetirementError('Command retirement could not be confirmed; ownership and cleanup evidence retained'));
-      }
-    }
-  };
-  const watch = () => {
-    if (!deadline) deadline = Date.now() + COMMAND_GRACE_MS;
-    timer ??= setInterval(check, 20);
-    check();
-  };
-  const cancel = (value: NodeJS.Signals): void => { forwarded ??= value; signal(value); watch(); };
-  const onInt = () => cancel('SIGINT');
-  const onTerm = () => cancel('SIGTERM');
-  const onAbort = () => cancel(abort?.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM');
-  process.on('SIGINT', onInt);
-  process.on('SIGTERM', onTerm);
-  abort?.addEventListener('abort', onAbort, { once: true });
-  if (abort?.aborted) onAbort();
-  child.once('exit', (value, signalValue) => {
-    code = value; exitSignal = signalValue; exited = true;
-    if (!(preserveOnSuccess && code === 0 && !forwarded)) signal('SIGTERM');
-    watch();
-  });
-  child.once('error', () => { if (!child.pid) { exited = true; watch(); } });
-  child.once('close', () => { closed = true; check(); });
-  return {
-    cancel,
-    get forwarded() { return forwarded; },
-    async finish() { await finished; return { code, signal: exitSignal }; },
-  };
-}
+export { COMMAND_GRACE_MS, COMMAND_CONFIRM_MS, commandProcessGroup, CommandRetirementError, commandLifetime } from './command-lifetime.mjs';

package/src/configs.ts

@@ -33,7 +33,7 @@ export function writeWorldConfig(path: string, config: WorldConfig): void {
 }
 
 const LEGACY_TOP_LEVEL = new Set(['id', 'description', 'bare', 'remotes', 'resources', 'isolation', 'env', 'stripEnv', 'services', 'share', 'actors', 'fixtures', 'catalog', 'network']);
-const LEGACY_SERVICE = new Set(['id', 'type', 'package', 'command', 'args', 'cwd', 'port', 'portReason', 'env', 'controlPlane', 'injectEnv', 'injectEnvTemplates', 'root', 'rootArg', 'portArg', 'cliRedirect', 'ready', 'preload', 'external', 'colocate', 'version']);
+const LEGACY_SERVICE = new Set(['id', 'type', 'package', 'command', 'args', 'cwd', 'port', 'portReason', 'env', 'controlPlane', 'branchState', 'injectEnv', 'injectEnvTemplates', 'root', 'rootArg', 'portArg', 'cliRedirect', 'ready', 'preload', 'external', 'colocate', 'version']);
 const LEGACY_NESTED = {
   bare: new Set(['name']), resources: new Set(['memoryMiB', 'writableStorageMiB']), catalog: new Set(['sha', 'protocol']),
   root: new Set(['url', 'deploy', 'refresh', 'scope']), refresh: new Set(['every', 'webhook']),

package/src/console-apart.ts

@@ -5,6 +5,7 @@
 // forwarded to the host — never a twin's path, so no twin-served script ever runs on this origin.
 // The console opens a World's pages (a vendor's screens) on the Worlds' origin, which it is told.
 
+import { errorMessage } from './error-message.ts';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 
 /** What a console offers a host: its shell and assets under `base`, told where the Worlds are served. */
@@ -53,7 +54,7 @@ export async function serveConsoleFor(target: string, opts: { hostname?: string;
   let mount: ConsoleMount;
   try { mount = ((await import('@volter/world-console')) as { createConsole: () => ConsoleMount }).createConsole(); }
   catch (error) {
-    if (error instanceof Error && /Cannot find (module|package)/.test(error.message)) throw new Error('the console is not installed: add @volter/world-console beside @volter/world');
+    if (error instanceof Error && /Cannot find (module|package)/.test(errorMessage(error))) throw new Error('the console is not installed: add @volter/world-console beside @volter/world', { cause: error });
     throw error;
   }
   const hostname = opts.hostname ?? '127.0.0.1';

package/src/covers.ts

@@ -22,11 +22,13 @@
 //             unknown-sdk → exit 1 by default (`--allow-unknown` downgrades to a warning:
 //             unknowns still print, but stop failing the proof).
 
+import { errorMessage } from './error-message.ts';
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { vendorOfPackModule } from '@volter/world-core/runtime';
 import { loadWorldConfig } from './configs.ts';
+import { VENDOR_SERVER_BACKINGS } from './backings.ts';
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from './inject-map.ts';
 import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from './project-inspect.ts';
 import { overlayCoversMaps, packFacts } from './pack-facts.ts';
@@ -340,6 +342,7 @@ export type WorldTwinId = {
 };
 
 type WorldTwinInventory = {
+  services: Array<WorldServiceConfig | WorldServiceInstance>;
   source: 'instance' | 'config';
   path: string;
   /** normalized identifier → id record (e.g. 'stripe' → { label: 'stripe (service)', … }) */
@@ -350,15 +353,56 @@ type WorldTwinInventory = {
   declared: Map<string, WorldTwinId>;
 };
 
-function declaredTwin(services: Array<WorldServiceConfig | WorldServiceInstance>): Map<string, WorldTwinId> {
+/** Identity comes from the registered wrapper, not an arbitrary process with the vendor's name. */
+function serverBacking(service: WorldServiceConfig | WorldServiceInstance) {
+  const backing = VENDOR_SERVER_BACKINGS[service.id];
+  if (!backing || service.type !== backing.service.type) return undefined;
+  // an instance records the whole argv in `command`; a config splits it into `command` and `args`
+  const command = Array.isArray(service.command) ? service.command : [service.command, ...(('args' in service ? service.args : undefined) ?? [])];
+  if (!command[0] || basename(command[0]) !== backing.service.command || command[1] !== backing.service.args?.[0]) return undefined;
+  return backing;
+}
+
+function addBackingIds(
+  ids: Map<string, WorldTwinId>,
+  services: Array<WorldServiceConfig | WorldServiceInstance>,
+  effectiveEnv?: Record<string, string>,
+): void {
+  for (const service of services) {
+    const backing = serverBacking(service);
+    if (backing) {
+      const template = backing.facts.endpointEnv.templates[backing.facts.endpointEnv.name];
+      const instance = 'pid' in service;
+      const values = instance ? service.env : service.injectEnvTemplates ?? {};
+      const endpoint = instance && service.url && service.port ? template?.replaceAll('${host}', new URL(service.url).hostname)
+        .replaceAll('${port}', String(service.port)).replaceAll('${url}', service.url) : undefined;
+      const routed = template !== undefined && (instance
+        ? endpoint !== undefined && Object.entries(values).some(([name, value]) => value === endpoint && effectiveEnv?.[name] === value)
+        : service.port !== undefined && Object.values(values).includes(template));
+      addId(ids, normalizeId(service.id), `${service.id} (server backing)`, routed);
+    }
+    // A protocol already proved owned by this service can satisfy its declared native driver.
+    // HTTP-only siblings of the same vendor retain their independent interface obligations.
+    for (const binding of serviceConnections([service], effectiveEnv).values()) {
+      for (const [vendor, facts] of Object.entries(packFacts())) {
+        if (facts.transport === 'raw-tcp' && facts.managedService?.scheme === binding.protocol) {
+          addId(ids, normalizeId(vendor), `${binding.label}; managed ${facts.managedService.kind} backing`, true);
+        }
+      }
+    }
+  }
+}
+
+function declaredTwin(services: Array<WorldServiceConfig | WorldServiceInstance>, effectiveEnv?: Record<string, string>): Map<string, WorldTwinId> {
   const declared = new Map<string, WorldTwinId>();
   for (const service of services) {
-    if (service.type !== undefined && service.type !== 'twin') continue;
+    if (service.type !== undefined && service.type !== 'twin' && !serverBacking(service)) continue;
     const config = service as WorldServiceConfig;
     const identity = config.package?.match(/^@volter\/twin-(.+)$/)?.[1] ?? servicePackNames(config)[0] ?? service.id;
     const vendor = Object.keys(packFacts()).find((candidate) => worldIdsFor(candidate).includes(normalizeId(identity))) ?? identity;
     const ids = new Map<string, WorldTwinId>();
-    addServiceIds(ids, service);
+    if (!serverBacking(service)) addServiceIds(ids, service);
+    addBackingIds(ids, [service], effectiveEnv);
     const match = [...worldIdsFor(vendor), vendor].map(normalizeId).map((id) => ids.get(id)).find(Boolean);
     declared.set(vendor, match ?? { label: `${service.id} (declared twin)`, interceptable: false });
   }
@@ -373,14 +417,22 @@ function addId(ids: Map<string, WorldTwinId>, key: string, label: string, interc
   else if (interceptable && !existing.interceptable) existing.interceptable = true;
 }
 
-function servicePackNames(service: { package?: string; command?: string | string[]; args?: string[]; colocate?: { module?: string } }): string[] {
+function servicePackNames(service: { id?: string; package?: string; command?: string | string[]; args?: string[]; colocate?: { module?: string } }): string[] {
   const commandParts = [
     ...(service.package ? [service.package] : []),
     ...(Array.isArray(service.command) ? service.command : service.command ? [service.command] : []),
     ...(service.args ?? []),
     ...(service.colocate?.module ? [service.colocate.module] : []),
   ];
-  return commandParts.flatMap((part) => {
+  return commandParts.flatMap((argument, index) => {
+    // A shared host command is recorded on each service. Only that service's
+    // module identifies its pack; its neighbours' modules must not cover it.
+    let part = argument;
+    if (commandParts[index - 1] === '--spec') {
+      const [id, module] = argument.split('|');
+      if (id !== service.id || !module) return [];
+      part = module;
+    }
     const fromPath = part.match(/(?:^|[/\\])twin-packs-p[23][/\\]([a-z0-9-]+)[/\\]/);
     const fromBin = part.match(/^world-([a-z0-9-]+)$/);
     const fromPkg = part.match(/(?:^|[/\\])@volter\/twin-([a-z0-9-]+)(?:[/\\]|$)/);
@@ -519,29 +571,31 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
   try {
     const status = statusWorld(world, root, { readOnly: true });
     const ids = new Map<string, WorldTwinId>();
-    for (const service of Object.values(status.services)) addServiceIds(ids, service);
+    for (const service of Object.values(status.services)) if (!serverBacking(service)) addServiceIds(ids, service);
+    addBackingIds(ids, Object.values(status.services), status.env);
     for (const key of Object.keys(status.env)) {
       const stem = key.match(/^(.+)_TWIN_URL$/);
       // a bare env `*_TWIN_URL` var is only a REACHABLE twin when the injector reads it
       if (stem) addId(ids, normalizeId(stem[1]!), `env ${key}`, twinUrlVendorFor(key) !== null);
     }
-    return { source: 'instance', path: `${status.dirs.instance}/instance.json`, ids, connections: serviceConnections(Object.values(status.services), status.env), selection: status.selection, declared: declaredTwin(Object.values(status.services)) };
+    return { services: Object.values(status.services), source: 'instance', path: `${status.dirs.instance}/instance.json`, ids, connections: serviceConnections(Object.values(status.services), status.env), selection: status.selection, declared: declaredTwin(Object.values(status.services), status.env) };
   } catch (error) {
-    instanceError = error instanceof Error ? error.message : String(error);
+    instanceError = errorMessage(error);
   }
   try {
     const { path, config } = loadWorldConfig(world, root);
     const ids = new Map<string, WorldTwinId>();
-    for (const service of config.services as WorldServiceConfig[]) addServiceIds(ids, service);
+    for (const service of config.services as WorldServiceConfig[]) if (!serverBacking(service)) addServiceIds(ids, service);
+    addBackingIds(ids, config.services);
     const connections = serviceConnections(config.services);
     // a name the World's env leaves to a twin's credential door (`$issue:<service>`) is that twin's, whatever scheme the
     // issued value has: the twin that issues it serves it
     for (const [name, value] of Object.entries(config.env ?? {})) {
       if (value.startsWith(ISSUE_ENV_PREFIX)) connections.set(name, { protocol: 'issued', label: `${value.slice(ISSUE_ENV_PREFIX.length)} (${name}; issued)` });
     }
-    return { source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services) };
+    return { services: config.services, source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services) };
   } catch (error) {
-    const configError = error instanceof Error ? error.message : String(error);
+    const configError = errorMessage(error);
     throw new Error(
       `volter-world covers: world "${world}" not found as an instance or a config.\n` +
       `  instance: ${instanceError}\n  config: ${configError}`,
@@ -614,7 +668,14 @@ function usesOf(signals: Map<string, string[]>): Map<string, Array<{ usage: Worl
  * directly to fetch in production source. URL attribution reads the injector's VENDOR_HOSTS table
  * rather than re-encoding host rules here. Insertion order follows the sorted dependency, env-name,
  * and source lists, so callers that preserve it are deterministic. */
-export function detectRepoVendors(repoPath: string): RepoVendorSignals {
+export function detectRepoVendors(repoPath: string, services: Array<WorldServiceConfig | WorldServiceInstance> = []): RepoVendorSignals {
+  // Application aliases are names the selected backing actually injects, never global vendor adoption.
+  const backingEnvVendors = new Map<string, string>();
+  for (const service of services) {
+    if (!serverBacking(service)) continue;
+    const bindings = 'pid' in service ? service.env : service.injectEnvTemplates;
+    for (const name of Object.keys(bindings ?? {})) backingEnvVendors.set(name, service.id);
+  }
   const repo = resolve(repoPath);
   // the platform's own packages — the twins an app installed, the command, the runtime — are
   // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency.
@@ -660,7 +721,7 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
       detected.set('smtp', [...(detected.get('smtp') ?? []), `env: ${name}`]);
       continue;
     }
-    const vendor = envStemVendor(name, ENV_SUFFIX_BROAD);
+    const vendor = backingEnvVendors.get(name) ?? envStemVendor(name, ENV_SUFFIX_BROAD);
     if (vendor) detected.set(vendor, [...(detected.get(vendor) ?? []), `env: ${name}`]);
   }
 
@@ -684,6 +745,9 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
     ...Object.values(SDK_TWINS).map((entry) => entry.vendor),
     ...Object.values(ENV_STEM_VENDORS),
     ...Object.keys(VENDOR_WORLD_IDS),
+    // a pack whose vendor is called only by its hosts (no SDK, no credential: Poly Haven's and ambientCG's public
+    // catalogs) is known by its descriptor's hosts, or a raw fetch matched to it would be dropped here
+    ...Object.entries(packFacts()).filter(([, facts]) => (facts.hosts ?? []).length).map(([vendor]) => vendor),
   ]) knownVendorById.set(normalizeId(vendor), vendor);
   const canonicalVendor = (injectorKey: string): string | null => {
     const key = normalizeId(injectorKey);
@@ -765,7 +829,7 @@ export function detectRepoVendors(repoPath: string): RepoVendorSignals {
     if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name)) continue;
     if (isSmtpEnvSignal(name)) continue; // now a DETECTED vendor (above), no longer an unknown
     const stem = envVendorStem(name, ENV_SUFFIX_STRICT);
-    if (stem === null || envStemVendor(name, ENV_SUFFIX_STRICT) || ENV_STEM_IGNORE.has(stem)) continue;
+    if (stem === null || backingEnvVendors.has(name) || envStemVendor(name, ENV_SUFFIX_STRICT) || ENV_STEM_IGNORE.has(stem)) continue;
     // The registry's notExternal suppressions apply to ENV STEMS too — the census adjudicated
     // 40 app-internal stems ("names no vendor") that this loop kept flagging because only the
     // dep-side checks consulted the registry (§9 round two H4, 2026-08-31: 17 of 18 formally
@@ -786,7 +850,7 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
   const repo = resolve(repoPath);
   const inventory = worldTwinInventory(world, root);
 
-  const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo);
+  const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services);
 
   // Does ANY injector vendor key exist for this vendor? Decides whether an UNINTERCEPTABLE
   // finding is acknowledgeable: a key that exists means the twin COULD be intercepted and the
@@ -812,7 +876,14 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
     // twin (no injector vendor, no app-read endpoint env) is a distinct, failing status.
     const candidates = worldIdsFor(vendor).filter((id) => inventory.ids.has(id));
     const matchId = candidates.find((id) => inventory.ids.get(id)!.interceptable) ?? candidates[0];
-    const match = matchId === undefined ? null : inventory.ids.get(matchId)!;
+    const managed = packFacts()[vendor]?.managedService;
+    // Only a booted, service-owned endpoint establishes a managed pack's reachable wire.
+    const managedBinding = inventory.source === 'instance' && managed
+      ? [...inventory.connections.values()].find(binding => binding.protocol === managed.scheme)
+      : undefined;
+    const match = matchId === undefined
+      ? managedBinding ? { label: managedBinding.label, interceptable: true } : null
+      : inventory.ids.get(matchId)!;
     let status: CoverageStatus = match === null ? 'missing' : match.interceptable ? 'covered' : 'uninterceptable';
     let ackRefused: string | undefined;
     if (acknowledge[vendor] !== undefined) {
@@ -884,9 +955,16 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
 
   for (const requirement of projectConnections(repo, new Set(
     [...detected.values(), ...unknownSources.values()].flat().filter((source) => source.startsWith('env: ')).map((source) => source.slice(5)),
-  ))) {
+  ), new Map([...inventory.connections].flatMap(([name, binding]) =>
+    binding.protocol && !['http', 'issued', 'incompatible'].includes(binding.protocol) ? [[name, binding.protocol] as const] : [])))) {
     const vendor = `${requirement.protocol ?? 'unknown-connection'}:${requirement.env ?? requirement.sources[0]}`;
-    if (inventory.selection !== undefined && !worldSelectionIncludes(inventory.selection, vendor, 'application')) {
+    const connectionNames = [vendor, ...(requirement.protocol ? [requirement.protocol] : [])];
+    const selectorMatches = (selector: WorldSelection['include'][number]) =>
+      (selector.usage === undefined || selector.usage === 'application') &&
+      (selector.vendor === undefined || connectionNames.includes(selector.vendor));
+    const connectionSelected = inventory.selection === undefined ||
+      (inventory.selection.include.some(selectorMatches) && !inventory.selection.exclude.some(selectorMatches));
+    if (!connectionSelected) {
       excluded.push(vendor);
       rows.push({
         vendor,

package/src/error-message.d.mts

@@ -0,0 +1 @@
+export function errorMessage(error: unknown): string;

package/src/error-message.mjs

@@ -0,0 +1,10 @@
+/** Operator-facing failures include aggregate members and retained causes. */
+export function errorMessage(error, seen = new Set()) {
+  const message = error && typeof error === 'object' && 'message' in error ? String(error.message) : String(error);
+  if (seen.has(error)) return '[circular error]';
+  seen.add(error);
+  const details = error instanceof AggregateError ? Array.from(error.errors, member => errorMessage(member, seen)) : [];
+  if (error instanceof Error && error.cause !== undefined) details.push(`cause: ${errorMessage(error.cause, seen)}`);
+  seen.delete(error);
+  return [message, ...details.map(detail => detail.split('\n').map(line => `  ${line}`).join('\n'))].join('\n');
+}

package/src/error-message.ts

@@ -0,0 +1,2 @@
+// The native Node hosts and typed runtime entrypoints use the same renderer.
+export { errorMessage } from './error-message.mjs';

package/src/guest-command.d.mts

@@ -0,0 +1,4 @@
+export function admitGuestArgv(argv: string[], runtime: string, root: string, cwd: string): { argv: string[]; cwd: string };
+export function guestCommandGap(message: string): Error & { code: string };
+export function guestEnvironment(env: Record<string, string>): Record<string, string>;
+export function guestEnvironment(env: Record<string, string | undefined>): Record<string, string | undefined>;

package/src/guest-command.mjs

@@ -0,0 +1,26 @@
+// Declared execution limits reach packs as capability gaps, never vendor launch failures.
+export const guestCommandGap = message => Object.assign(new Error(message), { code: 'WORLD_MACHINE_CAPABILITY_GAP' });
+// Only World routing may restore Node preload/CA configuration after caller controls are stripped.
+export function guestEnvironment(env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => !/^(NODE_|LD_|DYLD_|SUBSTRATE_|OPENSSL_CONF$|OPENSSL_MODULES$)/i.test(key)));
+}
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+// Interim admission list: the image's Node runtime and an ordinary JS file inside its folder.
+export function admitGuestArgv(argv, runtime, root, cwd) {
+  if (runtime !== 'node' || !Array.isArray(argv) || argv.length < 2 || !argv.every(value => typeof value === 'string' && !value.includes('\0')) || argv[0] !== 'node') {
+    throw guestCommandGap(`unsupported guest command ${Array.isArray(argv) ? argv[0] : '(invalid argv)'}; admitted program: node with an image entry file`);
+  }
+  if (argv[1].startsWith('-')) throw guestCommandGap('unsupported Node option/eval; guest command requires an image entry file');
+  const folder = realpathSync(root);
+  const within = path => {
+    const real = realpathSync(path), rest = relative(folder, real);
+    if (rest === '..' || rest.startsWith('../') || isAbsolute(rest)) throw guestCommandGap('guest command path leaves its folder');
+    return real;
+  };
+  const directory = within(cwd);
+  if (!statSync(directory).isDirectory()) throw guestCommandGap('guest command cwd is not a directory');
+  const entry = resolve(directory, argv[1]);
+  if (!existsSync(entry) || !/\.(?:mjs|cjs|js)$/.test(entry) || !statSync(within(entry)).isFile()) throw guestCommandGap('guest command needs an ordinary JS entry file in its folder');
+  return { argv: ['node', within(entry), ...argv.slice(2)], cwd: directory };
+}

package/src/guest-control.d.mts

@@ -0,0 +1 @@
+export function guestControl<T>(operation: (signal: AbortSignal) => Promise<T>, label: string, signal?: AbortSignal, budget?: number): Promise<T>;