@volter/world-runtime 2.0.0 → 2.0.2

package/dist/src/redis-backing.d.ts

@@ -0,0 +1,8 @@
+import type { InfraService } from './pglite-backing.js';
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export declare function redisTwinCli(from: string[]): string | undefined;
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export declare const redisTwinRoot: (dataDir: string) => string;
+export declare function redisTwinUp(services: InfraService[], dataDir: string, cli: string): Promise<void>;
+export declare function redisTwinStatus(services: InfraService[], dataDir: string): Promise<number>;
+export declare function redisTwinDown(services: InfraService[], dataDir: string): Promise<void>;

package/dist/src/redis-backing.js

@@ -0,0 +1,120 @@
+// The containerless backing for a World's managed REDIS: the redis twin (@volter/twin-redis) serving Redis's
+// own protocol on the loopback port the definition declares, its keys held in the World's tree under
+// VOLTER_WORLD_DATA. Chosen by `volter-world-infra` for every redis service unless the operator forces the
+// container backing (VOLTER_WORLD_INFRA_BACKING=docker); the definition, the injected REDIS_URL and the declared
+// service contract are the same either way, as the boundary comment in infra-cli.ts promises.
+//
+// Why the twin and not a container: a World's state branches, checkpoints and rolls back as one tree, and a Redis
+// in a container is state outside it (a branch of the World would share the container's queue and cache). The
+// twin keeps each key a subject of the World (packages/twin/redis/src/redis-storage.ts). It needs nothing
+// installed: no container runtime, no redis-server binary.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { findInstalledPackage, packCli } from "./catalog.js";
+const PACKAGE = '@volter/twin-redis';
+const READY_TIMEOUT_MS = 60_000;
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export function redisTwinCli(from) {
+    for (const dir of from) {
+        const found = findInstalledPackage(dir, PACKAGE);
+        const cli = found === undefined ? undefined : packCli(found);
+        if (cli !== undefined && existsSync(cli))
+            return cli;
+    }
+    return undefined;
+}
+const pidPath = (dataDir, service) => join(dataDir, `redis-twin-${service.hostPort}.pid`);
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export const redisTwinRoot = (dataDir) => join(dataDir, 'redis-twin');
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listening(port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+        // a port that answers PING with PONG is this service; anything else is not ready (or not ours)
+        socket.once('connect', () => socket.write('PING\r\n'));
+        socket.once('data', (chunk) => { socket.destroy(); resolve(chunk.toString('latin1').startsWith('+PONG')); });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function redisTwinUp(services, dataDir, cli) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
+            continue;
+        // a port that already answers is another process's (another World's twin, a redis-server): serving there would
+        // hand this World's app someone else's keys, so it is refused, never taken as ready
+        if (await listening(service.hostPort))
+            throw new Error(`port ${service.hostPort} already serves Redis for another process`);
+        const root = redisTwinRoot(dataDir);
+        mkdirSync(root, { recursive: true });
+        const log = join(dataDir, `redis-twin-${service.hostPort}.log`);
+        mkdirSync(dirname(log), { recursive: true });
+        // a real fd, not a pipe: the server outlives this process untethered
+        const logFd = openSync(log, 'a');
+        // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
+        // type transformation, not only stripping (the kernel declares constructor parameter properties)
+        const runtime = typeof globalThis.Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
+        const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+        closeSync(logFd);
+        writeFileSync(pidFile, `${child.pid}\n`);
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        while (!(await listening(service.hostPort)) || !alive(child.pid)) {
+            if (!alive(child.pid))
+                throw new Error(`redis exited before serving — see ${log}`);
+            if (Date.now() > deadline)
+                throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+            await sleep(200);
+        }
+    }
+}
+export async function redisTwinStatus(services, dataDir) {
+    let ready = 0;
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (!existsSync(pidFile))
+            continue;
+        if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
+            ready += 1;
+    }
+    return ready;
+}
+export async function redisTwinDown(services, dataDir) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service);
+        if (!existsSync(pidFile))
+            continue;
+        const pid = Number(readFileSync(pidFile, 'utf8').trim());
+        if (alive(pid)) {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+            const deadline = Date.now() + 5000;
+            while (alive(pid) && Date.now() < deadline)
+                await sleep(100);
+            if (alive(pid)) {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* raced */ }
+            }
+        }
+        rmSync(pidFile, { force: true });
+    }
+}

package/dist/src/root.d.ts

