@volter/world-runtime 2.0.21 → 2.0.23

package/dist/src/branch.d.ts

@@ -2,6 +2,7 @@ import type { WorldInstance } from './schema.js';
 export type BranchOptions = {
     root?: string;
     envFile?: string;
+    forceEnvOutput?: boolean;
     now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */
     at?: {
         instant?: string;

package/dist/src/branch.js

@@ -58,7 +58,7 @@ export async function branchWorld(base, name, options = {}) {
     const began = Date.now();
     let instance;
     try {
-        instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
+        instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile, forceEnvOutput: options.forceEnvOutput });
     }
     catch (error) {
         // only a record made during this call is ours to remove, and it is removed by its own createdAt, as the fork's

package/dist/src/changeset.js

@@ -43,7 +43,7 @@ function requireWorld(name, root) {
         if (!/World instance not found/.test(String(error.message)))
             throw error;
         const known = listWorlds(root).map((world) => world.name);
-        throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-file <path> --name ${name}\``);
+        throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-out <path> --name ${name}\``);
     }
 }
 /** Every state service a world service currently records actions under (often exactly one). */

package/dist/src/cli.js

@@ -70,7 +70,7 @@ function printHelp() {
                                                   # 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-file=<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] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — the catalog's upkeep verdicts for the mounted twins: matrix debt, census (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
@@ -120,7 +120,7 @@ function printHelp() {
                                                   # window open, so the defaults land as observed state (diff empty, nothing pending)
   volter-world reset <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
                                                   # back to the defaults: down --purge, up, seed (refuses a referenced parent)
-  volter-world branch <world> <name> [--env-file=<path>] [--json] [--root <repo>]
+  volter-world branch <world> <name> [--env-out=<path>] [--json] [--root <repo>]
                                                   # a new world over the base's mirrors (its own log; the base's unpushed changes stay)
   volter-world checkout <name> [--json] [--root <repo>]   # a stopped world back up, state intact
   volter-world fetch <world> [--origin <twins url> --namespace <org>/<world>] --key <key> [--full] [--service <id>]... [--json] [--root <repo>]
@@ -168,7 +168,7 @@ function printHelp() {
                                                   # attachers: volter-world attach <http://host:manifest-port> -- <command...>
   volter-world activate <name> [--root <repo>]   # eval "$(volter-world activate <name>)" — a virtualenv for vendor APIs
   volter-world shell <name> [--root <repo>]      # drop into a subshell with the world active (any CLI hits the twins)
-  volter-world run <config> --env-file=<path> [--name <name>] [--mode local|share|sealed] [--keep] [--verbose] -- <command...>
+  volter-world run <config> --env-out=<path> [--name <name>] [--mode local|share|sealed] [--keep] [--verbose] -- <command...>
   volter-world share <name> [--service app] [--verify /health|--no-verify] [--provider cloudflare-quick|command] [--command <cmd> [-- <args…>]]
                                                   # {url} in command args = the service's local URL;
                                                   # --provider cloudflare-quick selects raw cloudflared and clears a configured custom command
@@ -316,11 +316,13 @@ async function main() {
         return;
     }
     if (cmd === 'up') {
+        if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file=')))
+            throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
         if (!subject)
             throw new Error('volter-world up: missing config');
-        const envFile = optionValue(rest, '--env-file');
+        const envFile = optionValue(rest, '--env-out');
         if (!envFile)
-            throw new Error('volter-world up: missing required --env-file=<path>');
+            throw new Error('volter-world up: missing required --env-out=<path>');
         const name = optionValue(rest, '--name') || undefined;
         const mode = optionValue(rest, '--mode', 'local');
         const isolationArg = optionValue(rest, '--isolation');
@@ -332,7 +334,7 @@ async function main() {
         // --keep-state: boot over the state the World's directory already holds (a World carried somewhere else, e.g. a
         // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
         const keepState = rest.includes('--keep-state');
-        const instance = await superviseWorldUp(subject, { name, root, mode, envFile, owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+        const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
         printReady(instance);
         return;
     }
@@ -738,11 +740,13 @@ async function main() {
         return;
     }
     if (cmd === 'branch') {
+        if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file=')))
+            throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
         const [name] = positionalArgs(rest);
         if (!subject || !name)
-            throw new Error('volter-world branch: usage: volter-world branch <world> <name> [--env-file=<path>]');
-        const envFile = optionValue(rest, '--env-file') || undefined;
-        const { instance, forked } = await branchWorld(subject, name, { root, ...(envFile ? { envFile } : {}) });
+            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`);
         else {
@@ -1157,12 +1161,15 @@ async function main() {
         const split = rest.indexOf('--');
         if (split < 0)
             throw new Error('volter-world run: pass command after --');
-        const envFile = optionValue(rest, '--env-file');
+        const worldArgs = rest.slice(0, split);
+        if (worldArgs.some(arg => arg === '--env-file' || arg.startsWith('--env-file=')))
+            throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
+        const envFile = optionValue(worldArgs, '--env-out');
         if (!envFile)
-            throw new Error('volter-world run: missing required --env-file=<path>');
-        const name = optionValue(rest, '--name') || undefined;
-        const mode = optionValue(rest, '--mode', 'local');
-        const result = await runWorld(subject, rest.slice(split + 1), { root, name, mode, envFile, owner: ownerOption(rest.slice(0, split)), keep: rest.slice(0, split).includes('--keep'), verbose: rest.slice(0, split).includes('--verbose') });
+            throw new Error('volter-world run: missing required --env-out=<path>');
+        const name = optionValue(worldArgs, '--name') || undefined;
+        const mode = optionValue(worldArgs, '--mode', 'local');
+        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') });
         if (result.exitCode !== 0) {
             const detail = result.outcome.error ? `could not start (${result.outcome.error})`
                 : result.outcome.signal ? `was terminated by ${result.outcome.signal}`

package/dist/src/env-output.d.ts

@@ -0,0 +1,14 @@
+type PriorOutput = {
+    path: string;
+    contents: string;
+};
+export type EnvOutputClaim = {
+    path: string;
+    contents?: Buffer;
+    force: boolean;
+    backupDir: string;
+};
+/** Refuse a custody/input file before any World service or lifecycle mutation starts. */
+export declare function claimEnvOutput(path: string, backupDir: string, prior?: PriorOutput, force?: boolean): EnvOutputClaim;
+export declare function publishEnvOutput(claim: EnvOutputClaim, contents: string): void;
+export {};

package/dist/src/env-output.js

@@ -0,0 +1,67 @@
+import { constants, closeSync, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+function inspect(path) {
+    try {
+        const info = lstatSync(path);
+        if (!info.isFile() || info.nlink !== 1)
+            throw new Error('World env output must be a regular file with one link; symlinks are refused');
+        return readFileSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Refuse a custody/input file before any World service or lifecycle mutation starts. */
+export function claimEnvOutput(path, backupDir, prior, force = false) {
+    const contents = inspect(path);
+    if (contents !== undefined && !force && !(prior?.path === path && Buffer.from(prior.contents).equals(contents))) {
+        throw new Error(`World refuses existing --env-out file it does not own: ${path}. Choose a new output path; never use a custody file. --force explicitly replaces a file with a private backup.`);
+    }
+    if (force && contents !== undefined) {
+        mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+        const hash = createHash('sha256').update(path).update('\0').update(contents).digest('hex');
+        const backup = join(backupDir, hash);
+        if (existsSync(backup)) {
+            if (!readFileSync(backup).equals(contents))
+                throw new Error('World env backup differs; refusing replacement');
+        }
+        else
+            writeFileSync(backup, contents, { mode: 0o600, flag: 'wx' });
+    }
+    return { path, contents, force, backupDir };
+}
+export function publishEnvOutput(claim, contents) {
+    mkdirSync(dirname(claim.path), { recursive: true });
+    const current = inspect(claim.path);
+    if (current === undefined) {
+        const fd = openSync(claim.path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        try {
+            writeFileSync(fd, contents);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return;
+    }
+    if (claim.contents === undefined || !current.equals(claim.contents))
+        throw new Error('World env output changed during boot; refusing to overwrite it');
+    const fd = openSync(claim.path, constants.O_RDWR | constants.O_NOFOLLOW);
+    try {
+        const opened = fstatSync(fd);
+        const named = lstatSync(claim.path);
+        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== named.dev || opened.ino !== named.ino || !readFileSync(fd).equals(claim.contents)) {
+            throw new Error('World env output identity changed during boot; refusing to overwrite it');
+        }
+        ftruncateSync(fd, 0);
+        const bytes = Buffer.from(contents);
+        let offset = 0;
+        while (offset < bytes.length)
+            offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/src/init.js

@@ -1046,7 +1046,7 @@ export function initWorld(name, repoPath, options = {}) {
             'volter world down',
         ]
         : [
-            `volter-world up ${plan.configPath} --name ${plan.name} --env-file=${resolve(plan.out, 'world.env')}   # up WRITES the live env (twin URLs) there; app.env is init's static preview of the same map`,
+            `volter-world up ${plan.configPath} --name ${plan.name} --env-out=${resolve(plan.out, 'world.env')}   # up WRITES the live env (twin URLs) there; app.env is init's static preview of the same map`,
             ...(plan.seedEntry === null ? [] : [`volter-world seed ${plan.name} --cwd ${plan.repo}   # load the default data AFTER every up: it lands as data that was already there, the log empty; reset = down, up, seed`]),
             `volter-world env ${plan.name} -- <your app's dev command>   # run the app inside the world`,
             `volter-world down ${plan.name}`,

package/dist/src/reflect.js

@@ -358,7 +358,7 @@ export function composeOverrideForReflect(manifest, services, worldName) {
 }
 // docker compose's global options that take a value — the override's -f must land after the consumer's own
 // files and before the subcommand, so these are stepped over to find it.
-const COMPOSE_VALUED_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '--progress', '--parallel', '--ansi']);
+const COMPOSE_VALUED_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-out', '--project-directory', '--progress', '--parallel', '--ansi']);
 /** Split `docker [docker flags] compose [compose flags] <subcommand…>`; undefined when it is not a compose command. */
 export function splitDockerComposeArgs(command) {
     if (command[0] !== 'docker')

package/dist/src/runtime.d.ts

@@ -9,7 +9,9 @@ export type UpWorldOptions = {
     mode?: WorldMode;
     /** Overrides the config's `isolation` for this boot (e.g. force 'process' for a share world). */
     isolation?: WorldIsolation;
+    /** Output path for generated World exports; never an input credentials file. */
     envFile?: string;
+    forceEnvOutput?: boolean;
     share?: Omit<ShareWorldOptions, 'root' | 'service' | 'verifyPath'> & {
         verifyPath?: string | false;
     };

package/dist/src/runtime.js

@@ -1,3 +1,4 @@
+import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
@@ -1400,6 +1401,10 @@ export async function upWorld(configId, options = {}, abort) {
     const pidsFile = join(instance, 'pids');
     const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
     const instanceFile = join(instance, 'instance.json');
+    const priorOutputInstance = existsSync(instanceFile) ? JSON.parse(readFileSync(instanceFile, 'utf8')) : undefined;
+    const priorOutput = priorOutputInstance?.name === name && resolve(priorOutputInstance.root) === root
+        ? { path: resolve(priorOutputInstance.envFile), contents: envFileContents(priorOutputInstance.env) } : undefined;
+    const envOutputClaim = claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'), priorOutput, options.forceEnvOutput);
     if (loaded.config.resources)
         process.stderr.write(`World "${name}": config resources is deprecated; declarations are not reservations or enforced limits. Configure limits in the execution backend.\n`);
     checkedOwner(options.owner);
@@ -1639,7 +1644,7 @@ export async function upWorld(configId, options = {}, abort) {
             mkdirSync(dirname(envFile), { recursive: true });
             // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
             // the mode the caller chose (a shared env file may be read under another uid).
-            writeFileSync(envFile, envFileContents(env), { mode: 0o600 });
+            publishEnvOutput(envOutputClaim, envFileContents(env));
             writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
             saveWorldInstance(worldInstance);
             const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
@@ -2840,7 +2845,7 @@ export function urlsWorld(name, root = process.cwd()) {
 export function urlWorld(name, options = {}) {
     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}`);
+        throw new Error(`World ${name} is not running; start it with: volter-world up ${status.config} --env-out <path> --name ${name}`);
     }
     if (options.service === undefined) {
         return Object.values(status.services)
@@ -3252,7 +3257,7 @@ async function runWithWorldEnvLogged(name, command, root, options = {}) {
 export function worldShellEnv(name, root = process.cwd()) {
     const status = statusWorld(name, root);
     if (!status.running)
-        throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+        throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
     return {
         shell: status.env.SHELL || admittedEnv(stripEnvOf(status.env)).SHELL || '/bin/bash',
         cwd: resolve(root),
@@ -3560,7 +3565,7 @@ function stopWorldProxy(root, name) {
 export function activateScript(name, root = process.cwd()) {
     const status = statusWorld(name, root);
     if (!status.running)
-        throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+        throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
     const baseEnv = status.env ?? {};
     // Bring up the ambient redirect proxy (best-effort) and fold its env in so the activated shell
     // routes https through the twins too — not just the Node injector / cliRedirect endpoint vars.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.21",
+  "version": "2.0.23",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -35,7 +35,7 @@
     "url": "git+https://github.com/volter-ai/twin.git",
     "directory": "packages/world-runtime"
   },
-  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/world-runtime#readme",
+  "homepage": "https://world.volter.ai/docs/reference/cli",
   "type": "module",
   "exports": {
     ".": {
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.14",
-    "@volter/world-console": "2.0.9"
+    "@volter/world-core": "2.0.15",
+    "@volter/world-console": "2.0.10"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
-    "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.14",
+    "@volter/world-access": "2.0.2",
+    "@volter/world-core": "2.0.15",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.14"
+    "@volter/twin-mongodb": "0.1.15"
   }
 }

package/src/branch.ts

@@ -15,7 +15,7 @@ import type { WorldInstance } from './schema.ts';
 import { parseInfraDefinition, pgliteDown, pgliteUp } from './pglite-backing.ts';
 import { redisTwinCli, redisTwinDown, redisTwinUp } from './redis-backing.ts';
 
-export type BranchOptions = { root?: string; envFile?: string; now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */ at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } };
+export type BranchOptions = { root?: string; envFile?: string; forceEnvOutput?: boolean; now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */ at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } };
 
 function stateServices(controlRoot: string): string[] {
   const stateRoot = worldStateRoot(controlRoot);
@@ -54,7 +54,7 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
   const began = Date.now();
   let instance: WorldInstance;
   try {
-    instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
+    instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile, forceEnvOutput: options.forceEnvOutput });
   } catch (error) {
     // only a record made during this call is ours to remove, and it is removed by its own createdAt, as the fork's
     // cleanup below does: a concurrent `branch` of the same name that recorded first keeps its World

package/src/changeset.ts

@@ -67,7 +67,7 @@ function requireWorld(name: string, root: string): WorldInstance {
   } catch (error) {
     if (!/World instance not found/.test(String((error as Error).message))) throw error;
     const known = listWorlds(root).map((world) => world.name);
-    throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-file <path> --name ${name}\``);
+    throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-out <path> --name ${name}\``);
   }
 }
 

package/src/cli.ts

@@ -71,7 +71,7 @@ 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-file=<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] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — the catalog's upkeep verdicts for the mounted twins: matrix debt, census (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
@@ -121,7 +121,7 @@ function printHelp(): void {
                                                   # window open, so the defaults land as observed state (diff empty, nothing pending)
   volter-world reset <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
                                                   # back to the defaults: down --purge, up, seed (refuses a referenced parent)
-  volter-world branch <world> <name> [--env-file=<path>] [--json] [--root <repo>]
+  volter-world branch <world> <name> [--env-out=<path>] [--json] [--root <repo>]
                                                   # a new world over the base's mirrors (its own log; the base's unpushed changes stay)
   volter-world checkout <name> [--json] [--root <repo>]   # a stopped world back up, state intact
   volter-world fetch <world> [--origin <twins url> --namespace <org>/<world>] --key <key> [--full] [--service <id>]... [--json] [--root <repo>]
@@ -169,7 +169,7 @@ function printHelp(): void {
                                                   # attachers: volter-world attach <http://host:manifest-port> -- <command...>
   volter-world activate <name> [--root <repo>]   # eval "$(volter-world activate <name>)" — a virtualenv for vendor APIs
   volter-world shell <name> [--root <repo>]      # drop into a subshell with the world active (any CLI hits the twins)
-  volter-world run <config> --env-file=<path> [--name <name>] [--mode local|share|sealed] [--keep] [--verbose] -- <command...>
+  volter-world run <config> --env-out=<path> [--name <name>] [--mode local|share|sealed] [--keep] [--verbose] -- <command...>
   volter-world share <name> [--service app] [--verify /health|--no-verify] [--provider cloudflare-quick|command] [--command <cmd> [-- <args…>]]
                                                   # {url} in command args = the service's local URL;
                                                   # --provider cloudflare-quick selects raw cloudflared and clears a configured custom command
@@ -298,9 +298,10 @@ async function main(): Promise<void> {
   }
 
   if (cmd === 'up') {
+    if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
     if (!subject) throw new Error('volter-world up: missing config');
-    const envFile = optionValue(rest, '--env-file');
-    if (!envFile) throw new Error('volter-world up: missing required --env-file=<path>');
+    const envFile = optionValue(rest, '--env-out');
+    if (!envFile) throw new Error('volter-world up: missing required --env-out=<path>');
     const name = optionValue(rest, '--name') || undefined;
     const mode = optionValue(rest, '--mode', 'local') as 'local' | 'share' | 'sealed';
     const isolationArg = optionValue(rest, '--isolation');
@@ -312,7 +313,7 @@ async function main(): Promise<void> {
     // --keep-state: boot over the state the World's directory already holds (a World carried somewhere else, e.g. a
     // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
     const keepState = rest.includes('--keep-state');
-    const instance = await superviseWorldUp(subject, { name, root, mode, envFile, owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+    const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
     printReady(instance);
     return;
   }
@@ -662,10 +663,11 @@ async function main(): Promise<void> {
   }
 
   if (cmd === 'branch') {
+    if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
     const [name] = positionalArgs(rest);
-    if (!subject || !name) throw new Error('volter-world branch: usage: volter-world branch <world> <name> [--env-file=<path>]');
-    const envFile = optionValue(rest, '--env-file') || undefined;
-    const { instance, forked } = await branchWorld(subject, name, { root, ...(envFile ? { envFile } : {}) });
+    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`);
     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;
@@ -1021,11 +1023,13 @@ async function main(): Promise<void> {
     if (!subject) throw new Error('volter-world run: missing config');
     const split = rest.indexOf('--');
     if (split < 0) throw new Error('volter-world run: pass command after --');
-    const envFile = optionValue(rest, '--env-file');
-    if (!envFile) throw new Error('volter-world run: missing required --env-file=<path>');
-    const name = optionValue(rest, '--name') || undefined;
-    const mode = optionValue(rest, '--mode', 'local') as 'local' | 'share' | 'sealed';
-    const result = await runWorld(subject, rest.slice(split + 1), { root, name, mode, envFile, owner: ownerOption(rest.slice(0, split)), keep: rest.slice(0, split).includes('--keep'), verbose: rest.slice(0, split).includes('--verbose') });
+    const worldArgs = rest.slice(0, split);
+    if (worldArgs.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
+    const envFile = optionValue(worldArgs, '--env-out');
+    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') });
     if (result.exitCode !== 0) {
       const detail = result.outcome.error ? `could not start (${result.outcome.error})`
         : result.outcome.signal ? `was terminated by ${result.outcome.signal}`

package/src/env-output.ts

@@ -0,0 +1,57 @@
+import { constants, closeSync, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+type PriorOutput = { path: string; contents: string };
+export type EnvOutputClaim = { path: string; contents?: Buffer; force: boolean; backupDir: string };
+
+function inspect(path: string): Buffer | undefined {
+  try {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.nlink !== 1) throw new Error('World env output must be a regular file with one link; symlinks are refused');
+    return readFileSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/** Refuse a custody/input file before any World service or lifecycle mutation starts. */
+export function claimEnvOutput(path: string, backupDir: string, prior?: PriorOutput, force = false): EnvOutputClaim {
+  const contents = inspect(path);
+  if (contents !== undefined && !force && !(prior?.path === path && Buffer.from(prior.contents).equals(contents))) {
+    throw new Error(`World refuses existing --env-out file it does not own: ${path}. Choose a new output path; never use a custody file. --force explicitly replaces a file with a private backup.`);
+  }
+  if (force && contents !== undefined) {
+      mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+      const hash = createHash('sha256').update(path).update('\0').update(contents).digest('hex');
+      const backup = join(backupDir, hash);
+      if (existsSync(backup)) {
+        if (!readFileSync(backup).equals(contents)) throw new Error('World env backup differs; refusing replacement');
+      } else writeFileSync(backup, contents, { mode: 0o600, flag: 'wx' });
+    }
+  return { path, contents, force, backupDir };
+}
+
+export function publishEnvOutput(claim: EnvOutputClaim, contents: string): void {
+  mkdirSync(dirname(claim.path), { recursive: true });
+  const current = inspect(claim.path);
+  if (current === undefined) {
+    const fd = openSync(claim.path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try { writeFileSync(fd, contents); } finally { closeSync(fd); }
+    return;
+  }
+  if (claim.contents === undefined || !current.equals(claim.contents)) throw new Error('World env output changed during boot; refusing to overwrite it');
+  const fd = openSync(claim.path, constants.O_RDWR | constants.O_NOFOLLOW);
+  try {
+    const opened = fstatSync(fd);
+    const named = lstatSync(claim.path);
+    if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== named.dev || opened.ino !== named.ino || !readFileSync(fd).equals(claim.contents)) {
+      throw new Error('World env output identity changed during boot; refusing to overwrite it');
+    }
+    ftruncateSync(fd, 0);
+    const bytes = Buffer.from(contents);
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+  } finally { closeSync(fd); }
+}

package/src/init.ts

@@ -1245,7 +1245,7 @@ export function initWorld(name: string, repoPath: string, options: InitOptions =
         'volter world down',
       ]
     : [
-        `volter-world up ${plan.configPath} --name ${plan.name} --env-file=${resolve(plan.out, 'world.env')}   # up WRITES the live env (twin URLs) there; app.env is init's static preview of the same map`,
+        `volter-world up ${plan.configPath} --name ${plan.name} --env-out=${resolve(plan.out, 'world.env')}   # up WRITES the live env (twin URLs) there; app.env is init's static preview of the same map`,
         ...(plan.seedEntry === null ? [] : [`volter-world seed ${plan.name} --cwd ${plan.repo}   # load the default data AFTER every up: it lands as data that was already there, the log empty; reset = down, up, seed`]),
         `volter-world env ${plan.name} -- <your app's dev command>   # run the app inside the world`,
         `volter-world down ${plan.name}`,

package/src/reflect.ts

@@ -413,7 +413,7 @@ export function composeOverrideForReflect(manifest: ReflectManifest, services: s
 
 // docker compose's global options that take a value — the override's -f must land after the consumer's own
 // files and before the subcommand, so these are stepped over to find it.
-const COMPOSE_VALUED_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '--progress', '--parallel', '--ansi']);
+const COMPOSE_VALUED_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-out', '--project-directory', '--progress', '--parallel', '--ansi']);
 
 /** Split `docker [docker flags] compose [compose flags] <subcommand…>`; undefined when it is not a compose command. */
 export function splitDockerComposeArgs(command: string[]): { head: string[]; composeFlags: string[]; tail: string[] } | undefined {

package/src/runtime.ts

@@ -1,3 +1,4 @@
+import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
@@ -168,7 +169,9 @@ export type UpWorldOptions = {
   mode?: WorldMode;
   /** Overrides the config's `isolation` for this boot (e.g. force 'process' for a share world). */
   isolation?: WorldIsolation;
+  /** Output path for generated World exports; never an input credentials file. */
   envFile?: string;
+  forceEnvOutput?: boolean;
   share?: Omit<ShareWorldOptions, 'root' | 'service' | 'verifyPath'> & { verifyPath?: string | false };
   /** `checkout`: bring a stopped world back with its state — the data dir, marks, changesets and
    *  episodes survive the boot; logs and the pid file start clean. Never the default: `up` starts
@@ -1420,6 +1423,11 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
   const pidsFile = join(instance, 'pids');
   const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
   const instanceFile = join(instance, 'instance.json');
+  const priorOutputInstance = existsSync(instanceFile) ? JSON.parse(readFileSync(instanceFile, 'utf8')) as WorldInstance : undefined;
+  const priorOutput = priorOutputInstance?.name === name && resolve(priorOutputInstance.root) === root
+    ? { path: resolve(priorOutputInstance.envFile), contents: envFileContents(priorOutputInstance.env) } : undefined;
+  const envOutputClaim = claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'), priorOutput, options.forceEnvOutput);
+
   if (loaded.config.resources) process.stderr.write(`World "${name}": config resources is deprecated; declarations are not reservations or enforced limits. Configure limits in the execution backend.\n`);
   checkedOwner(options.owner);
   let resourcesClaimed = false;
@@ -1638,7 +1646,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       mkdirSync(dirname(envFile), { recursive: true });
       // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
       // the mode the caller chose (a shared env file may be read under another uid).
-      writeFileSync(envFile, envFileContents(env), { mode: 0o600 });
+      publishEnvOutput(envOutputClaim, envFileContents(env));
       writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
       saveWorldInstance(worldInstance);
       const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
@@ -2817,7 +2825,7 @@ export function urlsWorld(name: string, root = process.cwd()): WorldUrlInfo {
 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}`);
+    throw new Error(`World ${name} is not running; start it with: volter-world up ${status.config} --env-out <path> --name ${name}`);
   }
   if (options.service === undefined) {
     return Object.values(status.services)
@@ -3156,7 +3164,7 @@ async function runWithWorldEnvLogged(name: string, command: string[], root: stri
  * since starting a server is async; this pure helper stays synchronous + side-effect-free for tests. */
 export function worldShellEnv(name: string, root = process.cwd()): { shell: string; cwd: string; env: Record<string, string> } {
   const status = statusWorld(name, root);
-  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
   return {
     shell: status.env.SHELL || admittedEnv(stripEnvOf(status.env)).SHELL || '/bin/bash',
     cwd: resolve(root),
@@ -3413,7 +3421,7 @@ function stopWorldProxy(root: string, name: string): void {
  */
 export function activateScript(name: string, root = process.cwd()): string {
   const status = statusWorld(name, root);
-  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
   const baseEnv = status.env ?? {};
   // Bring up the ambient redirect proxy (best-effort) and fold its env in so the activated shell
   // routes https through the twins too — not just the Node injector / cliRedirect endpoint vars.