@volter/world-runtime 2.0.1 → 2.0.3

package/src/local-branches.ts

@@ -0,0 +1,173 @@
+// LOCAL BRANCHES: the branches a local host makes of the Worlds it serves (docs/contributing/architecture.md,
+// "Viewing a World"). A branch is another World: the parent's config under a new name, cloned from the
+// parent through its own doors (its history cut at an instant, when one is asked), its clock frozen at
+// that instant so no twin's catch-up walks it forward, and removed when its time runs out. world-host
+// and `volter world view` both make them with this; a hosted World's supervisor makes its own.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDirName, withStateRemoval } from '@volter/world-core';
+import { clockFile } from './runtime.ts';
+import { loadWorldConfig } from './configs.ts';
+import { TOKEN_HEADER, type BranchDoors, type BranchRow, type MountedWorld } from './served-world.ts';
+
+/** What a branch records beside itself: whose branch it is, as of when, and until when. */
+type BranchRecord = { from: string; at: { instant?: string; live?: boolean; label?: string } | null; createdAt: string; expiresAt: string | null };
+const RECORD = 'branch.json';
+const SWEEP_MS = 60_000;
+
+/** A World's manifest under another name, in the manifest's own format: format 2 names a World in
+ *  `metadata.id` and serves it bare at `serving.name`; format 1 in `id` and `bare.name`. */
+function renamed(config: Record<string, unknown>, id: string, name: string): Record<string, unknown> {
+  if (config.schemaVersion === 2) {
+    return { ...config, metadata: { ...(config.metadata as Record<string, unknown> | undefined), id }, serving: { ...(config.serving as Record<string, unknown> | undefined), mode: 'bare', name } };
+  }
+  return { ...config, id, bare: { ...(config.bare as Record<string, unknown> | undefined), name } };
+}
+
+export type LocalBranchesOptions = {
+  /** where branches live: `<dir>/<org>/<world>/` */
+  dir: string;
+  /** the URL a branch reaches its parent at (the host's own listener, on loopback) */
+  origin: () => string;
+  /** the Worlds the host serves, by served name; branches join it while they live */
+  worlds: Map<string, MountedWorld>;
+  /** mount a World at a root, with its branches doors wired */
+  mount: (root: string) => Promise<MountedWorld>;
+  announce?: (line: string) => void;
+};
+
+export class LocalBranches {
+  private sweeper: ReturnType<typeof setInterval> | null = null;
+  constructor(private readonly o: LocalBranchesOptions) {}
+
+  private record(world: MountedWorld): BranchRecord | null {
+    try { return JSON.parse(readFileSync(join(world.root, stateDirName(), RECORD), 'utf8')) as BranchRecord; } catch { return null; }
+  }
+
+  /** The branches of `parent` this host holds. */
+  list(parent: string): BranchRow[] {
+    const rows: BranchRow[] = [];
+    for (const [name, world] of this.o.worlds) {
+      const r = this.record(world);
+      if (r?.from === parent) rows.push({ name, from: r.from, at: r.at, createdAt: r.createdAt, expiresAt: r.expiresAt });
+    }
+    return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+
+  /** Branches being made, by parent: a parent is not removed mid-clone. */
+  private readonly making = new Map<string, number>();
+  hasBranches(parent: string): boolean { return (this.making.get(parent) ?? 0) > 0 || this.list(parent).length > 0; }
+
+  /** A World's branches doors, answered by this host. */
+  doorsFor(parent: string): BranchDoors {
+    return {
+      list: async () => this.list(parent),
+      create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+      remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent) return false; await this.remove(name); return true; },
+    };
+  }
+
+  private async create(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
+    try { return await this.make(parent, at, ttlSeconds, parentKey); } finally {
+      const left = (this.making.get(parent) ?? 1) - 1;
+      if (left > 0) this.making.set(parent, left); else this.making.delete(parent);
+    }
+  }
+  private async make(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    const from = this.o.worlds.get(parent);
+    if (!from) throw new Error(`no world ${parent} here`);
+    const [org, world] = parent.split('/') as [string, string];
+    const stamp = at.instant ? at.instant.replace(/[-:]/g, '').replace(/\.\d+Z$|Z$/, '').toLowerCase().slice(0, 13) : 'now';
+    // a labelled branch (a pull request's preview) is named for its label; the random tail keeps a replacement distinct
+    // a name already taken (a 4-hex tail's rare clash) is passed over for a fresh tail, never made over
+    const free = (): { id: string; name: string; root: string } | null => {
+      for (let tries = 0; tries < 8; tries++) {
+        const suffix = `${at.label ? `-${at.label}` : `-at-${stamp}`}-${Buffer.from(crypto.getRandomValues(new Uint8Array(2))).toString('hex')}`;
+        const id = `${world.slice(0, 64 - suffix.length)}${suffix}`;
+        const name = `${org}/${id}`; const root = join(this.o.dir, org, id);
+        if (!this.o.worlds.has(name) && !existsSync(root)) return { id, name, root };
+      }
+      return null;
+    };
+    const picked = free();
+    if (!picked) throw new Error(`no free name for a branch of ${parent}`);
+    const { id, name, root } = picked;
+    // the parent's config under the branch's own name: the same twins, served at the branch's place
+    mkdirSync(join(root, stateDirName()), { recursive: true });
+    writeFileSync(join(root, stateDirName(), 'world.json'), `${JSON.stringify(renamed(JSON.parse(readFileSync(join(from.root, stateDirName(), 'world.json'), 'utf8')) as Record<string, unknown>, id, name), null, 2)}\n`);
+    let mounted: MountedWorld | undefined;
+    try {
+      mounted = await this.o.mount(root);
+      await mounted.boot(this.o.origin());
+      this.o.worlds.set(name, mounted);
+      const origin = this.o.origin();
+      // each twin's history cut at the instant, by the parent's own history door
+      let views: unknown;
+      if (at.instant) {
+        const cut = await from.handle(new Request(`${origin}/-/${parent}/history?at=${encodeURIComponent(at.instant)}`, { headers: { [TOKEN_HEADER]: from.token } }));
+        if (!cut.ok) throw new Error(`the history of ${parent} at ${at.instant}: ${await cut.text()}`);
+        views = ((await cut.json()) as { views: unknown }).views;
+      }
+      const cloned = await mounted.handle(new Request(`${origin}/-/${name}/origin`, { method: 'PUT', headers: { [TOKEN_HEADER]: mounted.token, 'content-type': 'application/json' }, body: JSON.stringify({ url: `${origin}/${parent}`, token: parentKey ?? from.token, ...(views ? { views } : {}) }) })); // the branch's own key to its parent (the parent's doors make it), never the parent's token
+      if (!cloned.ok) throw new Error(`cloning ${parent}: ${await cloned.text()}`);
+      // the branch's clock stands at its instant, else at the parent's: no twin's catch-up walks it on
+      // (a parent whose clock was never set: the branch's stands at now, frozen there, as http-api says);
+      // a live branch (a pull request's preview) keeps the parent's time: real time, or its simulated clock
+      const clock = at.instant ?? this.frozenClock(from) ?? (at.live ? null : new Date().toISOString());
+      if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
+      const createdAt = new Date().toISOString();
+      const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
+      writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
+      this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
+      return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+    } catch (error) {
+      this.o.worlds.delete(name);
+      try { await mounted?.stop(); } catch { /* reported below */ }
+      withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+      throw error;
+    }
+  }
+
+  /** The parent's frozen clock, when it has one. */
+  private frozenClock(world: MountedWorld): string | null {
+    try {
+      const held = readFileSync(clockFile(world.root, loadWorldConfig(join(world.root, stateDirName(), 'world.json'), world.root).config.id), 'utf8').trim();
+      return Number.isNaN(Date.parse(held)) ? null : held;
+    } catch { return null; }
+  }
+
+  /** Stop a branch and remove its World (a branch's own branches first). */
+  async remove(name: string): Promise<void> {
+    const world = this.o.worlds.get(name);
+    if (!world) return;
+    for (const child of this.list(name)) await this.remove(child.name);
+    await world.stop();
+    withStateRemoval(world.root, () => rmSync(world.root, { recursive: true, force: true }));
+    this.o.worlds.delete(name);
+    this.o.announce?.(`removed  ${name}`);
+  }
+
+  /** Remove the branches whose time ran out, now and every minute while the host serves. */
+  async resume(): Promise<void> {
+    await this.sweep();
+    this.sweeper = setInterval(() => { void this.sweep(); }, SWEEP_MS);
+    this.sweeper.unref?.();
+  }
+  /** One sweep at a time: a slow one never overlaps the next. */
+  private sweeping = false;
+  private async sweep(): Promise<void> {
+    if (this.sweeping) return;
+    this.sweeping = true;
+    try {
+      const now = Date.now();
+      for (const [name, world] of [...this.o.worlds]) {
+        const r = this.record(world);
+        if (r?.expiresAt && Date.parse(r.expiresAt) <= now && this.o.worlds.has(name)) {
+          try { await this.remove(name); } catch (error) { this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`); }
+        }
+      }
+    } finally { this.sweeping = false; }
+  }
+  stop(): void { if (this.sweeper) clearInterval(this.sweeper); this.sweeper = null; }
+}

package/src/pglite-backing.ts

@@ -62,8 +62,10 @@ export function infraConnections(services: InfraService[], env: Record<string, s
 
 // this module's directory under Node as under Bun: `volter-world-infra` is a node-shebang bin, where
 // `import.meta.dir` (Bun's) is undefined
-const HERE = fileURLToPath(new URL('.', import.meta.url));
-const HOST = join(HERE, 'pglite-host.mjs');
+// lazy: a module that builds a URL from import.meta.url when it loads fails to load in workerd, which bundles this
+// module into the hosted World (it never runs these services there)
+const here = (): string => fileURLToPath(new URL('.', import.meta.url));
+const hostScript = (): string => join(here(), 'pglite-host.mjs');
 const READY_TIMEOUT_MS = 60_000;
 const MONGODB_TWIN = '@volter/twin-mongodb';
 
@@ -76,7 +78,7 @@ function pidPath(dataDir: string, kind: string): string {
 
 /** The MongoDB twin's cli: the package installed above the World's config (an app repo), else the one
  *  this runtime was installed with (its dependency, or the checkout's workspace link). */
-export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worldConfig ? [dirname(worldConfig)] : []), HERE]): string {
+export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worldConfig ? [dirname(worldConfig)] : []), here()]): string {
   for (const from of froms) {
     const dir = findInstalledPackage(from, MONGODB_TWIN);
     const cli = dir === undefined ? undefined : packCli(dir);
@@ -89,7 +91,7 @@ export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worl
  *  process's own runtime; a checkout's is TypeScript whose kernel needs more than Node's type
  *  stripping, so it runs under Bun (this process's, or the one on PATH) — the repository's toolchain —
  *  and without Bun it is refused by name rather than started to fail. */
-export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000 }).status === 0, underBun = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'): string {
+export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000, windowsHide: true }).status === 0, underBun = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'): string {
   if (!cli.endsWith('.ts') || underBun) return process.execPath;
   if (bunOnPath()) return 'bun';
   throw new Error(`a checkout's MongoDB twin runs under bun, which is not on PATH (${cli} is TypeScript that Node cannot run)`);
@@ -101,7 +103,7 @@ function hostArgv(service: InfraService, serviceData: string): string[] {
     const cli = mongodbTwinCli(process.env.VOLTER_WORLD_CONFIG);
     return [twinRunner(cli), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
   }
-  return ['node', HOST, '--port', String(service.hostPort), '--data', serviceData];
+  return ['node', hostScript(), '--port', String(service.hostPort), '--data', serviceData];
 }
 
 function alive(pid: number): boolean {
@@ -160,6 +162,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string): Promi
       // a real fd, not a pipe: the host must outlive this process untethered
       const logFd = openSync(log, 'a');
       const child = spawn(command!, args, {
+        windowsHide: true,
         detached: true,
         stdio: ['ignore', logFd, logFd],
       });

package/src/prerequisites.ts

@@ -15,7 +15,7 @@ type RunResult = { status: number | null; stdout: string; stderr: string };
 type Runner = (cmd: string, args: string[]) => RunResult;
 
 const realRunner: Runner = (cmd, args) => {
-  const result = spawnSync(cmd, args, { encoding: 'utf8' });
+  const result = spawnSync(cmd, args, { windowsHide: true, encoding: 'utf8' });
   return {
     status: result.status,
     stdout: result.stdout || '',

package/src/process-groups.ts

@@ -13,7 +13,7 @@ export function survivingOwnedGroups(pids: number[]): number[] {
     }
   });
   if (!candidates.length || process.platform === 'win32') return candidates;
-  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], {
+  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
     encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
   });
   if (result.status !== 0 || result.error) return candidates;

package/src/redirect-proxy.ts

@@ -192,12 +192,12 @@ export function opensslAvailable(): boolean {
   // process start rather than a same-process `process.env.PATH` mutation made mid-test. Never set
   // this env var in real usage.
   if (process.env.VOLTER_TEST_NO_OPENSSL === '1') return false;
-  const r = spawnSync('openssl', ['version'], { stdio: 'ignore' });
+  const r = spawnSync('openssl', ['version'], { windowsHide: true, stdio: 'ignore' });
   return r.status === 0;
 }
 
 function runOpenssl(args: string[]): string {
-  const r = spawnSync('openssl', args, { encoding: 'utf8' });
+  const r = spawnSync('openssl', args, { windowsHide: true, encoding: 'utf8' });
   if (r.status !== 0) throw new Error(`openssl ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`);
   return r.stdout;
 }

package/src/root.ts

@@ -16,6 +16,7 @@ import {
 import { loadWorldConfig, writeWorldConfig } from './configs.ts';
 import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, type DeployReport, type ObserveReport } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
+import { importModule } from './import-module.ts';
 import { statusWorld } from './runtime.ts';
 import { findInstalledPackage, twinPackageName } from './catalog.ts';
 import type { WorldConfig } from './schema.ts';
@@ -120,7 +121,7 @@ async function packModule(vendor: string, from: string): Promise<Record<string,
   const registered = getPack(vendor);
   if (registered) return { pack: registered };
   const entry = packEntryPath(vendor, from);
-  return entry ? ((await import(entry)) as Record<string, unknown>) : 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. */
@@ -137,8 +138,32 @@ export async function packMirrorExports(vendor: string, from: string): Promise<R
   if (!entry) 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(file ? join(dir, file) : entry)) as Record<string, unknown>;
+  return importModule(file ? join(dir, file) : entry);
 }
+/** 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 async function packMirror(vendor: string, from: string): Promise<PackMirror | null> {
+  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: RegExp): ((...a: unknown[]) => unknown) | undefined => { const k = Object.keys(mod).find((key) => re.test(key) && typeof mod[key] === 'function'); return k ? mod[k] as (...a: unknown[]) => unknown : 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 as () => string, client: client as () => Promise<string>, ...(styles ? { styles: styles as () => Promise<string> } : {}), ...(signIn ? { signIn: signIn as PackMirror['signIn'] } : {}) };
+}
+
 /** 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: { root?: string; secret?: string }) => Response | Promise<Response>;

package/src/run-task.ts

@@ -13,7 +13,7 @@ export type RunTaskReply = { result: RunTaskResult } | { error: string };
  * The task process is outside the caller's POSIX process group and owns boot through teardown. */
 export function superviseWorldRun(configId: string, command: string[], options: RunWorldOptions): Promise<RunTaskResult> {
   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/src/runtime.ts

@@ -63,7 +63,7 @@ function spawnRecorded(serviceId: string, command: string, args: string[], cwd:
   const recorderEnv: NodeJS.ProcessEnv = { ...env, VOLTER_WORLD_SERVICE_ID: serviceId, VOLTER_WORLD_SERVICE_LOG: log,
     VOLTER_WORLD_SERVICE_LOG_DIR: logDir, VOLTER_WORLD_EVENTS: worldEventsPath(dirname(log)) };
   if (recorderEnv.NODE_OPTIONS !== undefined) { 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,
@@ -662,7 +662,7 @@ function processStarts(pids: number[]): Map<number, string> {
     }
     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) starts.set(Number(match[1]), match[2]!);
@@ -802,7 +802,7 @@ async function runExternalCommand(
   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 = ''; let failure: Error | undefined;
   const collect = (chunk: Buffer, out: boolean) => {
@@ -843,7 +843,7 @@ async function runExternalUp(
   const chunks: string[] = [];
   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: unknown;
     child.on('error', error => { failure = error; });
@@ -2208,11 +2208,11 @@ export function ownCommand(command: string[]): string[] {
 }
 
 function onPath(command: string): boolean {
-  return spawnSync('which', [command], { stdio: 'ignore', env: process.env }).status === 0;
+  return spawnSync('which', [command], { windowsHide: true, stdio: 'ignore', env: process.env }).status === 0;
 }
 
 function resolveWithPublicDns(hostname: string): string | undefined {
-  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) return undefined;
@@ -2252,7 +2252,7 @@ async function verifyPublicUrl(
     || (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');
@@ -2286,7 +2286,7 @@ async function verifyPublicUrl(
         `${hostname}:443:${resolvedIp}`,
         target,
       ],
-      { encoding: 'utf8' },
+      { windowsHide: true, encoding: 'utf8' },
     );
     if (result.status === 0) {
       const output = result.stdout;
@@ -2348,7 +2348,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
   // 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 +2523,7 @@ async function probeExternalOnce(
       return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
     }
     const [probeBin, ...probeArgs] = ownCommand([ready.command, ...(ready.args ?? [])]);
-    const result = spawnSync(probeBin!, probeArgs, {
+    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) return { ok: true, message: 'probe ok (command)' };
@@ -2878,7 +2878,7 @@ export function runWithWorldEnv(name: string, command: string[], root = process.
   if (command.length === 0) 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',
@@ -2951,7 +2951,7 @@ export async function attachWorld(name: string, command: string[], root = proces
   let retired = true;
   try {
     return await new Promise<number>((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: unknown;
       record.consumerPid = child.pid;
@@ -3032,7 +3032,7 @@ async function runWithWorldEnvLogged(name: string, command: string[], root: stri
     let spawnError: string | undefined;
     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'],
@@ -3114,7 +3114,7 @@ export async function shellWorld(name: string, root = process.cwd()): Promise<nu
     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 {
     if (proxy) {
@@ -3207,7 +3207,7 @@ function startProxyDaemonOwned(name: string, root: string, caCertPath: string, e
     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],
       });
     } finally { closeSync(proxyOut); }

package/src/schema.ts

@@ -173,6 +173,9 @@ 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.
@@ -704,7 +707,7 @@ export function assertWorldSelection(value: unknown, path: string): asserts valu
 
 function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   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;
@@ -721,6 +724,11 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   assertKeys(environment, ['values'], 'service.execution.environment', path);
   if (typeof value.id !== 'string' || value.id === '') 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') throw new Error(`Service "${value.id}" execution.cwd must be a string in ${path}`);
   if (execution.controlPlane !== undefined && typeof execution.controlPlane !== 'boolean') throw new Error(`Service "${value.id}" execution.controlPlane must be a boolean in ${path}`);
@@ -770,6 +778,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates as Record<string, string> }),
     ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect as Record<string, string> }),
     ...(value.root === undefined ? {} : { root: value.root as WorldServiceConfig['root'] }),
+    ...(value.signIn === undefined ? {} : { signIn: { as: (value.signIn as { as: string }).as } }),
     ...(external === undefined ? {} : { external }),
   };
   if (type !== 'external' && bindings.discover !== undefined) throw new Error(`Service "${legacy.id}" bindings.discover is only valid for external services in ${path}`);
@@ -889,6 +898,7 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
     ...(Object.keys(endpoint).length ? { endpoint } : {}),
     ...(Object.keys(bindings).length ? { bindings } : {}),
     ...(service.root === undefined ? {} : { root: service.root }),
+    ...(service.signIn === undefined ? {} : { signIn: service.signIn }),
   };
 }