@volter/world-runtime 2.0.25 → 2.0.27

package/dist/src/cli.js

@@ -8,7 +8,7 @@ import { dirname, join, resolve } from 'node:path';
 import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
-import { clockFile, instanceDir, pruneWorlds } from "./runtime.js";
+import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
 import { worldResourceReport } from "./resources.js";
 import { worldConsumers, worldUsage } from "./consumers.js";
 import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from "./app-url.js";
@@ -990,7 +990,7 @@ async function main() {
             const { bridgeStreams, drainStreams } = createRequire(import.meta.url)('@volter/world-core/stream-bridge');
             const bridged = manifest.streams ? await bridgeStreams(manifest.streams, attachToken ?? manifest.env.VOLTER_TWINS_KEY ?? '') : { env: {} };
             // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
-            const commandEnv = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
+            const commandEnv = withoutVaultSignIn({ ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref });
             commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
             const child = spawn(command[0], command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
             const code = await new Promise((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
@@ -1012,7 +1012,7 @@ async function main() {
             const manifest = readReflectManifest(attachRoot, resolved.ref);
             if (!manifest)
                 throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
-            const env = { ...process.env, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
+            const env = { ...withoutVaultSignIn(process.env), VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
             Object.assign(env, sessionTrustEnv(manifest.caCertPath, env));
             let toRun = command;
             const compose = splitDockerComposeArgs(command);

package/dist/src/host-cli.js

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

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

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

package/dist/src/host-ready.js

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

package/dist/src/index.d.ts

@@ -39,7 +39,7 @@ export { fetchFromOrigin, worldOrigin } from './origin.js';
 export type { FetchOptions, FetchOutcome } from './origin.js';
 export { branchWorld, checkoutWorld } from './branch.js';
 export type { BranchOptions } from './branch.js';
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.js';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.js';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
@@ -51,3 +51,4 @@ export type { LocalBranchesOptions } from './local-branches.js';
 export type { ServedWorld } from './served-world.js';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.js';
 export { assertWorldStateRemovable } from './ancestry.js';
+export { withoutVaultSignIn } from './runtime.js';

package/dist/src/index.js

@@ -29,10 +29,11 @@ export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttac
 export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
 export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
 export { LocalBranches } from "./local-branches.js";
 export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
 export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
+export { withoutVaultSignIn } from "./runtime.js";

package/dist/src/init.d.ts

@@ -202,6 +202,15 @@ export declare const APP_READ_ENDPOINT_ENV: Record<string, {
 /** Render the private managed-infrastructure definition — deterministic, with no absolute paths.
  * Only meaningful when `plan.compose` is non-empty (writeWorldInit skips it otherwise). */
 export declare function renderComposeFile(plan: InitPlan): string;
+export type ParsedEnvEntry = {
+    name: string;
+    value: string;
+    source: string;
+};
+/** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
+ * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
+ * env agree on which names exist. */
+export declare function parseEnvFile(text: string, source: string): ParsedEnvEntry[];
 export declare function planWorldInit(name: string, repoPath: string, options?: InitOptions): InitPlan;
 /** The `app.env` rendering of the SAME map the config's `env` block holds — a dotenv for anything
  * attached to the World (a shell, app process, or CI step), annotated with the

package/dist/src/init.js

@@ -409,16 +409,17 @@ export function renderComposeFile(plan) {
 /** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
  * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
  * env agree on which names exist. */
-function parseEnvFile(text, source) {
+export function parseEnvFile(text, source) {
     const entries = [];
     for (const line of text.split(/\r?\n/)) {
         const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*)$/);
         if (!match)
             continue;
         let value = match[2].trim();
-        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2)
-            || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
-            value = value.slice(1, -1);
+        // A quoted value ends at its closing quote; what follows it (` # a comment`) is not the value.
+        const quoted = value.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+        if (quoted) {
+            value = quoted[2];
         }
         else {
             // Unquoted: a `#` after whitespace opens a trailing comment (dotenv semantics). Without this

package/dist/src/root.d.ts

@@ -15,6 +15,18 @@ export declare function sealedCredentialInfo(worldRoot: string, vendor: string):
 } | null;
 /** The signing secret sealed beside the credential (`{ headers, signingSecret }`), for ingest; null when none. */
 export declare function twinSigningSecret(worldRoot: string, vendor: string): Promise<string | null>;
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export declare function rootCredentialInput(worldRoot: string, vendor: string, env?: NodeJS.ProcessEnv): Promise<{
+    input: string | null;
+    from: string;
+    notes: string[];
+}>;
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export declare function credentialPayloadFrom(input: string, vendor: string): CredentialPayload;
 /** The root config carried in the state dir also names where the credential is sealed, so the

package/dist/src/root.js

@@ -8,14 +8,19 @@
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
 import { packEntry } from "./catalog.js";
-import { existsSync, readdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
 import { authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteExecute, clearRoot, openSealedCredential, readRoot, registerStateSystem, sealCredential, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
 import { loadWorldConfig, writeWorldConfig } from "./configs.js";
 import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from "./changeset.js";
 import { importModule } from "./import-module.js";
 import { statusWorld } from "./runtime.js";
+import { envNameVendor } from "./covers.js";
+import { parseEnvFile } from "./init.js";
+import { fakeEnvValue } from "./fixture-env.js";
+import { projectManifestDirs } from "./project-inspect.js";
 import { findInstalledPackage, twinPackageName } from "./catalog.js";
 // ── the user's sealing key ──────────────────────────────────────────────────────────────────
 /** `$XDG_CONFIG_HOME/volter/kek`, else `~/.config/volter/kek`: the key every credential this user
@@ -45,6 +50,127 @@ export async function twinSigningSecret(worldRoot, vendor) {
     const payload = await openSealedCredential(sealingKey(), JSON.parse(text), vendor);
     return typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? payload.signingSecret : null;
 }
+// ── where a root's credential comes from (company decision 0033) ────────────────────────────
+/** A vault the person is signed in to, as `bao login` (or `vault login`) leaves it: an address, a token of the same
+ *  CLI (`BAO_*` with `BAO_*`, `VAULT_*` with `VAULT_*`, else the CLI's token file), and its namespace if any. */
+function signedInVault(env) {
+    for (const prefix of ['BAO', 'VAULT']) {
+        const addr = env[`${prefix}_ADDR`];
+        if (!addr)
+            continue;
+        let token = env[`${prefix}_TOKEN`];
+        if (!token) {
+            try {
+                token = readFileSync(join(homedir(), '.vault-token'), 'utf8').trim();
+            }
+            catch { /* none */ }
+        }
+        if (!token)
+            return null;
+        vaultAddress(`${prefix}_ADDR`, addr); // a token never travels in the clear off this machine
+        const namespace = env[`${prefix}_NAMESPACE`];
+        return { addr: addr.replace(/\/+$/, ''), token, ...(namespace ? { namespace } : {}) };
+    }
+    return null;
+}
+/** A vault's address: https, or http only to this machine; no userinfo. Any host or IP: a company vault often sits on a
+ *  private name (`vault.acme.internal`, `10.1.2.3`), which a vendor's address may never be. */
+function vaultAddress(variable, addr) {
+    let url;
+    try {
+        url = new URL(addr);
+    }
+    catch {
+        throw new Error(`${variable} is not a URL: ${addr}`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${variable} must not carry credentials in its URL`);
+    // an IPv4 address in 127/8 (not a name that starts with "127."), localhost or [::1]
+    const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127(\.\d{1,3}){3}$/.test(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+        throw new Error(`${variable} must be https (http only to this machine): ${url.origin}`);
+}
+// The suffixes that carry a credential itself; a publishable key, a webhook or signing secret, an id, a URL or a DSN is
+// not what a root sends (covers.ts's broad list, less those).
+const ROOT_SECRET_SUFFIX = /_(SECRET_ACCESS_KEY|SERVICE_ROLE_KEY|OAUTH_TOKEN|AUTH_TOKEN|ACCESS_TOKEN|BEARER_TOKEN|BOT_TOKEN|API_TOKEN|API_SECRET|API_KEY|APIKEY|SECRET_KEY|SECRET|TOKEN|KEY)$/;
+// an OAuth app's client secret signs it in to the vendor; it is not the bearer a root sends
+const NOT_A_ROOT_SECRET = /_(PUBLISHABLE_KEY|WEBHOOK_SECRET|SIGNING_SECRET|ACCESS_KEY_ID|CLIENT_ID|CLIENT_SECRET|CONSUMER_KEY|ACCOUNT_SID)$/;
+/** A World's own fake for that name, or a twin's minted one: never a real credential. */
+function isFakeValue(name, value) {
+    return value === fakeEnvValue(name) || /twin[-_]?fake|_twin_|twin_bootstrap|twin_sandbox/i.test(value);
+}
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export async function rootCredentialInput(worldRoot, vendor, env = process.env) {
+    const notes = [];
+    const vault = signedInVault(env);
+    if (vault) {
+        const at = `${vault.addr}/v1/kv/data/vendors/${encodeURIComponent(vendor)}`;
+        let response;
+        try {
+            response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
+        }
+        catch (error) {
+            notes.push(`the vault at ${vault.addr} did not answer (${error.message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+        }
+        if (response) {
+            if (response.status === 403)
+                throw new Error(`the vault at ${vault.addr} refused kv/vendors/${vendor} (403): sign in again, or with a token that may read it`);
+            if (response.ok) {
+                let credential;
+                try {
+                    credential = (await response.json()).data?.data?.credential;
+                }
+                catch {
+                    throw new Error(`the vault at ${vault.addr} answered kv/vendors/${vendor} with no JSON`);
+                }
+                if (typeof credential === 'string' && credential.trim())
+                    return { input: credential, from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+                if (credential && typeof credential === 'object' && !Array.isArray(credential) && typeof credential.headers === 'object') {
+                    return { input: JSON.stringify(credential), from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+                }
+                notes.push(`the vault's kv/vendors/${vendor} holds no credential (a token, or a payload with headers)`);
+            }
+            else if (response.status === 404)
+                notes.push(`the vault holds no kv/vendors/${vendor}`);
+            else
+                throw new Error(`the vault at ${vault.addr} answered ${response.status} for kv/vendors/${vendor}`);
+        }
+    }
+    else
+        notes.push('not signed in to a vault (BAO_ADDR or VAULT_ADDR, and a token)');
+    // every .env the repo's members hold; within a member, .env.local over .env
+    const found = new Map();
+    for (const dir of projectManifestDirs(resolve(worldRoot))) {
+        const member = new Map();
+        for (const file of ['.env', '.env.local']) {
+            const path = join(dir, file);
+            if (!existsSync(path))
+                continue;
+            for (const entry of parseEnvFile(readFileSync(path, 'utf8'), relative(resolve(worldRoot), path) || file)) {
+                if (envNameVendor(entry.name) !== vendor || !ROOT_SECRET_SUFFIX.test(entry.name) || NOT_A_ROOT_SECRET.test(entry.name))
+                    continue;
+                if (!entry.value || isFakeValue(entry.name, entry.value))
+                    continue;
+                member.set(entry.name, { value: entry.value, source: entry.source });
+            }
+        }
+        for (const [name, hit] of member)
+            found.set(`${name} (${hit.source})`, hit);
+    }
+    const values = new Set([...found.values()].map((hit) => hit.value));
+    if (values.size === 1)
+        return { input: [...values][0], from: [...found.keys()].join(', '), notes };
+    if (values.size > 1)
+        throw new Error(`the repo's .env files hold more than one ${vendor} credential (${[...found.keys()].join(', ')}); pipe the one to seal`);
+    notes.push(`the repo's .env files hold no ${vendor} credential`);
+    return { input: null, from: '', notes };
+}
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export function credentialPayloadFrom(input, vendor) {
     const text = input.trim();

package/dist/src/runtime.d.ts

@@ -74,6 +74,10 @@ export type SharingClaim = {
 };
 /** Exported for direct drive: the liveness rule, pure over a claim. */
 export declare function sharingClaimAlive(claim: SharingClaim): boolean;
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export declare function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T;
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
 export declare function saveWorldInstance(instance: WorldInstance): void;

package/dist/src/runtime.js

@@ -1,6 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
 import { parallelStartup } from "./startup.js";
+import { waitForHostReady } from "./host-ready.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
 import { spawn, spawnSync } from 'node:child_process';
@@ -111,16 +112,25 @@ async function untilReadyOrEnded(wait, ended, boot, what, log) {
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port, boot, ended, twin, what, log, early = false) {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port, boot, ended, twin, what, log, early = false, sharedSettle) {
     // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
     boot.signal.throwIfAborted();
     const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
     const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' : new Promise(() => undefined))) : new Promise(() => undefined);
     // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
     if (ended) {
-        const settled = await Promise.race([own, ended.then(() => 'ended'), new Promise((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+        let timer;
+        let settled;
+        try {
+            const settle = sharedSettle ?? new Promise((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+            settled = await Promise.race([own, ended.then(() => 'ended'), settle]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
         boot.signal.throwIfAborted();
         if (settled === 'own')
             return;
@@ -504,6 +514,16 @@ const CONTROL_PLANE_EGRESS_ENV = [
     'https_proxy',
     'all_proxy',
 ];
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export function withoutVaultSignIn(env) {
+    const out = { ...env };
+    for (const name of Object.keys(out))
+        if (/^(BAO|VAULT)_/.test(name))
+            delete out[name];
+    return out;
+}
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export function admittedEnv(strip, env = process.env) {
     const out = {};
@@ -519,7 +539,7 @@ export function admittedEnv(strip, env = process.env) {
             continue;
         out[k] = v;
     }
-    return out;
+    return withoutVaultSignIn(out);
 }
 // The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
 function stripEnvOf(instanceEnv) {
@@ -1308,7 +1328,8 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     if (colocated.length === 0)
         return [];
     const hostCli = siblingScript(import.meta.url, 'host-cli');
-    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+    const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
     const allocated = [];
     for (const service of colocated) {
         const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1344,6 +1365,16 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         exitState.value = { code, signal };
     });
     const command = [process.execPath, ...args];
+    const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+    await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+        if (undeadPids([child.pid]).length)
+            recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+        try {
+            process.kill(-child.pid, 'SIGTERM');
+        }
+        catch { /* best effort cleanup */ }
+        throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
     await parallelStartup(allocated, async ({ service, port }) => {
         const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
         await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
@@ -1356,18 +1387,27 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
             throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
         });
     });
-    await parallelStartup(allocated, async ({ service, port }, index) => {
-        // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-        await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-            if (undeadPids([child.pid]).length)
-                recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-            try {
-                process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* best effort cleanup */ }
-            throw error;
+    let hostSettleTimer;
+    const hostSettle = new Promise((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+    try {
+        await parallelStartup(allocated, async ({ service, port }) => {
+            // The host has completed every start. Each matching boot answer can now
+            // end its own settle; legacy twins share one full host guard.
+            await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+                if (undeadPids([child.pid]).length)
+                    recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch { /* best effort cleanup */ }
+                throw error;
+            });
         });
-    });
+    }
+    finally {
+        if (hostSettleTimer !== undefined)
+            clearTimeout(hostSettleTimer);
+    }
     if (exitState.value !== null) {
         throw new Error(`The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
             + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`);
@@ -2503,7 +2543,7 @@ async function shareWorldReserved(name, options) {
     const out = openPrivateLog(log, 'w');
     const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
         cwd: root,
-        env: process.env,
+        env: withoutVaultSignIn(process.env),
         detached: true,
         stdio: ['ignore', out, out],
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.25",
+  "version": "2.0.27",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",

package/src/cli.ts

@@ -9,7 +9,7 @@ import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldC
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
 import type { WorldManifest } from './attach.ts';
-import { clockFile, instanceDir, pruneWorlds } from './runtime.ts';
+import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from './runtime.ts';
 import { worldResourceReport } from './resources.ts';
 import { worldConsumers, worldUsage } from './consumers.ts';
 import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
@@ -866,7 +866,7 @@ async function main(): Promise<void> {
       const { bridgeStreams, drainStreams } = createRequire(import.meta.url)('@volter/world-core/stream-bridge') as { bridgeStreams: (streams: WorldManifest['streams'], token: string) => Promise<{ env: Record<string, string> }>; drainStreams: (ms?: number) => Promise<void> };
       const bridged = manifest.streams ? await bridgeStreams(manifest.streams, attachToken ?? manifest.env.VOLTER_TWINS_KEY ?? '') : { env: {} };
       // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
-      const commandEnv: Record<string, string | undefined> = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
+      const commandEnv: Record<string, string | undefined> = withoutVaultSignIn({ ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref });
       commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
       const child = spawn(command[0]!, command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
       const code = await new Promise<number>((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
@@ -886,7 +886,7 @@ async function main(): Promise<void> {
       if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
       const manifest = readReflectManifest(attachRoot, resolved.ref);
       if (!manifest) throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
-      const env: Record<string, string> = { ...process.env as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
+      const env: Record<string, string> = { ...withoutVaultSignIn(process.env) as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
       Object.assign(env, sessionTrustEnv(manifest.caCertPath, env));
       let toRun = command;
       const compose = splitDockerComposeArgs(command);

package/src/host-cli.ts

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

package/src/host-ready.ts

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

package/src/index.ts

@@ -161,7 +161,7 @@ export type { FetchOptions, FetchOutcome } from './origin.ts';
 
 export { branchWorld, checkoutWorld } from './branch.ts';
 export type { BranchOptions } from './branch.ts';
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.ts';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
@@ -174,3 +174,5 @@ export type { ServedWorld } from './served-world.ts';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.ts';
 
 export { assertWorldStateRemovable } from './ancestry.ts';
+
+export { withoutVaultSignIn } from './runtime.ts';

package/src/init.ts

@@ -607,20 +607,21 @@ export function renderComposeFile(plan: InitPlan): string {
   return `${lines.join('\n')}\n`;
 }
 
-type ParsedEnvEntry = { name: string; value: string; source: string };
+export type ParsedEnvEntry = { name: string; value: string; source: string };
 
 /** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
  * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
  * env agree on which names exist. */
-function parseEnvFile(text: string, source: string): ParsedEnvEntry[] {
+export function parseEnvFile(text: string, source: string): ParsedEnvEntry[] {
   const entries: ParsedEnvEntry[] = [];
   for (const line of text.split(/\r?\n/)) {
     const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*)$/);
     if (!match) continue;
     let value = match[2]!.trim();
-    if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2)
-      || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
-      value = value.slice(1, -1);
+    // A quoted value ends at its closing quote; what follows it (` # a comment`) is not the value.
+    const quoted = value.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+    if (quoted) {
+      value = quoted[2]!;
     } else {
       // Unquoted: a `#` after whitespace opens a trailing comment (dotenv semantics). Without this
       // a line like `NEXTAUTH_URL=http://localhost:3000 # dev` yields a value with the comment

package/src/root.ts

@@ -8,8 +8,9 @@
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
 import { packEntry } from './catalog.ts';
-import { existsSync, readdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import {
   NO_SECRETS_CHECK, authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteExecute, clearRoot, observeAppends, openSealedCredential, readRoot, registerStateSystem, sealCredential, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
 } from '@volter/world-core';
@@ -18,6 +19,10 @@ import { changesetReadiness, collectObservations, type Observation, foldObservat
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
 import { importModule } from './import-module.ts';
 import { statusWorld } from './runtime.ts';
+import { envNameVendor } from './covers.ts';
+import { parseEnvFile } from './init.ts';
+import { fakeEnvValue } from './fixture-env.ts';
+import { projectManifestDirs } from './project-inspect.ts';
 import { findInstalledPackage, twinPackageName } from './catalog.ts';
 import type { WorldConfig } from './schema.ts';
 
@@ -51,6 +56,100 @@ export async function twinSigningSecret(worldRoot: string, vendor: string): Prom
   return typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? payload.signingSecret : null;
 }
 
+// ── where a root's credential comes from (company decision 0033) ────────────────────────────
+
+/** A vault the person is signed in to, as `bao login` (or `vault login`) leaves it: an address, a token of the same
+ *  CLI (`BAO_*` with `BAO_*`, `VAULT_*` with `VAULT_*`, else the CLI's token file), and its namespace if any. */
+function signedInVault(env: NodeJS.ProcessEnv): { addr: string; token: string; namespace?: string } | null {
+  for (const prefix of ['BAO', 'VAULT'] as const) {
+    const addr = env[`${prefix}_ADDR`];
+    if (!addr) continue;
+    let token = env[`${prefix}_TOKEN`];
+    if (!token) { try { token = readFileSync(join(homedir(), '.vault-token'), 'utf8').trim(); } catch { /* none */ } }
+    if (!token) return null;
+    vaultAddress(`${prefix}_ADDR`, addr); // a token never travels in the clear off this machine
+    const namespace = env[`${prefix}_NAMESPACE`];
+    return { addr: addr.replace(/\/+$/, ''), token, ...(namespace ? { namespace } : {}) };
+  }
+  return null;
+}
+
+/** A vault's address: https, or http only to this machine; no userinfo. Any host or IP: a company vault often sits on a
+ *  private name (`vault.acme.internal`, `10.1.2.3`), which a vendor's address may never be. */
+function vaultAddress(variable: string, addr: string): void {
+  let url: URL;
+  try { url = new URL(addr); } catch { throw new Error(`${variable} is not a URL: ${addr}`); }
+  if (url.username || url.password) throw new Error(`${variable} must not carry credentials in its URL`);
+  // an IPv4 address in 127/8 (not a name that starts with "127."), localhost or [::1]
+  const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127(\.\d{1,3}){3}$/.test(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) throw new Error(`${variable} must be https (http only to this machine): ${url.origin}`);
+}
+
+// The suffixes that carry a credential itself; a publishable key, a webhook or signing secret, an id, a URL or a DSN is
+// not what a root sends (covers.ts's broad list, less those).
+const ROOT_SECRET_SUFFIX = /_(SECRET_ACCESS_KEY|SERVICE_ROLE_KEY|OAUTH_TOKEN|AUTH_TOKEN|ACCESS_TOKEN|BEARER_TOKEN|BOT_TOKEN|API_TOKEN|API_SECRET|API_KEY|APIKEY|SECRET_KEY|SECRET|TOKEN|KEY)$/;
+// an OAuth app's client secret signs it in to the vendor; it is not the bearer a root sends
+const NOT_A_ROOT_SECRET = /_(PUBLISHABLE_KEY|WEBHOOK_SECRET|SIGNING_SECRET|ACCESS_KEY_ID|CLIENT_ID|CLIENT_SECRET|CONSUMER_KEY|ACCOUNT_SID)$/;
+/** A World's own fake for that name, or a twin's minted one: never a real credential. */
+function isFakeValue(name: string, value: string): boolean {
+  return value === fakeEnvValue(name) || /twin[-_]?fake|_twin_|twin_bootstrap|twin_sandbox/i.test(value);
+}
+
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export async function rootCredentialInput(worldRoot: string, vendor: string, env: NodeJS.ProcessEnv = process.env): Promise<{ input: string | null; from: string; notes: string[] }> {
+  const notes: string[] = [];
+  const vault = signedInVault(env);
+  if (vault) {
+    const at = `${vault.addr}/v1/kv/data/vendors/${encodeURIComponent(vendor)}`;
+    let response: Response | undefined;
+    try {
+      response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
+    } catch (error) {
+      notes.push(`the vault at ${vault.addr} did not answer (${(error as Error).message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+    }
+    if (response) {
+      if (response.status === 403) throw new Error(`the vault at ${vault.addr} refused kv/vendors/${vendor} (403): sign in again, or with a token that may read it`);
+      if (response.ok) {
+        let credential: unknown;
+        try { credential = ((await response.json()) as { data?: { data?: { credential?: unknown } } }).data?.data?.credential; }
+        catch { throw new Error(`the vault at ${vault.addr} answered kv/vendors/${vendor} with no JSON`); }
+        if (typeof credential === 'string' && credential.trim()) return { input: credential, from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+        if (credential && typeof credential === 'object' && !Array.isArray(credential) && typeof (credential as { headers?: unknown }).headers === 'object') {
+          return { input: JSON.stringify(credential), from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+        }
+        notes.push(`the vault's kv/vendors/${vendor} holds no credential (a token, or a payload with headers)`);
+      } else if (response.status === 404) notes.push(`the vault holds no kv/vendors/${vendor}`);
+      else throw new Error(`the vault at ${vault.addr} answered ${response.status} for kv/vendors/${vendor}`);
+    }
+  } else notes.push('not signed in to a vault (BAO_ADDR or VAULT_ADDR, and a token)');
+  // every .env the repo's members hold; within a member, .env.local over .env
+  const found = new Map<string, { value: string; source: string }>();
+  for (const dir of projectManifestDirs(resolve(worldRoot))) {
+    const member = new Map<string, { value: string; source: string }>();
+    for (const file of ['.env', '.env.local']) {
+      const path = join(dir, file);
+      if (!existsSync(path)) continue;
+      for (const entry of parseEnvFile(readFileSync(path, 'utf8'), relative(resolve(worldRoot), path) || file)) {
+        if (envNameVendor(entry.name) !== vendor || !ROOT_SECRET_SUFFIX.test(entry.name) || NOT_A_ROOT_SECRET.test(entry.name)) continue;
+        if (!entry.value || isFakeValue(entry.name, entry.value)) continue;
+        member.set(entry.name, { value: entry.value, source: entry.source });
+      }
+    }
+    for (const [name, hit] of member) found.set(`${name} (${hit.source})`, hit);
+  }
+  const values = new Set([...found.values()].map((hit) => hit.value));
+  if (values.size === 1) return { input: [...values][0]!, from: [...found.keys()].join(', '), notes };
+  if (values.size > 1) throw new Error(`the repo's .env files hold more than one ${vendor} credential (${[...found.keys()].join(', ')}); pipe the one to seal`);
+  notes.push(`the repo's .env files hold no ${vendor} credential`);
+  return { input: null, from: '', notes };
+}
+
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export function credentialPayloadFrom(input: string, vendor: string): CredentialPayload {
   const text = input.trim();

package/src/runtime.ts

@@ -1,6 +1,7 @@
 import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
 import { parallelStartup } from './startup.ts';
+import { waitForHostReady } from './host-ready.ts';
 import { assertWorldStateRemovable, removeWorldState } from './ancestry.ts';
 import { packCli, packEntry } from './catalog.ts';
 import { spawn, spawnSync } from 'node:child_process';
@@ -105,16 +106,21 @@ async function untilReadyOrEnded<T>(wait: (abort: AbortSignal) => Promise<T>, en
  *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
  *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
  *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports (a co-located host's)
- *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
-async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false): Promise<void> {
+ *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
+ *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
+async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false, sharedSettle?: Promise<'alive'>): Promise<void> {
   // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
   boot.signal.throwIfAborted();
   const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
   const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' as const : new Promise<never>(() => undefined))) : new Promise<never>(() => undefined);
   // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
   if (ended) {
-    const settled = await Promise.race([own, ended.then(() => 'ended' as const), new Promise<'alive'>((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let settled: 'own' | 'ended' | 'alive';
+    try {
+      const settle = sharedSettle ?? new Promise<'alive'>((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
+      settled = await Promise.race([own, ended.then(() => 'ended' as const), settle]);
+    } finally { if (timer !== undefined) clearTimeout(timer); }
     boot.signal.throwIfAborted();
     if (settled === 'own') return;
     if (settled === 'ended') throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
@@ -555,6 +561,15 @@ const CONTROL_PLANE_EGRESS_ENV = [
   'all_proxy',
 ];
 
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T {
+  const out = { ...env };
+  for (const name of Object.keys(out)) if (/^(BAO|VAULT)_/.test(name)) delete out[name];
+  return out;
+}
+
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
   const out: Record<string, string> = {};
@@ -567,7 +582,7 @@ export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv
     if (rules.some((r) => ('prefix' in r ? k.startsWith(r.prefix) : k === r.name))) continue;
     out[k] = v;
   }
-  return out;
+  return withoutVaultSignIn(out);
 }
 // The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
 function stripEnvOf(instanceEnv: Record<string, string>): string[] | undefined {
@@ -1324,7 +1339,8 @@ async function startColocatedServices(
 ): Promise<WorldServiceInstance[]> {
   if (colocated.length === 0) return [];
   const hostCli = siblingScript(import.meta.url, 'host-cli');
-  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+  const readyFile = join(paths.instance, `host-ready-${boot.bootId}.json`);
+  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker', '--ready-file', readyFile];
   const allocated: Array<{ service: WorldServiceConfig; port: number; mounted: MountedPackage }> = [];
   for (const service of colocated) {
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1362,6 +1378,12 @@ async function startColocatedServices(
   });
 
   const command = [process.execPath, ...args];
+  const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
+  await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+    if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
+    try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+    throw new Error(`Co-located host failed to complete startup (isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+  });
   await parallelStartup(allocated, async ({ service, port }) => {
     const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
     await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
@@ -1370,14 +1392,19 @@ async function startColocatedServices(
       throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
     });
   });
-  await parallelStartup(allocated, async ({ service, port }, index) => {
-    // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
-    await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
-      if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
-      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
-      throw error;
+  let hostSettleTimer: ReturnType<typeof setTimeout> | undefined;
+  const hostSettle = new Promise<'alive'>((resolveAlive) => { hostSettleTimer = setTimeout(() => resolveAlive('alive'), 300); });
+  try {
+    await parallelStartup(allocated, async ({ service, port }) => {
+      // The host has completed every start. Each matching boot answer can now
+      // end its own settle; legacy twins share one full host guard.
+      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch((error) => {
+        if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+        try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+        throw error;
+      });
     });
-  });
+  } finally { if (hostSettleTimer !== undefined) clearTimeout(hostSettleTimer); }
   if (exitState.value !== null) {
     throw new Error(
       `The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
@@ -2467,7 +2494,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
   const out = openPrivateLog(log, 'w');
   const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
     cwd: root,
-    env: process.env,
+    env: withoutVaultSignIn(process.env),
     detached: true,
     stdio: ['ignore', out, out],
   });