@volter/world-runtime 3.0.165 → 3.0.167

package/src/attach.ts

@@ -6,10 +6,11 @@
 // delegates to runWithWorldEnv, `--via direct` prints the manifest. Reflect and
 // remote refs are proposals (docs/guides/route-a-cli-through-the-world.md) and are refused loudly, never
 // silently degraded.
+import { createHash, X509Certificate } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { activeVendorMap } from './redirect-proxy.ts';
-import { statusWorld } from './runtime.ts';
+import { refuseRequiredCredentialTransport, statusWorld } from './runtime.ts';
 import { worldNetworkPolicyFromEnv, type WorldNetwork } from '@volter/world-core/network-policy';
 
 export const WORLD_REF_FILE = '.volter-world';
@@ -82,6 +83,16 @@ export interface WorldManifest {
    *  env its client reads, `${host}`/`${port}` being the attacher's loopback bridge
    *  (@volter/world-core/stream-bridge) */
   streams?: Record<string, { protocol: string; url: string; env: Record<string, string> }>;
+  /** what a browser is started with to reach the World's pages as a person's does (Chrome's flags): the World's proxy as
+   *  its proxy, and this World's CA alone trusted, by its key's SPKI hash, which Chrome matches in the chain the proxy
+   *  presents (each leaf followed by the CA). Chrome honours the trust flag only with a `--user-data-dir` of its own,
+   *  so the browser trusts this World's CA and no other profile is touched. Present when the World runs its proxy. */
+  browser?: { args: string[] };
+}
+
+/** The base64 SHA-256 of a certificate's SubjectPublicKeyInfo, as Chrome's `--ignore-certificate-errors-spki-list` takes it. */
+export function spkiHash(pem: string): string {
+  return createHash('sha256').update(new X509Certificate(pem).publicKey.export({ type: 'spki', format: 'der' })).digest('base64');
 }
 
 // Internal runtime vars are plumbing, not suggested credentials. CA-trust
@@ -112,11 +123,13 @@ export function deriveWorldManifest(name: string, worldEnv: Record<string, strin
   }
   const policy = worldNetworkPolicyFromEnv(worldEnv);
   const network = policy === undefined ? undefined : (({ version, world, ...permission }) => permission)(policy);
-  return { name, vendors, ca, proxy: worldEnv.VOLTER_WORLD_PROXY ?? null, env, ...(network === undefined ? {} : { network }) };
+  const proxy = worldEnv.VOLTER_WORLD_PROXY ?? null;
+  return { name, vendors, ca, proxy, env, ...(network === undefined ? {} : { network }), ...(proxy && ca ? { browser: { args: [`--proxy-server=${proxy}`, `--ignore-certificate-errors-spki-list=${spkiHash(ca)}`] } } : {}) };
 }
 
 /** The manifest of a local world instance (name resolved against `root` like every other verb). */
 export function worldManifest(name: string, root = process.cwd()): WorldManifest {
   const status = statusWorld(name, root);
+  refuseRequiredCredentialTransport(status, 'WorldManifest publication');
   return deriveWorldManifest(name, status.env);
 }

package/src/cli-commands.ts