@@ -36,6 +36,29 @@ export declare function rootForControlRoot(controlRoot: string, service: string)
 /** The pack's mirror module (`src/<vendor>-mirror-ui.ts`: its shell, client and stylesheet), read as the
  *  hosted mirror build reads it (apps/cloud/scripts/mirrors.ts); a pack's index need not re-export them. */
 export declare function packMirrorExports(vendor: string, from: string): Promise<Record<string, unknown> | null>;
+/** A pack's mirror as the pack builds it (`<vendor>MirrorHtml`, `build<Vendor>MirrorClient`,
+ *  `<vendor>MirrorStyles`), found the way a World finds the pack; null when the pack has none. The
+ *  client builds at serve under Bun and is served prebuilt under Node, by the pack's own builder. */
+export type PackMirror = {
+    html: () => string;
+    client: () => Promise<string>;
+    styles?: () => Promise<string>; /** the account and a credential its screens sign in with (`<vendor>MirrorSignIn`): the account found in the twin's
+       *  state at `root`, the credential minted for it through the twin's own doors (`twin`), never a stored one read back */
+    signIn?: (as: string, ctx: MirrorSignInContext) => Promise<{
+        account: string;
+        token: string;
+    } | null> | {
+        account: string;
+        token: string;
+    } | null;
+};
+/** What a pack's `<vendor>MirrorSignIn` is given: the twin's state root (to find the account) and the twin's own doors
+ *  (to mint a credential for it, as the World's seed does through `/_twin/…`). */
+export type MirrorSignInContext = {
+    root: string;
+    twin: (path: string, init?: RequestInit) => Promise<Response>;
+};
+export declare function packMirror(vendor: string, from: string): Promise<PackMirror | null>;
 /** The real state system's adapters for a vendor: registered with the pack (protocol 2), else the
  *  pack's anchored exports (protocol 1: `perform<Name>Action`, `sync<Name>FromRemote`). */
 export type IngestAdapter = (request: Request, ctx: {

package/dist/src/root.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 // A TWIN'S ROOT (docs/concepts/the-model.md): the vendor's real account
 // behind a twin on a shared world. `volter twin <vendor> root <url> --deploy <policy>` records it,
 // key-free, in `.volter/world.json` (committed) and, at boot, in the twin's state dir (core's
@@ -22,6 +14,7 @@ import { authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteE
 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 { findInstalledPackage, twinPackageName } from "./catalog.js";
 // ── the user's sealing key ──────────────────────────────────────────────────────────────────
@@ -125,7 +118,7 @@ async function packModule(vendor, from) {
     if (registered)
         return { pack: registered };
     const entry = packEntryPath(vendor, from);
-    return entry ? (await import(__rewriteRelativeImportExtension(entry))) : null;
+    return entry ? await importModule(entry) : null;
 }
 /** The pack's module itself, installed beside the World or in this checkout: its every export (a
  *  mirror's shell and client), where the registry holds only the descriptor. */
@@ -144,7 +137,26 @@ export async function packMirrorExports(vendor, from) {
         return null;
     const dir = dirname(entry);
     const file = existsSync(dir) ? readdirSync(dir).find((f) => /-mirror-ui\.(ts|js)$/.test(f) && !f.includes('.test.')) : undefined;
-    return (await import(__rewriteRelativeImportExtension(file ? join(dir, file) : entry)));
+    return importModule(file ? join(dir, file) : entry);
+}
+export async function packMirror(vendor, from) {
+    const installed = findInstalledPackage(from, twinPackageName(vendor));
+    const dir = installed ?? resolve(import.meta.dir, '..', '..', 'twin', vendor);
+    // the pack's mirror module, as the hosted build reads it (its index need not re-export every builder)
+    const src = join(dir, 'src');
+    const file = existsSync(src) ? readdirSync(src).find((f) => f.endsWith('-mirror-ui.ts')) : undefined;
+    const entry = file ? join(src, file) : installed ? packEntry(installed) : join(src, 'index.ts');
+    if (!existsSync(entry))
+        return null;
+    const mod = await importModule(entry);
+    const pick = (re) => { const k = Object.keys(mod).find((key) => re.test(key) && typeof mod[key] === 'function'); return k ? mod[k] : undefined; };
+    const html = pick(/^\w+MirrorHtml$/);
+    const client = pick(/^build\w+MirrorClient$/);
+    const styles = pick(/^\w+MirrorStyles$/);
+    const signIn = pick(/^\w+MirrorSignIn$/);
+    if (!html || !client)
+        return null;
+    return { html: html, client: client, ...(styles ? { styles: styles } : {}), ...(signIn ? { signIn: signIn } : {}) };
 }
 export async function adaptersFor(vendor, from) {
     const registered = stateSystemFor(vendor);

package/dist/src/run-task.js

@@ -7,7 +7,7 @@ import { siblingScript } from "./sibling.js";
  * The task process is outside the caller's POSIX process group and owns boot through teardown. */
 export function superviseWorldRun(configId, command, options) {
     return new Promise((done, reject) => {
-        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'run-task-worker')], {
+        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'run-task-worker')], { windowsHide: true,
             cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
             stdio: ['inherit', 'inherit', 'inherit', 'ipc'], serialization: 'json',
         });

package/dist/src/runtime.d.ts

@@ -122,6 +122,7 @@ export declare function pruneWorlds(options?: {
     entries: WorldCleanupEntry[];
 };
 export declare function parseCloudflareQuickPublicUrl(candidate: string): string | undefined;
+export declare function ownCommand(command: string[]): string[];
 export declare function shareWorld(name: string, options?: ShareWorldOptions): Promise<WorldInstance>;
 export declare function shareWorldServices(name: string, options?: ShareWorldServicesOptions): Promise<WorldInstance>;
 /** TWIN-62: `unshare` must give tunnels the same contract plain `downWorld` already gives owned

package/dist/src/runtime.js

@@ -17,7 +17,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from "./pack-facts.js";
 import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
 import { Socket } from 'node:net';
-import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
 import { loadWorldConfig } from "./configs.js";
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
 import { resolveServicePackage } from "./catalog.js";
@@ -65,7 +65,7 @@ function spawnRecorded(serviceId, command, args, cwd, env, log) {
         recorderEnv.VOLTER_WORLD_SERVICE_NODE_OPTIONS = recorderEnv.NODE_OPTIONS;
         delete recorderEnv.NODE_OPTIONS;
     }
-    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'service-recorder'), command, ...args], {
+    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'service-recorder'), command, ...args], { windowsHide: true,
         cwd,
         env: recorderEnv,
         detached: true,
@@ -614,7 +614,7 @@ function processStarts(pids) {
         }
         return starts;
     }
-    const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
+    const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
     for (const line of (result.stdout ?? '').split('\n')) {
         const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
         if (match)
@@ -762,13 +762,13 @@ function getByJsonPath(value, jsonPath) {
     return current;
 }
 async function runExternalCommand(command, cwd, serviceId, phase, env = process.env, abort, timeoutMs = 60_000) {
-    const [bin, ...args] = command;
+    const [bin, ...args] = ownCommand(command);
     if (!bin)
         throw new Error(`External service "${serviceId}": ${phase} command is empty`);
     if (!commandExists(bin))
         throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the ${phase} command's tool is not installed)`);
     abort?.throwIfAborted();
-    const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(bin, args, { windowsHide: true, cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
     const lifetime = commandLifetime(child, abort, true);
     let stdout = '';
     let stderr = '';
@@ -803,7 +803,7 @@ async function runExternalCommand(command, cwd, serviceId, phase, env = process.
  * (instead of buffering through spawnSync's 1MB cap, which a large DB restore would overflow). Returns
  * the combined output so `discover` can read it. Throws with a bounded tail on nonzero exit. */
 async function runExternalUp(command, cwd, serviceId, env, logPath, abort) {
-    const [bin, ...args] = command;
+    const [bin, ...args] = ownCommand(command);
     if (!bin)
         throw new Error(`External service "${serviceId}": up command is empty`);
     if (!commandExists(bin)) {
@@ -815,7 +815,7 @@ async function runExternalUp(command, cwd, serviceId, env, logPath, abort) {
     const chunks = [];
     try {
         abort?.throwIfAborted();
-        const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+        const child = spawn(bin, args, { windowsHide: true, cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
         const lifetime = commandLifetime(child, abort, true);
         let failure;
         child.on('error', error => { failure = error; });
@@ -1453,7 +1453,8 @@ export async function upWorld(configId, options = {}, abort) {
             VOLTER_WORLD_MODE: mode,
             VOLTER_WORLD_CONFIG: loaded.path,
             VOLTER_WORLD_INSTANCE: instanceFile,
-            VOLTER_WORLD_DATA: data,
+            // every service's root is `<data>/<service id>`; the kernel finds another pack's store across them (A3, ownerStoreRoots)
+            [WORLD_DATA_ENV]: data,
             // the live env file this `up` writes: what a service that runs apps elsewhere (world-machine's guest) carries there
             VOLTER_WORLD_ENV_FILE: envFile,
             // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
@@ -2220,11 +2221,26 @@ function sleep(ms) {
 }
 function commandExists(command) {
     // Pass the live env so PATH reflects the current process (some runtimes snapshot env otherwise).
-    const result = spawnSync('which', [command], { stdio: 'ignore', env: process.env });
-    return result.status === 0;
+    return OWN_COMMANDS[command] !== undefined || onPath(command);
+}
+/** A lifecycle command naming this runtime's own bin (`volter-world-infra`, which `init` names in every managed
+ *  infrastructure's lifecycle) runs this runtime's own script with the executable running it, when nothing on PATH
+ *  answers the name: a bare `volter-world down` (no runner that put node_modules/.bin on PATH) failed "not found on
+ *  PATH" and left the infrastructure up. Only the name is mapped — no directory joins PATH — and a same-named
+ *  command on PATH still wins, as before. */
+const OWN_COMMANDS = { 'volter-world-infra': 'infra-cli' };
+export function ownCommand(command) {
+    const [bin, ...args] = command;
+    const stem = bin === undefined ? undefined : OWN_COMMANDS[bin];
+    if (stem === undefined || onPath(bin))
+        return command;
+    return [process.execPath, siblingScript(import.meta.url, stem), ...args];
+}
+function onPath(command) {
+    return spawnSync('which', [command], { windowsHide: true, stdio: 'ignore', env: process.env }).status === 0;
 }
 function resolveWithPublicDns(hostname) {
-    const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], {
+    const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], { windowsHide: true,
         encoding: 'utf8',
     });
     if (result.status !== 0)
@@ -2260,7 +2276,7 @@ async function verifyPublicUrl(publicUrl, path, timeoutMs) {
         || (isIP(normalizedHostname) === 4 && normalizedHostname.split('.')[0] === '127');
     if (local) {
         const target = publicHealthUrl(publicUrl, path);
-        const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { encoding: 'utf8' });
+        const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { windowsHide: true, encoding: 'utf8' });
         const separator = result.stdout.lastIndexOf('\n');
         const body = separator >= 0 ? result.stdout.slice(0, separator).trim() : result.stdout.trim();
         const status = Number(separator >= 0 ? result.stdout.slice(separator + 1).trim() : '0');
@@ -2291,7 +2307,7 @@ async function verifyPublicUrl(publicUrl, path, timeoutMs) {
             '--resolve',
             `${hostname}:443:${resolvedIp}`,
             target,
-        ], { encoding: 'utf8' });
+        ], { windowsHide: true, encoding: 'utf8' });
         if (result.status === 0) {
             const output = result.stdout;
             const separator = output.lastIndexOf('\n');
@@ -2354,7 +2370,7 @@ async function shareWorldReserved(name, options) {
     // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
     // share from accepting the previous process's URL handshake as the new process's endpoint.
     const out = openPrivateLog(log, 'w');
-    const child = spawn(tunnel.command, tunnel.args, {
+    const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
         cwd: root,
         env: process.env,
         detached: true,
@@ -2523,7 +2539,8 @@ async function probeExternalOnce(ready, cwd, env, logPath) {
         if (!commandExists(ready.command)) {
             return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
         }
-        const result = spawnSync(ready.command, ready.args ?? [], {
+        const [probeBin, ...probeArgs] = ownCommand([ready.command, ...(ready.args ?? [])]);
+        const result = spawnSync(probeBin, probeArgs, { windowsHide: true,
             cwd, encoding: 'utf8', env, timeout: DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
         });
         if (result.status === 0)
@@ -2897,7 +2914,7 @@ export function runWithWorldEnv(name, command, root = process.cwd(), options = {
         throw new Error('Missing command after --');
     const attached = worldAttachedCommandEnv(name, root, options.verbose);
     return new Promise((resolveExit) => {
-        const child = spawn(command[0], command.slice(1), {
+        const child = spawn(command[0], command.slice(1), { windowsHide: true,
             cwd: resolve(options.cwd ?? root),
             env: attached.env,
             stdio: 'inherit',
@@ -2981,7 +2998,7 @@ export async function attachWorld(name, command, root = process.cwd(), options =
     let retired = true;
     try {
         return await new Promise((done, reject) => {
-            const child = spawn(command[0], command.slice(1), { cwd: resolve(options.cwd ?? root), env: attached.env, stdio: 'inherit', detached: commandProcessGroup });
+            const child = spawn(command[0], command.slice(1), { windowsHide: true, cwd: resolve(options.cwd ?? root), env: attached.env, stdio: 'inherit', detached: commandProcessGroup });
             const lifetime = commandLifetime(child);
             let failure;
             record.consumerPid = child.pid;
@@ -3082,7 +3099,7 @@ async function runWithWorldEnvLogged(name, command, root, options = {}) {
         let spawnError;
         let child;
         try {
-            child = spawn(command[0], command.slice(1), {
+            child = spawn(command[0], command.slice(1), { windowsHide: true,
                 cwd: resolve(options.cwd ?? root),
                 env: attached.env,
                 stdio: ['inherit', 'pipe', 'pipe'],
@@ -3189,7 +3206,7 @@ export async function shellWorld(name, root = process.cwd()) {
         process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (env-only; install openssl for ambient https redirect). type 'exit' to leave.\n`);
     }
     try {
-        const result = spawnSync(shell, ['-i'], { cwd, env, stdio: 'inherit' });
+        const result = spawnSync(shell, ['-i'], { windowsHide: true, cwd, env, stdio: 'inherit' });
         return result.status ?? 0;
     }
     finally {
@@ -3297,7 +3314,7 @@ function startProxyDaemonOwned(name, root, caCertPath, envFile, boot, caller = p
         mkdirSync(dirname(proxyLogPath(root, name)), { recursive: true, mode: 0o700 });
         const proxyOut = openPrivateLog(proxyLogPath(root, name), 'a');
         try {
-            child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', root, ...(envFile ? [`--env-file=${envFile}`] : [])], {
+            child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', root, ...(envFile ? [`--env-file=${envFile}`] : [])], { windowsHide: true,
                 cwd: root, env: process.env, detached: true, stdio: ['ignore', proxyOut, proxyOut],
             });
         }

package/dist/src/schema.d.ts

@@ -190,6 +190,11 @@ export type WorldServiceConfig = {
      * to loopback services directly while presenting a disguised world to the app/user.
      */
     controlPlane?: boolean;
+    /** The account a vendor's own screens (its mirror) open signed in as: its handle, username or email, which the pack
+     *  resolves against the accounts this World holds (`<vendor>MirrorSignIn`). Nothing secret is written here. */
+    signIn?: {
+        as: string;
+    };
     injectEnv?: string;
     /**
      * Additional env vars exported into the generated world env after this service starts.

package/dist/src/schema.js

@@ -358,7 +358,7 @@ export function assertWorldSelection(value, path) {
 function serviceV2ToLegacy(value, path) {
     if (!record(value))
         throw new Error(`World service must be an object in ${path}`);
-    assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root'], `Service ${String(value.id ?? '')}`, path, true);
+    assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root', 'signIn'], `Service ${String(value.id ?? '')}`, path, true);
     const source = value.source === undefined ? {} : value.source;
     const execution = value.execution === undefined ? {} : value.execution;
     const endpoint = value.endpoint === undefined ? {} : value.endpoint;
@@ -379,6 +379,13 @@ function serviceV2ToLegacy(value, path) {
         throw new Error(`World service must define string id in ${path}`);
     if (value.description !== undefined && typeof value.description !== 'string')
         throw new Error(`Service "${value.id}" description must be a string in ${path}`);
+    if (value.signIn !== undefined) {
+        if (!record(value.signIn))
+            throw new Error(`Service "${value.id}" signIn must be an object in ${path}`);
+        assertKeys(value.signIn, ['as'], `Service "${value.id}" signIn`, path);
+        if (typeof value.signIn.as !== 'string' || value.signIn.as.trim() === '')
+            throw new Error(`Service "${value.id}" signIn.as must name an account (a handle, username or email) in ${path}`);
+    }
     if (value.description !== undefined && value['//'] !== undefined)
         throw new Error(`Service "${value.id}" must not set both description and // in ${path}`);
     if (execution.cwd !== undefined && typeof execution.cwd !== 'string')
@@ -437,6 +444,7 @@ function serviceV2ToLegacy(value, path) {
         ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates }),
         ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect }),
         ...(value.root === undefined ? {} : { root: value.root }),
+        ...(value.signIn === undefined ? {} : { signIn: { as: value.signIn.as } }),
         ...(external === undefined ? {} : { external }),
     };
     if (type !== 'external' && bindings.discover !== undefined)
@@ -573,6 +581,7 @@ function serviceToV2(service) {
         ...(Object.keys(endpoint).length ? { endpoint } : {}),
         ...(Object.keys(bindings).length ? { bindings } : {}),
         ...(service.root === undefined ? {} : { root: service.root }),
+        ...(service.signIn === undefined ? {} : { signIn: service.signIn }),
     };
 }
 /** Serialize normalized intent as the committed format-2 manifest. */