@volter/twin-world 0.1.0 → 0.1.2

package/src/runtime.ts

@@ -1,13 +1,18 @@
 import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { createServer } from 'node:net';
-import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync, writeSync, existsSync } from 'node:fs';
+import { createServer, isIP } from 'node:net';
+import { constants as osConstants, hostname as osHostname } from 'node:os';
+import { appendFileSync, chmodSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, writeSync, existsSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { Socket } from 'node:net';
-import { withFileLock } from '@volter/twin';
+import { buildLocalActionPlan, recordPlanReview, withFileLock, stateDirName} from '@volter/twin';
+import type { LocalActionPlan, PlanReviewDecision, PlanReviewRecord } from '@volter/twin';
 import { loadWorldConfig } from './configs.ts';
+import { inertInjectEnvWarnings } from './inject-map.ts';
 import { activeVendorMap, ensureCa, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from './redirect-proxy.ts';
-import type { WorldConfig, WorldExternalReadyWhen, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceInstance } from './schema.ts';
+import type { WorldConfig, WorldExternalReadyWhen, WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome, WorldRunRecord, WorldServiceConfig, WorldServiceInstance } from './schema.ts';
+import { claimWorldResources, handoffWorldResourceClaim, recordWorldResourceEvent, releaseWorldResources, requestedWorldResources } from './resources.ts';
 
 const requireFromHere = createRequire(import.meta.url);
 
@@ -27,6 +32,7 @@ export type ShareWorldOptions = {
   provider?: 'cloudflare-quick' | 'command';
   command?: string;
   args?: string[];
+  ephemeral?: boolean;
   timeoutMs?: number;
   verifyPath?: string | false;
 };
@@ -63,7 +69,11 @@ export type WorldUrlInfo = {
 };
 
 function worldBaseDir(root: string): string {
-  return join(root, '.volter', 'worlds');
+  // `stateDirName()`, not a literal: VOLTER_STATE_DIR is the documented way to point a process at
+  // a different state directory, and control-plane honours it everywhere. This package did not,
+  // so a caller that set it got worlds written under `.volter/` while the kernel read from the
+  // requested directory — two halves of the same world in two places.
+  return join(root, stateDirName(), 'worlds');
 }
 
 /** World names become a path segment (instanceDir/instanceLockFile) and must never let a
@@ -75,7 +85,16 @@ function assertSafeWorldName(name: string): void {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) throw new Error(`Invalid world name: ${name}`);
 }
 
-function instanceDir(root: string, name: string): string {
+/** Exported for the reflect attachment (reflect.ts), whose routes file lives in
+ * the instance dir — one layout owner, no duplicated path knowledge. */
+/** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
+ *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
+ *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+export function clockFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'clock');
+}
+
+export function instanceDir(root: string, name: string): string {
   return join(worldBaseDir(root), name);
 }
 
@@ -83,6 +102,10 @@ function instanceFile(root: string, name: string): string {
   return join(instanceDir(root, name), 'instance.json');
 }
 
+function foregroundRunFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'foreground-run.json');
+}
+
 /** Lockfile guarding the synchronous claim-of-the-instance-dir section of `upWorld` (TWIN-36).
  * It must survive the claim's own `rmSync` of the instance dir, so it lives BESIDE the dirs in
  * a dot-prefixed sibling: world names must start with an alphanumeric, so `.locks` can never
@@ -91,6 +114,102 @@ function instanceLockFile(root: string, name: string): string {
   return join(worldBaseDir(root), '.locks', `${name}.lock`);
 }
 
+const SHARE_CLAIM_STALE_MS = 60_000;
+const SHARE_CLAIM_HEARTBEAT_MS = 5_000;
+
+type SharingClaim = {
+  token: string;
+  pid: number;
+  hostname: string;
+  serviceId?: string;
+  processIdentity?: string;
+  claimedAt: string;
+  heartbeatAt: string;
+};
+
+function processStartIdentity(pid: number): string | undefined {
+  const result = spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8' });
+  if (result.status !== 0) return undefined;
+  const value = result.stdout.trim();
+  return value || undefined;
+}
+
+const currentProcessIdentity = processStartIdentity(process.pid);
+
+function sharingClaimFile(root: string, name: string): string {
+  return join(worldBaseDir(root), '.locks', `${name}.share.json`);
+}
+
+function readSharingClaim(path: string): SharingClaim | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const claim = JSON.parse(readFileSync(path, 'utf8')) as SharingClaim;
+    if (!claim || typeof claim !== 'object' || typeof claim.token !== 'string'
+      || !Number.isInteger(claim.pid) || claim.pid <= 0 || typeof claim.hostname !== 'string'
+      || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string'
+      || (claim.serviceId !== undefined && typeof claim.serviceId !== 'string')
+      || (claim.processIdentity !== undefined && typeof claim.processIdentity !== 'string')) return undefined;
+    return claim;
+  } catch { return undefined; }
+}
+
+function sharingClaimAlive(claim: SharingClaim): boolean {
+  const heartbeatAt = Date.parse(claim.heartbeatAt);
+  const heartbeatAge = Date.now() - heartbeatAt;
+  const fresh = Number.isFinite(heartbeatAt)
+    && heartbeatAge >= -SHARE_CLAIM_STALE_MS && heartbeatAge <= SHARE_CLAIM_STALE_MS;
+  if (claim.hostname !== osHostname()) return fresh;
+  if (livePids([claim.pid]).length === 0) return false;
+  const identity = processStartIdentity(claim.pid);
+  if (claim.processIdentity && identity) return claim.processIdentity === identity;
+  // A legacy or ps-uninspectable claim cannot rely on pid alone: pid reuse would wedge sharing.
+  // Its owner heartbeat keeps it live, while a crashed claim becomes reclaimable on a bound.
+  return fresh;
+}
+
+async function reserveSharingClaim(root: string, name: string, serviceId: string): Promise<SharingClaim> {
+  const path = sharingClaimFile(root, name);
+  mkdirSync(dirname(path), { recursive: true });
+  while (true) {
+    const claim = withFileLock(`${path}.lock`, () => {
+      const existing = readSharingClaim(path);
+      if (existing && sharingClaimAlive(existing)) {
+        if (existing.serviceId === serviceId) {
+          throw new Error(`World "${name}" service "${serviceId}" is already being shared by pid ${existing.pid}`);
+        }
+        return undefined;
+      }
+      const now = new Date().toISOString();
+      const reserved: SharingClaim = {
+        token: randomUUID(), pid: process.pid, hostname: osHostname(), serviceId,
+        claimedAt: now, heartbeatAt: now,
+        ...(currentProcessIdentity ? { processIdentity: currentProcessIdentity } : {}),
+      };
+      writeTextAtomic(path, `${JSON.stringify(reserved)}\n`);
+      return reserved;
+    });
+    if (claim) return claim;
+    // A different service is mutating the same instance/pids projection. Wait for its bounded,
+    // heartbeated claim to settle, then reload the committed instance before starting this child.
+    await sleep(50);
+  }
+}
+
+function refreshSharingClaim(root: string, name: string, token: string): void {
+  const path = sharingClaimFile(root, name);
+  withFileLock(`${path}.lock`, () => {
+    const claim = readSharingClaim(path);
+    if (claim?.token === token) writeTextAtomic(path, `${JSON.stringify({ ...claim, heartbeatAt: new Date().toISOString() })}\n`);
+  });
+}
+
+function releaseSharingClaim(root: string, name: string, token: string): void {
+  const path = sharingClaimFile(root, name);
+  withFileLock(`${path}.lock`, () => {
+    if (readSharingClaim(path)?.token === token) rmSync(path, { force: true });
+  });
+}
+
 /** Claim marker a winning `upWorld` writes into the freshly-wiped instance dir — under the
  * instance lock, before releasing it — and removes once its boot attempt settles. It is what
  * keeps later claimants out for the whole (async, possibly long) boot: mid-boot there are no
@@ -294,17 +413,36 @@ function tunnelPids(instance: WorldInstance): number[] {
     .filter((pid): pid is number => Boolean(pid));
 }
 
+let atomicWriteSequence = 0;
+function writeTextAtomic(path: string, value: string): void {
+  const temporary = `${path}.${process.pid}.${Date.now()}.${atomicWriteSequence++}.tmp`;
+  try {
+    writeFileSync(temporary, value, { mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function openPrivateLog(path: string, flags: 'a' | 'w'): number {
+  const descriptor = openSync(path, flags, 0o600);
+  chmodSync(path, 0o600);
+  return descriptor;
+}
+
 function writePidsFromInstance(instance: WorldInstance): void {
   // Deduped: co-located services share the single host child's pid.
   const pids = [...new Set([
     ...Object.values(instance.services).map((service) => service.pid),
     ...tunnelPids(instance),
+    ...(instance.resources?.holderPid ? [instance.resources.holderPid] : []),
   ].filter((pid) => Number.isInteger(pid) && pid > 0))];
-  writeFileSync(instance.pidsFile, `${pids.join('\n')}\n`);
+  writeTextAtomic(instance.pidsFile, `${pids.join('\n')}\n`);
 }
 
 function saveWorldInstance(instance: WorldInstance): void {
-  writeFileSync(instanceFile(instance.root, instance.name), `${JSON.stringify(instance, null, 2)}\n`);
+  writeTextAtomic(instanceFile(instance.root, instance.name), `${JSON.stringify(instance, null, 2)}\n`);
 }
 
 /** The co-located host CHILD process cannot safely rewrite instance.json out from under the
@@ -328,11 +466,38 @@ function mergeWorkerGaveUp(instance: WorldInstance, instancePath: string): void
   }
 }
 
+/** `world run` persists this sidecar before the foreground consumer starts. If the runner itself
+ * is hard-killed, it cannot record its own signal or execute `finally`; the next World read turns
+ * that orphaned running marker into an explicit, durable abrupt-termination diagnosis. */
+function mergeForegroundRun(instance: WorldInstance): void {
+  const path = foregroundRunFile(instance.root, instance.name);
+  if (!existsSync(path)) return;
+  try {
+    let record = JSON.parse(readFileSync(path, 'utf8')) as WorldRunRecord;
+    if (record.state === 'running' && !isAlive(record.runnerPid)) {
+      record = {
+        state: 'abrupt',
+        runnerPid: record.runnerPid,
+        ...(record.consumerPid ? { consumerPid: record.consumerPid } : {}),
+        startedAt: record.startedAt,
+        observedAt: new Date().toISOString(),
+        log: record.log,
+        error: 'World runner disappeared without an exit record; it was hard-killed or its host/session terminated abruptly',
+      };
+      writeTextAtomic(path, `${JSON.stringify(record, null, 2)}\n`);
+    }
+    instance.lastRun = record;
+  } catch {
+    // Preserve instance readability if a process vanished between the sidecar's atomic writes.
+  }
+}
+
 function readWorldInstance(name: string, root: string): WorldInstance {
   const path = instanceFile(root, name);
   if (!existsSync(path)) throw new Error(`World instance not found: ${name}`);
   const instance = JSON.parse(readFileSync(path, 'utf8')) as WorldInstance;
   mergeWorkerGaveUp(instance, path);
+  mergeForegroundRun(instance);
   return instance;
 }
 
@@ -399,8 +564,9 @@ async function runExternalUp(
   if (!commandExists(bin)) {
     throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the up command's tool is not installed)`);
   }
-  writeFileSync(logPath, `$ ${command.join(' ')}\n`);
-  const out = openSync(logPath, 'a');
+  writeFileSync(logPath, `$ ${command.join(' ')}\n`, { mode: 0o600 });
+  chmodSync(logPath, 0o600);
+  const out = openPrivateLog(logPath, 'a');
   const chunks: string[] = [];
   try {
     const code = await new Promise<number | null>((resolveCode, reject) => {
@@ -483,20 +649,28 @@ async function startExternalService(
   const external = service.external;
   if (!external) throw new Error(`External service "${service.id}" is missing its external config`);
   const log = join(paths.logs, `${service.id}.log`);
+  const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
   // External commands see the accumulated world env (process.env + earlier services' discovered/
   // injected vars), so a later external can consume an earlier service's connection info.
-  const env: NodeJS.ProcessEnv = { ...process.env, ...worldEnv };
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...worldEnv,
+    ...(service.env ?? {}),
+    VOLTER_WORLD_SERVICE_ID: service.id,
+    VOLTER_WORLD_SERVICE_LOG: log,
+  };
+  if (service.controlPlane) for (const key of CONTROL_PLANE_EGRESS_ENV) delete env[key];
 
   // 1. up — start the self-managed stack, STREAMING its output to the service log (no 1MB cap).
-  const upOutput = await runExternalUp(external.up, paths.root, service.id, env, log);
+  const upOutput = await runExternalUp(external.up, cwd, service.id, env, log);
 
   // 2. readiness — Docker-backed externals take seconds to boot.
-  await awaitReadiness(external.readyWhen, log, paths.root, service.id, env);
+  await awaitReadiness(external.readyWhen, log, cwd, service.id, env);
 
   // 3. status — discover connection info (optional; may reuse up output instead).
   let statusOutput = '';
   if (external.status) {
-    const statusResult = runExternalCommand(external.status, paths.root, service.id, 'status', env);
+    const statusResult = runExternalCommand(external.status, cwd, service.id, 'status', env);
     statusOutput = statusResult.stdout || statusResult.stderr;
     appendFileSync(log, `\n$ ${external.status.join(' ')}\n${statusOutput}`);
   }
@@ -540,10 +714,23 @@ async function startExternalService(
     log,
     env: injected,
     // Keep the discovered env on the instance so `down` can reference connection info it needs.
-    external: { down: [...external.down], cwd: paths.root, discoveredEnv: injected },
+    external: { down: [...external.down], cwd, discoveredEnv: injected },
   };
 }
 
+// PIDS OF CHILDREN STILL COMING UP. A service is recorded in the instance only once it is ready;
+// until then only this set knows its pid. A boot interrupted by a signal (an operator's kill, an
+// OOM reaper) tears these down too, so a half-started service never outlives the boot that
+// spawned it (the `volter-livekit-redis-<port>` containers and vendor twins that outlived every
+// World that made them were exactly the children of boots killed mid-way).
+const bootingPids = new Set<number>();
+function trackBootingChild(child: { pid?: number; on: (event: 'exit', listener: () => void) => unknown }): void {
+  const pid = child.pid;
+  if (!pid) return;
+  bootingPids.add(pid);
+  child.on('exit', () => bootingPids.delete(pid));
+}
+
 async function startService(
   config: WorldConfig,
   service: WorldServiceConfig,
@@ -561,8 +748,10 @@ async function startService(
   if (service.rootArg !== false) args.push(service.rootArg ?? '--root', serviceDataDir);
 
   const log = join(paths.logs, `${service.id}.log`);
-  const out = openSync(log, 'a');
+  const out = openPrivateLog(log, 'a');
   const env = serviceProcessEnv(config, service, worldEnv, port);
+  env.VOLTER_WORLD_SERVICE_ID = service.id;
+  env.VOLTER_WORLD_SERVICE_LOG = log;
   const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
 
   // Augment NODE_OPTIONS with declared extra preloads, so a service can add an app-local preload
@@ -580,6 +769,7 @@ async function startService(
     stdio: ['ignore', out, out],
   });
   child.unref();
+  trackBootingChild(child);
 
   // Track an early exit. allocatePort() is TOCTOU (it closes its probe listener before the
   // child binds), so if another/stale process already holds `port`, the child gets EADDRINUSE
@@ -592,7 +782,11 @@ async function startService(
     exitState.value = { code, signal };
   });
 
-  await waitForTcp(port).catch((error) => {
+  // A service that declares a readiness budget gets it for its bind too: under load (a box
+  // swapping, a docker build beside the boot) a heavy service takes longer than the 15s default
+  // to answer on its port, and failing it there wastes the whole boot.
+  const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
+  await waitForTcp(port, bindTimeoutMs).catch((error) => {
     try {
       process.kill(-child.pid!, 'SIGTERM');
     } catch {
@@ -665,7 +859,7 @@ async function startColocatedServices(
   }
 
   const log = join(paths.logs, 'host.log');
-  const out = openSync(log, 'a');
+  const out = openPrivateLog(log, 'a');
   // The host is world infrastructure, not an app process — same egress hygiene as controlPlane
   // services (no injector preload, no ambient proxy): its twins SERVE, they don't call vendors.
   const env: Record<string, string> = { ...process.env as Record<string, string>, ...(config.env ?? {}), ...worldEnv };
@@ -677,6 +871,7 @@ async function startColocatedServices(
     stdio: ['ignore', out, out],
   });
   child.unref();
+  trackBootingChild(child);
 
   const exitState: { value: { code: number | null; signal: NodeJS.Signals | null } | null } = { value: null };
   child.on('exit', (code, signal) => {
@@ -685,7 +880,8 @@ async function startColocatedServices(
 
   const command = [process.execPath, ...args];
   for (const { service, port } of allocated) {
-    await waitForTcp(port).catch((error) => {
+    const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
+    await waitForTcp(port, bindTimeoutMs).catch((error) => {
       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}`);
     });
@@ -724,18 +920,25 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
   const mode = options.mode ?? 'local';
   assertSafeWorldName(name);
   assertMode(mode);
-  const isolation = options.isolation ?? loaded.config.isolation ?? 'process';
+  let isolation = options.isolation ?? loaded.config.isolation ?? 'process';
   // TWIN-67: schema.ts's WorldIsolation contract says process isolation ("one OS process per
   // service") is "the only choice for share/sealed/hosted worlds" — colocating twins in one host
   // process (or worker threads, which still share that process) under `share`/`sealed` puts a
   // semi-untrusted session on colocated twins sharing one host process, exactly what the
   // contract forbids. Enforce it here instead of leaving it a comment nothing checks. Checked
   // before the file-lock claim / any dir creation below, so a rejected combination leaves nothing
-  // to clean up.
+  // to clean up. A CONFIG-sourced isolation is a local-mode preference (init emits
+  // `isolation: 'colocated'` so a local world costs one twin process — R2a), so share/sealed
+  // quietly boot it per-process, their contractual shape; only an EXPLICIT --isolation flag
+  // contradicting the mode is an error, because the caller asked for two things at once.
   if (mode !== 'local' && isolation !== 'process') {
-    throw new Error(
-      `world "${name}": mode "${mode}" requires isolation "process" (schema.ts: process isolation is the only choice for share/sealed/hosted worlds), got isolation "${isolation}". Use --isolation process (or omit --isolation) with --mode ${mode}.`,
-    );
+    if (options.isolation === undefined) {
+      isolation = 'process';
+    } else {
+      throw new Error(
+        `world "${name}": mode "${mode}" requires isolation "process" (schema.ts: process isolation is the only choice for share/sealed/hosted worlds), got --isolation "${isolation}". Use --isolation process (or omit --isolation) with --mode ${mode}.`,
+      );
+    }
   }
 
   const instance = instanceDir(root, name);
@@ -744,6 +947,9 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
   const pidsFile = join(instance, 'pids');
   const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
   const instanceFile = join(instance, 'instance.json');
+  const requestedResources = requestedWorldResources(loaded.config.resources);
+  let resourcesClaimed = false;
+  let resourceHolderPid = 0;
 
   // Claim the instance dir under the kernel's cross-process file lock (TWIN-36). Without it,
   // two concurrent `upWorld` calls on one name can both observe "no live pids", both rmSync the
@@ -757,22 +963,36 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
   // the lockfile adds the cross-process exclusion, and an in-process lock holder always releases
   // before its first await, so withFileLock's synchronous contender wait can never deadlock the
   // event loop against a holder in the same process.
-  withFileLock(instanceLockFile(root, name), () => {
-    const live = livePids(readPids(pidsFile));
-    if (live.length > 0) {
-      throw new Error(`World "${name}" is already running (${live.join(', ')}). Run: volter-world down ${name}`);
-    }
-    const booting = liveBootingClaim(bootingFile(root, name));
-    if (booting) {
-      throw new Error(
-        `World "${name}" is being booted by another process (pid ${booting.pid}, since ${booting.at}). Retry after it finishes (a dead booter's claim is reclaimed automatically).`,
-      );
-    }
-    rmSync(instance, { recursive: true, force: true });
-    mkdirSync(logs, { recursive: true });
-    mkdirSync(data, { recursive: true });
-    writeFileSync(bootingFile(root, name), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() } satisfies BootingClaim)}\n`);
-  });
+  try {
+    withFileLock(instanceLockFile(root, name), () => {
+      const live = livePids(readPids(pidsFile));
+      if (live.length > 0) {
+        throw new Error(`World "${name}" is already running (${live.join(', ')}). Run: volter-world down ${name}`);
+      }
+      const booting = liveBootingClaim(bootingFile(root, name));
+      if (booting) {
+        throw new Error(
+          `World "${name}" is being booted by another process (pid ${booting.pid}, since ${booting.at}). Retry after it finishes (a dead booter's claim is reclaimed automatically).`,
+        );
+      }
+      // Capacity is claimed while the instance-name lock is still held, after proving this is not
+      // an already-running World and before creating the instance or starting its first service.
+      // The resource module has its own cross-World lock, so two different names cannot both pass
+      // the same last slice of capacity.
+      claimWorldResources(root, name, requestedResources);
+      resourcesClaimed = true;
+      rmSync(instance, { recursive: true, force: true });
+      mkdirSync(logs, { mode: 0o700, recursive: true });
+      mkdirSync(data, { mode: 0o700, recursive: true });
+      chmodSync(instance, 0o700);
+      chmodSync(logs, 0o700);
+      chmodSync(data, 0o700);
+      writeFileSync(bootingFile(root, name), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() } satisfies BootingClaim)}\n`, { mode: 0o600 });
+    });
+  } catch (error) {
+    if (resourcesClaimed) releaseWorldResources(root, name);
+    throw error;
+  }
 
   // From here on this call owns the claim; the finally below releases it however the boot
   // settles. On success the recorded live pids (written before returning) take over as the
@@ -787,6 +1007,12 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
       VOLTER_WORLD_MODE: mode,
       VOLTER_WORLD_CONFIG: loaded.path,
       VOLTER_WORLD_INSTANCE: instanceFile,
+      VOLTER_WORLD_DATA: data,
+      // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
+      // absent until `volter-world clock <name> set/advance` writes it (→ real time).
+      TWIN_WORLD_CLOCK_FILE: clockFile(root, name),
+      VOLTER_WORLD_RESOURCE_MEMORY_MIB: String(requestedResources.memoryMiB),
+      VOLTER_WORLD_RESOURCE_WRITABLE_STORAGE_MIB: String(requestedResources.writableStorageMiB),
       // VOLTER_WORLD_SEALED is intent-only; VOLTER_TWIN_STRICT_EGRESS is what the ENFORCEMENT
       // points actually gate on (redirect-proxy.ts's CONNECT/plain-proxy handlers and
       // control-plane/inject.cjs's patched http/https/fetch) — both block any untwinned
@@ -799,15 +1025,28 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
     env.no_proxy = process.env.no_proxy ? `127.0.0.1,localhost,${process.env.no_proxy}` : '127.0.0.1,localhost';
     writeProxyEnv(root, name, env);
 
+    // A signal during the boot is the boot's failure, handled by the catch below like any other:
+    // the services that came up are stopped, the child still coming up with them.
+    let interruptBoot: ((error: Error) => void) | undefined;
+    const bootInterrupted = new Promise<never>((_, reject) => { interruptBoot = reject; });
+    bootInterrupted.catch(() => {});
+    const onBootSignal = (signal: NodeJS.Signals) => interruptBoot?.(new Error(`World "${name}": boot interrupted by ${signal}`));
+    process.once('SIGTERM', onBootSignal);
+    process.once('SIGINT', onBootSignal);
+    const detachBootSignals = () => { process.off('SIGTERM', onBootSignal); process.off('SIGINT', onBootSignal); };
+    // The pids file is written as each service comes up, not once at the end: a boot that dies
+    // or hangs leaves `down` (and the next `up`'s "already running" guard) an honest record.
+    const recordPidsSoFar = () => writeTextAtomic(pidsFile, `${[...new Set(Object.values(services).map((service) => service.pid).filter((pid) => Number.isInteger(pid) && pid > 0))].join('\n')}\n`);
     try {
       // Non-'process' isolation: boot every colocate-declaring service inside ONE host child
       // first; anything without `colocate` (and externals) still goes through the spawn path.
       if (isolation !== 'process') {
         const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
-        for (const started of await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data })) {
+        for (const started of await Promise.race([startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data }), bootInterrupted])) {
           services[started.id] = started;
           Object.assign(env, started.env);
         }
+        recordPidsSoFar();
         writeProxyEnv(root, name, env);
       }
       let proxyForServices: ReturnType<typeof ensureWorldProxyFromEnv> | null = null;
@@ -839,19 +1078,22 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
       for (const service of loaded.config.services) {
         if (services[service.id]) continue; // already up co-located
         attemptProxy();
-        const started = await startService(loaded.config, service, env, { root, instance, logs, data });
+        const started = await Promise.race([startService(loaded.config, service, env, { root, instance, logs, data }), bootInterrupted]);
         services[started.id] = started;
+        recordPidsSoFar();
         Object.assign(env, started.env);
         writeProxyEnv(root, name, env);
       }
+      detachBootSignals();
       // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
       // only lands in `env` once IT has started, so a check that only runs "before starting the
       // next service" never fires when there is no next service (TWIN-64) — the single-twin sealed
       // config test below exercises exactly this.
       attemptProxy();
     } catch (error) {
+      detachBootSignals();
       stopWorldProxy(root, name);
-      const pids = [...new Set(Object.values(services).map((service) => service.pid).filter(Boolean))];
+      const pids = [...new Set([...Object.values(services).map((service) => service.pid).filter(Boolean), ...bootingPids])];
       signalPids(pids, 'SIGTERM');
       // Stop any self-managed externals that DID come up, so a failed `up` never leaves a
       // half-running external stack behind. Best-effort: the original error is what we throw —
@@ -885,6 +1127,14 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
       throw error;
     }
 
+    // Inert-injectEnv check (LibreChat blind-adoption finding): an injectEnv like AWS_TWIN_URL
+    // lands in the world env, LOOKS wired, and does nothing — the injector reads no such vendor.
+    // Warn loudly at `up`, when the operator is watching, instead of letting the disagreement
+    // surface later as silently-real vendor traffic.
+    for (const warning of inertInjectEnvWarnings(loaded.config.services)) {
+      process.stderr.write(`${warning}\n`);
+    }
+
     const worldInstance: WorldInstance = {
       name,
       config: loaded.config.id,
@@ -899,12 +1149,25 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
       pidsFile,
       ...(loaded.config.actors ? { actors: loaded.config.actors } : {}),
       ...(loaded.config.fixtures ? { fixtures: loaded.config.fixtures } : {}),
+      resources: { ...requestedResources, log: join(worldBaseDir(root), '.resources', `${name}.log`), holderPid: 0 },
     };
 
     mkdirSync(dirname(envFile), { recursive: true });
     writeFileSync(envFile, envFileContents(env));
+    const resourceOut = openPrivateLog(worldInstance.resources!.log, 'a');
+    const resourceHolder = spawn(process.execPath, [join(import.meta.dir, 'resource-holder.ts')], {
+      cwd: root,
+      env: process.env,
+      detached: true,
+      stdio: ['ignore', resourceOut, resourceOut],
+    });
+    resourceHolder.unref();
+    worldInstance.resources!.holderPid = resourceHolder.pid ?? 0;
+    resourceHolderPid = worldInstance.resources!.holderPid;
     writePidsFromInstance(worldInstance);
     saveWorldInstance(worldInstance);
+    const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
+    handoffWorldResourceClaim(root, name, [...servicePids, worldInstance.resources!.holderPid]);
     if (mode === 'share') {
       try {
         return await shareWorldServices(name, { root, ...(options.share ?? {}) });
@@ -914,6 +1177,13 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}): P
       }
     }
     return worldInstance;
+  } catch (error) {
+    if (resourcesClaimed) {
+      if (resourceHolderPid > 0) signalPids([resourceHolderPid], 'SIGTERM');
+      recordWorldResourceEvent(root, name, `boot failed: ${error instanceof Error ? error.message : String(error)}`);
+      releaseWorldResources(root, name);
+    }
+    throw error;
   } finally {
     rmSync(bootingFile(root, name), { force: true });
   }
@@ -1070,7 +1340,14 @@ export async function downWorld(
   // Tear down the ambient-redirect proxy + its session CA FIRST, so the trusted CA never outlives
   // the world (it was only ever trusted via per-shell env, never system-wide).
   stopWorldProxy(resolvedRoot, name);
-  const pids = readPids(pidsFile);
+  let instance: WorldInstance | undefined;
+  try {
+    instance = readWorldInstance(name, resolvedRoot);
+  } catch {
+    instance = undefined;
+  }
+  const foregroundPid = instance?.lastRun?.state !== 'completed' ? instance?.lastRun?.consumerPid : undefined;
+  const pids = [...new Set([...readPids(pidsFile), ...(foregroundPid ? [foregroundPid] : [])])];
   const stopped = signalPids(pids, 'SIGTERM');
 
   // Stop self-managed externals via their declared `down` command. Tolerate a missing
@@ -1078,7 +1355,7 @@ export async function downWorld(
   let externalStopped: string[] = [];
   let externalErrors: string[] = [];
   try {
-    const instance = readWorldInstance(name, resolvedRoot);
+    if (!instance) throw new Error('World instance unavailable');
     const result = teardownExternalServices(instance);
     externalStopped = result.stopped;
     externalErrors = result.errors;
@@ -1092,6 +1369,7 @@ export async function downWorld(
   const escalated = await killSurvivorsAfterGrace(pids, options.graceMs ?? DOWN_GRACE_MS_DEFAULT);
 
   rmSync(pidsFile, { force: true });
+  if (externalErrors.length === 0 && undeadPids(pids).length === 0) releaseWorldResources(resolvedRoot, name);
 
   // Purge LAST, only after every process (including SIGKILL escalations) is confirmed dead —
   // removing the instance dir out from under a still-running service would orphan it with no
@@ -1116,13 +1394,56 @@ export function statusWorld(name: string, root = process.cwd()): WorldInstance &
   return { ...worldInstance, running: live.length > 0, livePids: live };
 }
 
+function worldServiceControlRoot(name: string, service: string, root = process.cwd()): string {
+  const instance = readWorldInstance(name, resolve(root));
+  if (!instance.services[service]) throw new Error(`World ${name} has no service "${service}"`);
+  return join(instance.dirs.data, service);
+}
+
+function worldServiceStateService(controlRoot: string, requestedService: string): string {
+  const stateRoot = join(controlRoot, stateDirName(), 'world');
+  if (!existsSync(stateRoot)) return requestedService;
+  const actionServices = readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(stateRoot, entry.name, 'actions.jsonl')))
+    .map((entry) => entry.name);
+  if (actionServices.includes(requestedService)) return requestedService;
+  if (actionServices.length === 1) return actionServices[0]!;
+  if (actionServices.length > 1) {
+    throw new Error(`World service "${requestedService}" records actions under multiple state services (${actionServices.join(', ')}); use volter-twin plan with the explicit service data root`);
+  }
+  return requestedService;
+}
+
+/** Instance-aware plan surface: callers name the world/service, never internal data directories. */
+export function planWorldActions(name: string, service: string, root = process.cwd()): LocalActionPlan {
+  const controlRoot = worldServiceControlRoot(name, service, root);
+  return buildLocalActionPlan(worldServiceStateService(controlRoot, service), controlRoot);
+}
+
+/** Durably review the exact pending transaction set owned by one world service. */
+export function reviewWorldActions(name: string, service: string, opts: {
+  expectedTransactionSetId: string;
+  decision: PlanReviewDecision;
+  actor: { kind: 'agent' | 'human'; id: string };
+  reason?: string;
+  occurredAt?: string;
+  root?: string;
+}): PlanReviewRecord {
+  const controlRoot = worldServiceControlRoot(name, service, opts.root);
+  const stateService = worldServiceStateService(controlRoot, service);
+  return recordPlanReview({ service: stateService, expectedTransactionSetId: opts.expectedTransactionSetId, decision: opts.decision, actor: opts.actor, ...(opts.reason ? { reason: opts.reason } : {}), ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}), root: controlRoot });
+}
+
 function shareCommand(options: ShareWorldOptions, serviceUrl: string): { provider: 'cloudflare-quick' | 'command'; command: string; args: string[] } {
+  if (options.provider === 'cloudflare-quick' && options.command) {
+    throw new Error('share provider "cloudflare-quick" uses the built-in cloudflared command and cannot be combined with a custom command');
+  }
   if (!options.command && options.provider === 'command') {
     throw new Error(`share provider "command" requires a tunnel command (share.command / --command)`);
   }
   if (options.command) {
     return {
-      provider: options.provider ?? 'command',
+      provider: 'command',
       command: options.command,
       args: (options.args ?? []).map((arg) => arg.replaceAll('{url}', serviceUrl)),
     };
@@ -1134,8 +1455,51 @@ function shareCommand(options: ShareWorldOptions, serviceUrl: string): { provide
   };
 }
 
+export function parseCloudflareQuickPublicUrl(candidate: string): string | undefined {
+  // Validate the provider's RAW stdout token before WHATWG normalization. Otherwise `%2e` in the
+  // authority, an explicit default `:443`, or `/.` / `/%2e%2e` paths normalize into an apparently
+  // valid origin and bypass the strict cloudflared-output boundary.
+  if (!/^https:\/\/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.trycloudflare\.com\/?$/.test(candidate)) return undefined;
+  let parsed: URL;
+  try { parsed = new URL(candidate); } catch { return undefined; }
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.port
+    || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.trycloudflare\.com$/.test(parsed.hostname)
+    || parsed.pathname !== '/' || parsed.search || parsed.hash) return undefined;
+  return parsed.origin;
+}
+
+function canonicalDottedIpv4(host: string): boolean {
+  const parts = host.split('.');
+  return parts.length === 4 && parts.every((part) => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255);
+}
+
+function parseCustomShareOrigin(handshake: string): string {
+  const raw = /^https?:\/\/(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?\/?$/i.exec(handshake);
+  if (!raw) {
+    throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
+  }
+  const rawHost = raw[1]!;
+  const rawPort = raw[2];
+  let parsed: URL;
+  try { parsed = new URL(handshake); }
+  catch { throw new Error(`Custom tunnel emitted an invalid VOLTER_SHARE_URL handshake: ${handshake}`); }
+  const normalizedHostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!rawHost.startsWith('[') && isIP(normalizedHostname) === 4
+    && (!canonicalDottedIpv4(rawHost) || rawHost !== normalizedHostname)) {
+    throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
+  }
+  if (rawPort && rawPort.length > 1 && rawPort.startsWith('0')) {
+    throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical decimal port syntax: ${handshake}`);
+  }
+  if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.username || parsed.password
+    || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+    throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a credential-free http(s) origin: ${handshake}`);
+  }
+  return parsed.origin;
+}
+
 async function waitForPublicUrl(child: ReturnType<typeof spawn>, logPath: string, timeoutMs: number, requireTryCloudflare: boolean): Promise<string> {
-  const urlPattern = /https:\/\/[a-zA-Z0-9.-]+/g;
+  const urlPattern = /https?:\/\/[^\s"'<>]+/gi;
   let exited = false;
   let exitSummary = '';
   child.once('exit', (code, signal) => {
@@ -1150,15 +1514,21 @@ async function waitForPublicUrl(child: ReturnType<typeof spawn>, logPath: string
   const started = Date.now();
   while (Date.now() - started < timeoutMs) {
     const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
-    const matches = text.match(urlPattern);
-    const url = requireTryCloudflare
-        ? matches?.find((candidate) => candidate.includes('trycloudflare.com'))
-        : matches?.find((candidate) => candidate.includes('trycloudflare.com')) ?? matches?.[0];
-    if (url) return url;
+    if (requireTryCloudflare) {
+      for (const candidate of text.match(urlPattern) ?? []) {
+        const parsed = parseCloudflareQuickPublicUrl(candidate);
+        if (parsed) return parsed;
+      }
+    } else {
+      const handshake = /^VOLTER_SHARE_URL=(\S+)\s*$/m.exec(text)?.[1];
+      if (handshake) return parseCustomShareOrigin(handshake);
+    }
     if (exited) throw new Error(`Tunnel process exited before printing a public URL (${exitSummary}). Log: ${logPath}`);
     await new Promise((resolveWait) => setTimeout(resolveWait, 250));
   }
-  throw new Error(`Tunnel did not print a public https URL within ${timeoutMs}ms. Log: ${logPath}`);
+  throw new Error(requireTryCloudflare
+    ? `Cloudflare tunnel did not print a trycloudflare.com https URL within ${timeoutMs}ms. Log: ${logPath}`
+    : `Custom tunnel did not print VOLTER_SHARE_URL=<http(s)-url> within ${timeoutMs}ms. Log: ${logPath}`);
 }
 
 function sleep(ms: number): Promise<void> {
@@ -1205,9 +1575,23 @@ async function verifyPublicUrl(
   path: string,
   timeoutMs: number,
 ): Promise<NonNullable<WorldServiceInstance['publicVerification']>> {
-  if (!commandExists('dig')) throw new Error('Public URL verification requires dig');
   if (!commandExists('curl')) throw new Error('Public URL verification requires curl');
   const hostname = new URL(publicUrl).hostname;
+  const normalizedHostname = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  const local = normalizedHostname === 'localhost' || normalizedHostname === '::1'
+    || (isIP(normalizedHostname) === 4 && normalizedHostname.split('.')[0] === '127');
+  if (local) {
+    const target = publicHealthUrl(publicUrl, path);
+    const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { encoding: 'utf8' });
+    const separator = result.stdout.lastIndexOf('\n');
+    const body = separator >= 0 ? result.stdout.slice(0, separator).trim() : result.stdout.trim();
+    const status = Number(separator >= 0 ? result.stdout.slice(separator + 1).trim() : '0');
+    if (result.status !== 0 || status < 200 || status >= 400) {
+      throw new Error(`Local shared URL did not pass health verification at ${target}: ${result.stderr.trim() || `HTTP ${status}`}`);
+    }
+    return { path, checkedAt: new Date().toISOString(), hostname, resolvedIp: normalizedHostname === 'localhost' ? '127.0.0.1' : normalizedHostname, status, body: body.slice(0, 500) };
+  }
+  if (!commandExists('dig')) throw new Error('Public URL verification requires dig');
   const started = Date.now();
   const resolvedIp = await waitForPublicDns(hostname, Math.min(timeoutMs, 60_000));
   if (!resolvedIp) {
@@ -1259,6 +1643,24 @@ async function verifyPublicUrl(
 }
 
 export async function shareWorld(name: string, options: ShareWorldOptions = {}): Promise<WorldInstance> {
+  const root = resolve(options.root ?? process.cwd());
+  const serviceId = options.service ?? 'app';
+  assertSafeWorldName(name);
+  const claim = await reserveSharingClaim(root, name, serviceId);
+  const heartbeat = setInterval(() => {
+    try { refreshSharingClaim(root, name, claim.token); }
+    catch { /* retry next tick; same-host process identity still protects the live owner */ }
+  }, SHARE_CLAIM_HEARTBEAT_MS);
+  heartbeat.unref();
+  try {
+    return await shareWorldReserved(name, { ...options, root, service: serviceId });
+  } finally {
+    clearInterval(heartbeat);
+    releaseSharingClaim(root, name, claim.token);
+  }
+}
+
+async function shareWorldReserved(name: string, options: ShareWorldOptions): Promise<WorldInstance> {
   const root = resolve(options.root ?? process.cwd());
   const serviceId = options.service ?? 'app';
   const instance = readWorldInstance(name, root);
@@ -1273,7 +1675,9 @@ export async function shareWorld(name: string, options: ShareWorldOptions = {}):
 
   const tunnel = shareCommand(options, service.url);
   const log = join(instance.dirs.logs, `${serviceId}.tunnel.log`);
-  const out = openSync(log, 'a');
+  // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
+  // share from accepting the previous process's URL handshake as the new process's endpoint.
+  const out = openPrivateLog(log, 'w');
   const child = spawn(tunnel.command, tunnel.args, {
     cwd: root,
     env: process.env,
@@ -1284,11 +1688,34 @@ export async function shareWorld(name: string, options: ShareWorldOptions = {}):
 
   let publicUrl: string;
   let publicVerification: WorldServiceInstance['publicVerification'];
+  let pidsWritten = false;
   try {
     publicUrl = await waitForPublicUrl(child, log, options.timeoutMs ?? 20_000, tunnel.provider === 'cloudflare-quick');
     if (options.verifyPath !== false) {
       publicVerification = await verifyPublicUrl(publicUrl, options.verifyPath ?? '/health', options.timeoutMs ?? 90_000);
     }
+
+    // Build the prospective instance off to the side. Until BOTH persistence files are written,
+    // callers and the previously loaded instance retain the exact unshared object.
+    const nextInstance = structuredClone(instance);
+    const nextService = nextInstance.services[serviceId]!;
+    nextService.publicUrl = publicUrl;
+    nextService.publicUrlEphemeral = tunnel.provider === 'cloudflare-quick' || options.ephemeral === true;
+    nextService.publicReady = options.verifyPath !== false;
+    if (publicVerification) nextService.publicVerification = publicVerification;
+    else delete nextService.publicVerification;
+    nextService.tunnel = {
+      provider: tunnel.provider,
+      pid: child.pid ?? 0,
+      log,
+      command: [tunnel.command, ...tunnel.args],
+      startedAt: new Date().toISOString(),
+    };
+    writePidsFromInstance(nextInstance);
+    pidsWritten = true;
+    saveWorldInstance(nextInstance);
+    child.unref();
+    return nextInstance;
   } catch (error) {
     // TWIN-62: never-half-shared means the tunnel must actually be confirmed dead before we
     // rethrow, not just best-effort SIGTERM'd — the same SIGTERM→grace→SIGKILL contract `downWorld`
@@ -1298,25 +1725,20 @@ export async function shareWorld(name: string, options: ShareWorldOptions = {}):
       signalPids([child.pid], 'SIGTERM');
       await killSurvivorsAfterGrace([child.pid], DOWN_GRACE_MS_DEFAULT);
     }
+    const cleanupProblems: string[] = [];
+    if (child.pid && undeadPids([child.pid]).length > 0) cleanupProblems.push(`tunnel pid ${child.pid} survived cleanup`);
+    // If the pids write landed but instance.json did not, restore the previous pids projection only
+    // after the child is confirmed dead. Atomic writes ensure a failed write itself leaves the old
+    // file intact; this compensates the one successful write in a two-file persistence attempt.
+    if (pidsWritten) {
+      try { writePidsFromInstance(instance); }
+      catch (restoreError) { cleanupProblems.push(`could not restore pids file: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`); }
+    }
+    if (cleanupProblems.length > 0) {
+      throw new Error(`${error instanceof Error ? error.message : String(error)}; share cleanup incomplete: ${cleanupProblems.join('; ')}`, { cause: error });
+    }
     throw error;
   }
-  child.unref();
-
-  service.publicUrl = publicUrl;
-  service.publicUrlEphemeral = tunnel.provider === 'cloudflare-quick';
-  service.publicReady = options.verifyPath !== false;
-  if (publicVerification) service.publicVerification = publicVerification;
-  else delete service.publicVerification;
-  service.tunnel = {
-    provider: tunnel.provider,
-    pid: child.pid ?? 0,
-    log,
-    command: [tunnel.command, ...tunnel.args],
-    startedAt: new Date().toISOString(),
-  };
-  writePidsFromInstance(instance);
-  saveWorldInstance(instance);
-  return instance;
 }
 
 function configuredShareTargets(
@@ -1341,12 +1763,22 @@ export async function shareWorldServices(name: string, options: ShareWorldServic
   const config = loadWorldConfig(instance.configPath, instance.root).config;
   const targets = configuredShareTargets(instance, options.service, options.verifyPath);
   for (const target of targets) {
+    const provider = options.provider ?? (options.command ? 'command' : config.share?.provider);
+    if (provider === 'cloudflare-quick' && options.command) {
+      throw new Error('share provider "cloudflare-quick" uses the built-in cloudflared command and cannot be combined with a custom command');
+    }
+    // An explicit provider override is authoritative. In particular, selecting the real
+    // Cloudflare provider must clear a config-declared local rehearsal command instead of
+    // launching that command while parsing its output as cloudflared.
+    const command = provider === 'cloudflare-quick' ? undefined : options.command ?? config.share?.command;
+    const args = provider === 'cloudflare-quick' ? undefined : options.args ?? config.share?.args;
     instance = await shareWorld(name, {
       ...options,
       root,
-      provider: options.provider ?? config.share?.provider,
-      command: options.command ?? config.share?.command,
-      args: options.args ?? config.share?.args,
+      provider,
+      command,
+      args,
+      ephemeral: options.ephemeral ?? config.share?.ephemeral,
       service: target.id,
       verifyPath: target.verifyPath,
     });
@@ -1458,6 +1890,17 @@ export async function doctorWorld(name: string, options: { root?: string; verify
 
   checks.push({ id: 'env-file', ok: existsSync(instance.envFile), message: instance.envFile });
 
+  if (instance.resources) {
+    const holderAlive = livePids([instance.resources.holderPid]).length === 1;
+    checks.push({
+      id: 'resources',
+      ok: holderAlive && existsSync(instance.resources.log),
+      message: holderAlive
+        ? `reserved memory=${instance.resources.memoryMiB}MiB writable-storage=${instance.resources.writableStorageMiB}MiB; log=${instance.resources.log}`
+        : `resource reservation holder is not running; log=${instance.resources.log}`,
+    });
+  }
+
   const live = livePids(readPids(instance.pidsFile));
   checks.push({
     id: 'pids',
@@ -1591,13 +2034,41 @@ export function urlsWorld(name: string, root = process.cwd()): WorldUrlInfo {
   };
 }
 
-export async function runWorld(configId: string, command: string[], options: RunWorldOptions = {}): Promise<{ instance: WorldInstance; exitCode: number }> {
+/**
+ * The clean (unquoted) base URL(s) of a RUNNING world's services — the `volter-world url`
+ * surface. Resolved from the generated instance, so callers never shell-parse `world.env`
+ * (its values are single-quoted). One `{ id, url }` when `service` is named; every
+ * URL-bearing service otherwise ('external' services have no assigned URL — their endpoints
+ * are discovered env vars, so they are omitted from the list and refused by name).
+ */
+export function urlWorld(name: string, options: { service?: string; root?: string } = {}): Array<{ id: string; url: string }> {
+  const status = statusWorld(name, options.root ?? process.cwd());
+  if (!status.running) {
+    throw new Error(`World ${name} is not running; start it with: volter-world up ${status.config} --env-file <path> --name ${name}`);
+  }
+  if (options.service === undefined) {
+    return Object.values(status.services)
+      .filter((service) => service.url)
+      .map((service) => ({ id: service.id, url: service.url! }));
+  }
+  const service = status.services[options.service];
+  if (!service) {
+    throw new Error(`World ${name} has no service "${options.service}"; it has: ${Object.keys(status.services).join(', ')}`);
+  }
+  if (!service.url) {
+    throw new Error(`Service "${options.service}" has no assigned URL (type '${service.type}' endpoints are discovered env vars) — read them with: volter-world env ${name} -- env`);
+  }
+  return [{ id: service.id, url: service.url }];
+}
+
+export async function runWorld(configId: string, command: string[], options: RunWorldOptions = {}): Promise<{ instance: WorldInstance; exitCode: number; outcome: WorldRunOutcome }> {
   if (command.length === 0) throw new Error('Missing command after --');
   const instance = await upWorld(configId, options);
-  let exitCode = 1;
   try {
-    exitCode = runWithWorldEnv(instance.name, command, instance.root);
-    return { instance, exitCode };
+    const outcome = await runWithWorldEnvLogged(instance.name, command, instance.root);
+    instance.lastRun = outcome;
+    saveWorldInstance(instance);
+    return { instance, exitCode: outcome.exitCode, outcome };
   } finally {
     if (!options.keep) await downWorld(instance.name, instance.root);
   }
@@ -1607,7 +2078,10 @@ export function listWorlds(root = process.cwd()): Array<{ name: string; running:
   const base = worldBaseDir(resolve(root));
   if (!existsSync(base)) return [];
   return readdirSync(base, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+    // World names must start with an alphanumeric (assertSafeWorldName), which is exactly why
+    // the lock dir is dot-prefixed — so anything not world-NAMED is bookkeeping (`.locks`),
+    // never a world, and must not be listed as one.
+    .filter((entry) => entry.isDirectory() && /^[A-Za-z0-9]/.test(entry.name))
     .map((entry) => {
       try {
         const status = statusWorld(entry.name, root);
@@ -1619,8 +2093,7 @@ export function listWorlds(root = process.cwd()): Array<{ name: string; running:
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-export function runWithWorldEnv(name: string, command: string[], root = process.cwd()): number {
-  if (command.length === 0) throw new Error('Missing command after --');
+function worldAttachedCommandEnv(name: string, root: string): { instance: ReturnType<typeof statusWorld>; env: NodeJS.ProcessEnv } {
   const status = statusWorld(name, root);
   const sealed = status.env.VOLTER_WORLD_MODE === 'sealed';
   let proxyEnv: Record<string, string> = {};
@@ -1628,37 +2101,120 @@ export function runWithWorldEnv(name: string, command: string[], root = process.
     const proxy = ensureWorldProxy(name, root);
     if (proxy?.url) {
       proxyEnv = proxy.env;
-    } else if (sealed && proxy === null) {
-      // TWIN-64: ensureWorldProxy() returns bare `null` when openssl is unavailable — silently, by
-      // design, for the non-sealed env-only fallback. A SEALED world running a command without the
-      // ambient proxy is a different story: the Node injector (loaded via NODE_OPTIONS, still in
-      // `status.env`) keeps blocking Node http/https/fetch calls, but unmodified non-Node CLIs
-      // (curl, gh, stripe, …) have no HTTPS_PROXY to redirect them and can bypass the twins
-      // entirely. Never let that be silent — the daemon-timeout case is already loud (see the WARN
-      // `ensureWorldProxy` itself emits), this covers the "no openssl at all" gap.
-      process.stderr.write(
-        `!! WARN: world "${name}" is sealed but openssl is unavailable — NOT proxy-sealed for this command; unmodified CLIs (curl, gh, stripe, …) can bypass the twins here (Node http/https/fetch calls are still blocked via the injector).\n`,
-      );
-    }
+    } else if (sealed) throw new Error(`sealed world "${name}": attachment proxy is unavailable; refusing to run the command`);
   } catch (error) {
-    if (sealed) {
-      // Never swallow a sealed world's proxy failure silently (TWIN-64): the command is about to
-      // run NOT proxy-sealed for unmodified CLIs even though Node calls stay guarded by the
-      // injector.
-      process.stderr.write(
-        `!! WARN: world "${name}" is sealed but the ambient redirect proxy failed to start (${error instanceof Error ? error.message : String(error)}) — NOT proxy-sealed for this command; unmodified CLIs (curl, gh, stripe, …) can bypass the twins here.\n`,
-      );
-    }
+    if (sealed) throw new Error(`sealed world "${name}": attachment proxy failed; refusing to run the command (${error instanceof Error ? error.message : String(error)})`);
     // Keep env-only redirect if the ambient proxy cannot start.
   }
+  return { instance: status, env: { ...process.env, ...status.env, ...proxyEnv } };
+}
+
+export function runWithWorldEnv(name: string, command: string[], root = process.cwd(), options: { cwd?: string } = {}): number {
+  if (command.length === 0) throw new Error('Missing command after --');
+  const attached = worldAttachedCommandEnv(name, root);
   const result = spawnSync(command[0]!, command.slice(1), {
-    cwd: resolve(root),
-    env: { ...process.env, ...status.env, ...proxyEnv },
+    cwd: resolve(options.cwd ?? root),
+    env: attached.env,
     stdio: 'inherit',
   });
   return result.status ?? 1;
 }
 
+function signalExitCode(signal: NodeJS.Signals | null): number {
+  if (signal === null) return 1;
+  return 128 + (osConstants.signals[signal] ?? 0);
+}
+
+/** `world run`'s foreground consumer: stream output to the terminal while retaining one current
+ * World-visible log, then return a structured outcome even when spawning fails or a signal kills
+ * the consumer. The record intentionally contains neither argv nor environment values. */
+async function runWithWorldEnvLogged(name: string, command: string[], root: string, options: { cwd?: string } = {}): Promise<WorldRunOutcome> {
+  const startedAt = new Date().toISOString();
+  const instance = statusWorld(name, root);
+  const log = join(instance.dirs.logs, 'foreground.log');
+  const running: WorldRunRecord = { state: 'running', runnerPid: process.pid, startedAt, log };
+  writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(running, null, 2)}\n`);
+  const logFd = openPrivateLog(log, 'w');
+  writeSync(logFd, `World ${name}: foreground consumer started at ${startedAt}\n`);
+
+  const finish = (exitCode: number, signal?: NodeJS.Signals, error?: string): WorldRunOutcome => {
+    const finishedAt = new Date().toISOString();
+    const detail = error ? `spawn error: ${error}` : signal ? `terminated by ${signal}` : `exited ${exitCode}`;
+    writeSync(logFd, `\nWorld ${name}: foreground consumer ${detail} at ${finishedAt}\n`);
+    closeSync(logFd);
+    const outcome: WorldRunOutcome = {
+      state: 'completed',
+      runnerPid: process.pid,
+      startedAt,
+      finishedAt,
+      exitCode,
+      log,
+      ...(signal ? { signal } : {}),
+      ...(error ? { error } : {}),
+    };
+    writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(outcome, null, 2)}\n`);
+    return outcome;
+  };
+
+  let attached: ReturnType<typeof worldAttachedCommandEnv>;
+  try {
+    attached = worldAttachedCommandEnv(name, root);
+  } catch (cause) {
+    return finish(1, undefined, cause instanceof Error ? cause.message : String(cause));
+  }
+
+  return await new Promise<WorldRunOutcome>((resolveOutcome) => {
+    let spawnError: string | undefined;
+    let child;
+    try {
+      child = spawn(command[0]!, command.slice(1), {
+        cwd: resolve(options.cwd ?? root),
+        env: attached.env,
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+    } catch (cause) {
+      resolveOutcome(finish(1, undefined, cause instanceof Error ? cause.message : String(cause)));
+      return;
+    }
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      process.stdout.write(chunk);
+      writeSync(logFd, chunk);
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      process.stderr.write(chunk);
+      writeSync(logFd, chunk);
+    });
+    child.once('error', (cause) => {
+      spawnError = cause.message;
+    });
+    const activeRecord: WorldRunRecord = {
+      state: 'running',
+      runnerPid: process.pid,
+      ...(child.pid ? { consumerPid: child.pid } : {}),
+      startedAt,
+      log,
+    };
+    writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(activeRecord, null, 2)}\n`);
+    let forwardedSignal: NodeJS.Signals | undefined;
+    const forwardSignal = (signal: NodeJS.Signals): void => {
+      forwardedSignal = signal;
+      child.kill(signal);
+    };
+    const onSigint = (): void => forwardSignal('SIGINT');
+    const onSigterm = (): void => forwardSignal('SIGTERM');
+    process.once('SIGINT', onSigint);
+    process.once('SIGTERM', onSigterm);
+    child.once('close', (code, signal) => {
+      process.removeListener('SIGINT', onSigint);
+      process.removeListener('SIGTERM', onSigterm);
+      const effectiveSignal = signal ?? forwardedSignal;
+      const exitCode = effectiveSignal ? signalExitCode(effectiveSignal) : (code ?? 1);
+      resolveOutcome(finish(exitCode, effectiveSignal, spawnError));
+    });
+  });
+}
+
 /** The shell + env + cwd a `volter-world shell` subshell launches with (extracted for testability):
  * the world env (twin `*_URL`s + fake keys + the Node injector + cliRedirect endpoint vars) on top
  * of the caller's env, plus `VOLTER_WORLD` so a prompt can show which world is active. The ambient
@@ -1684,15 +2240,18 @@ export async function shellWorld(name: string, root = process.cwd()): Promise<nu
   const { shell, cwd, env } = worldShellEnv(name, root);
   const resolvedRoot = resolve(root);
   let proxy: Awaited<ReturnType<typeof startRedirectProxy>> | null = null;
+  const sealed = env.VOLTER_WORLD_MODE === 'sealed';
   if (opensslAvailable()) {
     try {
       proxy = await startRedirectProxy({ env, tlsDir: tlsDir(resolvedRoot, name) });
       Object.assign(env, proxy.proxyEnv());
       process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (ambient proxy ${proxy.url}). type 'exit' to leave.\n`);
     } catch (error) {
+      if (sealed) throw new Error(`sealed world "${name}": attachment proxy failed; refusing to open a shell (${error instanceof Error ? error.message : String(error)})`);
       process.stderr.write(`world '${name}': ambient TLS proxy unavailable (${error instanceof Error ? error.message : String(error)}); falling back to env-only redirect.\n`);
     }
   } else {
+    if (sealed) throw new Error(`sealed world "${name}": openssl is unavailable; refusing to open a shell`);
     process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (env-only; install openssl for ambient https redirect). type 'exit' to leave.\n`);
   }
   try {
@@ -1859,13 +2418,15 @@ export function activateScript(name: string, root = process.cwd()): string {
   // routes https through the twins too — not just the Node injector / cliRedirect endpoint vars.
   let proxyNote = '';
   let env: Record<string, string> = { ...baseEnv };
+  const sealed = baseEnv.VOLTER_WORLD_MODE === 'sealed';
   try {
     const proxy = ensureWorldProxy(name, root);
     if (proxy && proxy.url) {
       env = { ...baseEnv, ...proxy.env };
       proxyNote = ` (ambient proxy ${proxy.url})`;
-    }
-  } catch {
+    } else if (sealed) throw new Error('attachment proxy is unavailable');
+  } catch (error) {
+    if (sealed) throw new Error(`sealed world "${name}": attachment proxy failed; refusing activation (${error instanceof Error ? error.message : String(error)})`);
     // openssl missing or daemon failed — keep env-only redirect; never fabricate proxy success.
   }
   const keys = Object.keys(env).sort();