@@ -152,6 +152,9 @@ function printHelp(): void {
                                                   # ref: explicit → $VOLTER_WORLD → nearest .volter-world file (docs/guides/route-a-cli-through-the-world.md)
                                                   # --via env (default): run the command attached; --via direct: print the manifest JSON
   volter-world manifest <name> [--root <repo>]    # the world manifest (vendors map, CA, traffic proxy, suggested env) as JSON
+  volter-world browser-flags <name> [--root <repo>]
+                                                  # Chrome's flags for the World's pages: its proxy, and its CA alone trusted (by SPKI);
+                                                  # pass them with a --user-data-dir of the browser's own
   volter-world reflect <name> --target-ip <ip> [--resolver-ip <ip>] [--port <p>] [--resolver-port <p>] [--upstream <dns-ip>] [--root <repo>]
                                                   # run the reflect front (SNI TLS door) + resolver in the foreground (docs/ATTACH.md);
                                                   # --port 443 --resolver-port 53 is what containers can reach (attach --via reflect);
@@ -841,7 +844,7 @@ export async function main(): Promise<void> {
     // The local env attach, every app's CMD path, needs the World's ref and its runtime alone: the two load together,
     // and the remote door (serve.ts) and the reflect front (reflect.ts, ca-trust.ts) load only on their own paths.
     // All five were imported one after another first (S2 R16: Dub's attach, 225 bodies in 341 ms before its `next`).
-    const [{ resolveWorldRef, isRemoteWorldRef, worldManifest }, { withoutVaultSignIn, instanceDir, attachWorld }] = await Promise.all([import('./attach.ts'), import('./runtime.ts')]);
+    const [{ resolveWorldRef, isRemoteWorldRef, worldManifest }, { withoutVaultSignIn, instanceDir, attachWorld, statusWorld: readAttachStatus, refuseRequiredCredentialTransport }] = await Promise.all([import('./attach.ts'), import('./runtime.ts')]);
     // `subject` may be the ref, a flag, or the `--` separator — reassemble and split.
     const args = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
     const split = args.indexOf('--');
@@ -899,6 +902,7 @@ export async function main(): Promise<void> {
       // gets the override — and everything else runs with the trust env and VOLTER_WORLD set, its DNS
       // being the caller's to point (a container's --dns, a resolver on the host).
       if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
+      refuseRequiredCredentialTransport(readAttachStatus(resolved.ref, attachRoot), 'reflect attachment');
       const [{ readReflectManifest, splitDockerComposeArgs, composeOverrideForReflect, dockerComposeWithOverride, ATTACHED_CA_PATH }, { sessionTrustEnv }] = await Promise.all([import('./reflect.ts'), import('./ca-trust.ts')]);
       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`);
@@ -936,10 +940,20 @@ export async function main(): Promise<void> {
     return;
   }
 
+  if (cmd === 'browser-flags') {
+    const { worldManifest } = await import('./attach.ts');
+    if (!subject) throw new Error('volter-world browser-flags: missing world name');
+    const browser = worldManifest(subject, root).browser;
+    if (!browser) throw new Error(`volter-world browser-flags: World "${subject}" runs no proxy (it has no twinned host or network policy, or this host opens no raw sockets), so a browser has no route to its pages`);
+    process.stdout.write(`${browser.args.join('\n')}\n`);
+    return;
+  }
+
   if (cmd === 'reflect') {
     const { reflectRoutesPath, startReflectFront, startReflectResolver, readReflectRoutes, writeReflectManifest, clearReflectManifest } = await import('./reflect.ts');
-    const { statusWorld, instanceDir } = await import('./runtime.ts');
+    const { statusWorld, instanceDir, refuseRequiredCredentialTransport } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world reflect: missing world name');
+    refuseRequiredCredentialTransport(statusWorld(subject, root), 'reflect front publication');
     const targetIp = optionValue(rest, '--target-ip');
     if (!targetIp) throw new Error('volter-world reflect: --target-ip <ip> is required (the address attachers reach the front at)');
     const routesPath = reflectRoutesPath(root, subject);
@@ -973,7 +987,7 @@ export async function main(): Promise<void> {
 
   if (cmd === 'serve') {
     const { startReflectFront } = await import('./reflect.ts');
-    const { statusWorld, instanceDir } = await import('./runtime.ts');
+    const { statusWorld, instanceDir, refuseRequiredCredentialTransport } = await import('./runtime.ts');
     const { startManifestServer, advertiseWorldManifest, MANIFEST_PATH } = await import('./serve.ts');
     if (!subject) throw new Error('volter-world serve: missing world name');
     const advertise = optionValue(rest, '--advertise');
@@ -985,6 +999,7 @@ export async function main(): Promise<void> {
       throw new Error(`volter-world serve: --advertise must be an origin URL, got "${advertise}"`);
     }
     if (advertisedUrl.protocol !== 'https:') throw new Error('volter-world serve: the advertised origin must be https (the door terminates TLS with the session CA)');
+    refuseRequiredCredentialTransport(statusWorld(subject, root), 'remote WorldManifest serving');
     const frontPort = Number(advertisedUrl.port) || 443;
     const front = await startReflectFront({
       envLoader: () => statusWorld(subject, root).env,

package/src/console-apart.ts

@@ -7,6 +7,7 @@
 
 import { errorMessage } from './error-message.ts';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
+import { forwardableHeaders } from './forwardable-headers.ts';
 
 /** What a console offers a host: its shell and assets under `base`, told where the Worlds are served. */
 export type ConsoleMount = { handle: (request: Request, base: string, opts?: { worlds?: string; names?: string[]; worldOrigin?: boolean }) => Promise<Response | null> };
@@ -28,7 +29,7 @@ export async function serveConsoleApart(mount: ConsoleMount, opts: { upstream: s
       if (!url.pathname.startsWith('/-/') || url.pathname.startsWith(`${CONSOLE_BASE}/`)) return Response.json({ error: 'the console serves the console and the host\'s doors only' }, { status: 404 });
       // a door, forwarded: the caller's token header rides along; no cookie goes up (this origin holds
       // none) and none comes back (a World's session belongs to the Worlds' origin, set there)
-      const headers = new Headers(request.headers);
+      const headers = forwardableHeaders(request.headers);
       for (const h of ['host', 'cookie', 'origin', 'referer']) headers.delete(h);
       const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
       const answer = await fetch(`${upstream}${url.pathname}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' });
@@ -65,7 +66,7 @@ export async function serveConsoleFor(target: string, opts: { hostname?: string;
     hostname, port: opts.port !== undefined && opts.port !== 0 ? opts.port + 1 : 0, twinRequestJournal: false,
     async fetch(request) {
       const url = new URL(request.url);
-      const headers = new Headers(request.headers);
+      const headers = forwardableHeaders(request.headers);
       for (const h of ['host', 'origin', 'referer']) headers.delete(h);
       const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
       const answer = await fetch(`${origin}${url.pathname}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' });

package/src/credential-door.ts

@@ -0,0 +1,54 @@
+import type { WorldServiceConfig } from './schema.ts';
+
+export type CredentialDoor = NonNullable<WorldServiceConfig['issues']>;
+
+/** The answer's own scalar property, without a file, directory or side transform. */
+export function isScalarCredentialField(value: string | undefined): boolean {
+  return value !== undefined && value.length > 0 && !/^(?:file|directory|side):/.test(value);
+}
+
+/** A saved alias extends the current descriptor; it cannot replace its issuer or fields. */
+export function composeCredentialDoor(saved: CredentialDoor | undefined, current: CredentialDoor | undefined, service: string): CredentialDoor | undefined {
+  if (current === undefined) {
+    if (saved !== undefined) throw new Error(`World service ${service}: its current pack has no credential door; revalidate its declared aliases`);
+    return undefined;
+  }
+  const aliases: Array<[string, string]> = [];
+  const fields = new Set(Object.values(current.fill).filter(isScalarCredentialField));
+  for (const [name, field] of Object.entries(saved?.fill ?? {})) {
+    if (Object.hasOwn(current.fill, name)) {
+      if (current.fill[name] !== field) throw new Error(`World service ${service}: credential binding ${name} conflicts with its current pack; revalidate the source`);
+      continue;
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !isScalarCredentialField(field) || !fields.has(field))
+      throw new Error(`World service ${service}: alias ${name} does not name a current scalar credential field; revalidate the source`);
+    aliases.push([name, field]);
+  }
+  const fill = Object.fromEntries([...Object.entries(current.fill), ...aliases]);
+  const required = saved?.required;
+  if (required !== undefined) {
+    if (!Array.isArray(required)) throw new Error(`World service ${service}: required credential names must be an array`);
+    const seen = new Set<string>();
+    for (const name of required) {
+      if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || seen.has(name)
+        || !Object.hasOwn(fill, name) || !isScalarCredentialField(fill[name]) || !fields.has(fill[name]!)) {
+        throw new Error(`World service ${service}: required credential ${String(name)} does not name a current scalar field`);
+      }
+      seen.add(name);
+    }
+  }
+  return { path: current.path, body: current.body, fill, ...(required === undefined ? {} : { required: [...required] }) };
+}
+
+/** Non-pack process doors keep their own contract. Omitted type means twin, as at startup. */
+export function withCurrentCredentialDoor(service: WorldServiceConfig, current: CredentialDoor | undefined): WorldServiceConfig {
+  if ((service.type ?? 'twin') !== 'twin') return service;
+  const door = composeCredentialDoor(service.issues, current, service.id);
+  if (door === undefined) return service;
+  for (const name of Object.keys(door.fill)) {
+    if (Object.hasOwn(current!.fill, name) && !door.required?.includes(name)) continue;
+    if (name === service.injectEnv || Object.hasOwn(service.injectEnvTemplates ?? {}, name) || Object.hasOwn(service.cliRedirect ?? {}, name))
+      throw new Error(`World service ${service.id}: credential alias ${name} conflicts with an endpoint binding`);
+  }
+  return { ...service, issues: door };
+}

package/src/fixture-env.ts

@@ -201,7 +201,7 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   // Stripe's keys carry their kind in their prefix, and applications check it before calling (Cal.com's Stripe app
   // refuses a key that is not `sk_…`/`pk_…`); a webhook signing secret is `whsec_…`. Test mode, as a World is.
   { match: /(^|_)STRIPE_[A-Z0-9_]*WEBHOOK_SECRET$/, value: () => 'whsec_twinfake0000000000000000000000000000', source: 'https://docs.stripe.com/webhooks#verify-events' },
-  { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
+  { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test' + '_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
   { match: /(^|_)STRIPE_[A-Z0-9_]*(PUBLISHABLE|PUBLIC)(_API)?_KEY$/, value: () => 'pk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (pk_test_)' },
   // tavily-auth.ts and firecrawl-auth.ts refuse a key without the vendor's prefix with the vendor's 401
   { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'earlier @volter/twin-tavily tavily-auth.ts' },
@@ -209,7 +209,7 @@ const CREDENTIAL_SHAPES: Array<{ match: RegExp; value: (name: string) => string;
   // a Clerk webhook's signing secret is Svix's (`whsec_` and base64), which the app's verifier decodes; the World registers
   // its endpoint with the same secret (the Clerk twin's webhooks door takes `signing_secret`)
   { match: /(^|_)CLERK_WEBHOOK(_SIGNING)?_SECRET$/, value: () => `whsec_${Buffer.from('twin-fake-clerk-webhook-secret!!').toString('base64')}`, source: 'https://clerk.com/docs/webhooks/sync-data (CLERK_WEBHOOK_SIGNING_SECRET, whsec_); https://docs.svix.com/receiving/verifying-payloads/how-manual' },
-  { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'earlier @volter/twin-clerk manifest.ts' },
+  { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test' + '_twinfake000000000000000000000000000000', source: 'earlier @volter/twin-clerk manifest.ts' },
   { match: /(^|_)CLERK_[A-Z0-9_]*PUBLISHABLE[A-Z0-9_]*$/, value: () => `pk_test_${Buffer.from('twin.clerk.accounts.dev$').toString('base64')}`, source: 'earlier @volter/twin-clerk index.ts' },
 ];
 

package/src/forwardable-headers.ts

@@ -0,0 +1,15 @@
+/** The headers of one connection, not of the request (RFC 9110 §7.6.1), with `expect`: the hop that received them
+ *  answered them (Node's server sends the 100 Continue itself). Node's fetch refuses `transfer-encoding`, `keep-alive`,
+ *  `upgrade`, `expect` and a `connection` other than close/keep-alive outright, so a request forwarded with them fails
+ *  `fetch failed (UND_ERR_INVALID_ARG)`; the body streams on and fetch frames it afresh. Every World path that forwards
+ *  a received request into fetch (the redirect proxy, a served World's twin routes, a reflected host) copies its
+ *  headers through this. */
+const HOP_BY_HOP = ['connection', 'keep-alive', 'proxy-connection', 'transfer-encoding', 'te', 'trailer', 'upgrade', 'expect'];
+const TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i;
+
+export function forwardableHeaders(incoming: Headers): Headers {
+  const headers = new Headers(incoming);
+  for (const listed of (incoming.get('connection') ?? '').split(',')) { const name = listed.trim(); if (TOKEN.test(name)) headers.delete(name); }
+  for (const h of HOP_BY_HOP) headers.delete(h);
+  return headers;
+}

package/src/go-mysql-binding.ts

@@ -3,11 +3,18 @@ export type GoMysqlBinding = { dsnFormat: 'go-mysql'; endpoint: 'explicit-port'
 
 /** Only versioned, explicitly typed data selects a driver grammar. */
 export function goMysqlBinding(entry: Record<string, unknown>, version: unknown, name: string, declaredPort: number): Partial<GoMysqlBinding> {
+  if (entry.dsnFormat !== undefined && version !== 6 && version !== 7)
+    throw new Error(`volter init: ${name} needs a valid stack-needs version6/7 Go MySQL binding`);
+  return goMysqlBindingFields(entry, name, declaredPort);
+}
+
+/** The driver fields themselves; callers own their separate input-version gate. */
+export function goMysqlBindingFields(entry: Record<string, unknown>, name: string, declaredPort: number): Partial<GoMysqlBinding> {
   if (entry.dsnFormat === undefined) {
     if (entry.endpoint !== undefined || entry.dsnPrefix !== undefined || entry.dsnProtocol !== undefined) throw new Error(`volter init: ${name} has DSN fields without a declared format`);
     return {};
   }
-  if ((version !== 6 && version !== 7) || entry.dsnFormat !== 'go-mysql' || entry.scheme !== 'mysql' || entry.withPort !== undefined
+  if (entry.dsnFormat !== 'go-mysql' || entry.scheme !== 'mysql' || entry.withPort !== undefined
     || (entry.endpoint !== 'explicit-port' && entry.endpoint !== 'default-port') || (entry.dsnPrefix !== '' && entry.dsnPrefix !== 'mysql://')
     || (entry.dsnProtocol !== '' && entry.dsnProtocol !== 'tcp') || !Number.isInteger(entry.containerPort) || Number(entry.containerPort) < 1 || Number(entry.containerPort) > 65535
     || (entry.endpoint === 'default-port' && entry.containerPort !== declaredPort)

package/src/guest-runner.ts

@@ -9,9 +9,10 @@ import { allocatePort } from './tcp-port.ts';
 import { ownedPath, assertOwnedRealPath } from './owned-path.ts';
 import { commandLifetime, commandProcessGroup } from './command-lifetime.ts';
 import { beginGuestProcess, retainGuestProcess, readGuestProcesses, releaseGuestProcesses } from './guest-processes.mjs';
-import { retireOwnedProcessGroups } from './runtime.ts';
+import { refuseRequiredCredentialTransport, retireOwnedProcessGroups } from './runtime.ts';
 import { guestControl } from './guest-control.mjs';
 import { admitGuestArgv, guestCommandGap, guestEnvironment } from './guest-command.mjs';
+import { forwardableHeaders } from './forwardable-headers.ts';
 type Plan = { runtime: string; cwd: string; env: Record<string, string>; command: string[]; ports: number[]; copies: Array<{ sources: string[]; destination: string; cwd: string }> };
 type Guest = { name: string; dir: string; cwd: string; env: Record<string, string>; child: ChildProcess; lifetime: ReturnType<typeof commandLifetime>; runtime: RemoteRuntime; ports: Set<number>; status: MachineStatus; stopping?: boolean; launch?: RemoteProcessHandle; imageRuntime: string; agentPort: number; resetOnStop?: boolean };
 const delay = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms));
@@ -134,6 +135,7 @@ function worldEnv(): NodeJS.ProcessEnv {
   const instancePath = process.env.VOLTER_WORLD_INSTANCE;
   if (!instancePath) throw new Error('guest execution requires a World instance');
   const instance = JSON.parse(readFileSync(instancePath, 'utf8'));
+  refuseRequiredCredentialTransport(instance, 'light machine application transport', 'WORLD_MACHINE_CAPABILITY_GAP');
   // proxy-env has the completed vendor map; the early twin process env may not.
   const current = JSON.parse(readFileSync(join(dirname(instancePath), 'proxy-env.json'), 'utf8'));
   const env: NodeJS.ProcessEnv = { ...instance.env, ...current };
@@ -245,13 +247,14 @@ export function createLightGuestPool(options: LightPoolOptions & { world: string
     pauseMode: 'freeze-processes',
     async start({ id }) { const g = guests.get(id); if (!g) throw new Error('Substrate guest launch was not prepared'); return { name: id, url: `http://127.0.0.1:${g.agentPort}` }; },
     async pause({ name }) { const g = live(name); await ask(g.child, 'pause'); update(g, { state: 'paused' }); },
-    async resume({ name }) { const g = guests.get(name); if (!g || g.status.state !== 'paused') throw new Error('Substrate guest cannot resume'); await ask(g.child, 'resume'); update(g, { state: 'started' }); },
+    async resume({ name }) { worldEnv(); const g = guests.get(name); if (!g || g.status.state !== 'paused') throw new Error('Substrate guest cannot resume'); await ask(g.child, 'resume'); update(g, { state: 'started' }); },
     async stop({ name }) { await stop(name); },
     running() { return new Set([...guests].filter(([, g]) => g.status.state === 'started').map(([name]) => name)); },
   };
   return {
     kind: 'light',
     async admitRun(spec) {
+      worldEnv(); // Required application bindings have no admitted guest transport.
       if (!/^[a-zA-Z0-9_-]+$/.test(spec.name)) throw new Error('invalid guest name');
       const image = options.images?.[spec.image];
       if (!image) throw new Error(`image ${spec.image} has no light guest context`);
@@ -386,6 +389,7 @@ export function createLightGuestPool(options: LightPoolOptions & { world: string
       } finally { starting = false; clearTimeout(deadline); }
     },
     async exec(name, spec) {
+      worldEnv(); // Re-read the owning boot before a later command can start.
       const g = live(name);
       const queue: Array<{ stdout?: string } | { stderr?: string } | { exit: number }> = []; let wake: (() => void) | undefined, done = false;
       const push = (item: (typeof queue)[number]): void => { queue.push(item); wake?.(); };
@@ -401,8 +405,8 @@ export function createLightGuestPool(options: LightPoolOptions & { world: string
     async request(name, port, request) {
       const g = live(name);
       if (!g.ports.has(port)) throw new Error('guest port is not declared');
-      const url = new URL(request.url), headers = new Headers(request.headers);
-      for (const key of ['host', 'connection', 'content-length', 'transfer-encoding']) headers.delete(key);
+      const url = new URL(request.url), headers = forwardableHeaders(request.headers);
+      for (const key of ['host', 'content-length']) headers.delete(key);
       const init = { method: request.method, headers, body: ['GET', 'HEAD'].includes(request.method) ? undefined : await request.arrayBuffer(), signal: request.signal, redirect: 'manual' as const };
       return g.runtime.request(port, url.pathname + url.search, init);
     },

package/src/host-ready.ts

@@ -20,12 +20,21 @@ export function publishHostReady(path: string, boot: string, ports: Record<strin
   renameSync(temporary, path);
 }
 
+/** The twins a co-located host's log says it has started (host-cli's `event twin=<id> kind=started` lines). Only
+ *  starts count: a twin's own output, the recorder's time marks or another twin's errors are not progress. */
+export function startedTwins(log: string): number {
+  let text: string;
+  try { text = readFileSync(log, 'utf8'); } catch { return 0; }
+  return new Set(Array.from(text.matchAll(/^event twin=(\S+) kind=started\b/gmu), (match) => match[1])).size;
+}
+
 /**
  * Receipt admission is cancellation-aware; stale or malformed state is never
  * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
- * one: each change in `progress` (the host log's size, which grows with every
- * twin it starts) begins the bound again, so a host still starting its twins
- * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ * one: each change in `progress` (the count of twins started, `startedTwins`)
+ * begins the bound again, so a host still starting its twins on a busy machine
+ * is waited for, and one that starts no further twin for `timeoutMs` is not.
+ * Starts are finite, so the whole wait is at most (twins + 1) × `timeoutMs`.
  * Resolves with what the receipt says of the host's start: when it was published, its steps before, and which declared
  * twins' main ports are byte streams.
  */

package/src/index.ts

@@ -103,6 +103,10 @@ export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, Repo
 // world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.ts';
 export { STATE_GITIGNORE } from './init.ts';
+export { MANAGED_API_SOURCE_READER_CONTRACT } from './managed-api-source.ts';
+export type { ManagedApiSourceReader, ManagedApiSourceReading } from './managed-api-source.ts';
+/** Current resolved-catalog metadata; callers authenticate its supplying package bytes separately. */
+export { packFacts, type PackFacts } from './pack-facts.ts';
 export { clockFile, instanceDir } from './runtime.ts';
 export { setWorldClock, writeWorldClock } from './clock.ts';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.ts';
@@ -159,7 +163,7 @@ export {
 } from './serve.ts';
 export type { ManifestServerHandle, ManifestServerOptions } from './serve.ts';
 
-export { resetWorld, seedEntryFor, seedWorld } from './placeholder.ts';
+export { resetWorld, seedEntryFor, seedServedWorld, seedWorld, type SeedServedOutcome } from './placeholder.ts';
 export type { SeedWorldOptions, SeedWorldOutcome } from './placeholder.ts';
 
 export { fetchFromOrigin, worldOrigin } from './origin.ts';

package/src/infra.ts

@@ -19,10 +19,15 @@ import type { ManagedProtocol } from './twin-backing.ts';
 
 /** Whether a program is on PATH, read from the file system without starting a process: where a missing program
  *  still costs a process round trip (a browser tab's kernel), the container probe is not spawned at all. */
+/** Whether a command is on PATH. On Windows the variable may be spelled `Path` (a copied environment is not
+ *  case-insensitive as `process.env` is) and a command is found with PATHEXT's extensions, as the shell finds it. */
 function onPath(name: string, env: NodeJS.ProcessEnv): boolean {
-  return (env.PATH ?? '').split(delimiter).some((dir) => {
+  const windows = process.platform === 'win32';
+  const value = windows ? Object.entries(env).find(([key]) => key.toUpperCase() === 'PATH')?.[1] : env.PATH;
+  const names = windows ? ['', ...(Object.entries(env).find(([key]) => key.toUpperCase() === 'PATHEXT')?.[1] ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)].map(ext => name + ext) : [name];
+  return (value ?? '').split(delimiter).some((dir) => {
     if (!dir) return false;
-    try { const path = join(dir, name); accessSync(path, constants.X_OK); return statSync(path).isFile(); } catch { return false; }
+    return names.some((candidate) => { try { const path = join(dir, candidate); accessSync(path, constants.X_OK); return statSync(path).isFile(); } catch { return false; } });
   });
 }
 
@@ -224,7 +229,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
       return 2;
     }
     // No docker on PATH is the same absence the probe's ENOENT reports, read without a process.
-    if (process.platform !== 'win32' && !onPath('docker', env)) return 'pglite';
+    if (!onPath('docker', env)) return 'pglite';
     const probe = await runCommand('docker', ['info', '--format', '{{.ServerVersion}}'], { env, timeout: 10_000, ...(signal ? { signal } : {}) });
     signal?.throwIfAborted();
     if (probe.status === 0 && probe.stdout.trim()) return 'docker';