peachsim 0.1.1620 → 0.1.1635

package/cli/commands/control.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs'
 import http from 'node:http'
 import https from 'node:https'
 import { createRequire } from 'node:module'
+import net from 'node:net'
 import os from 'node:os'
 import path from 'node:path'
 import { bundleUrlForPlatform } from 'peach-engine/bundle-platform-url'
@@ -27,26 +28,40 @@ import {
   readPeachConfigFromSearchParams,
   type PeachConfig,
 } from '../../src/config'
+import {
+  desktopHostDelivery,
+  desktopHostPlatform,
+  headlessHostCommand,
+} from '../../src/desktop-host-delivery'
 import {
   resolveConnectionInput,
   type ResolvedDevBundle,
 } from '../../src/dev-bundle-resolution'
 import { readProjectDotEnv } from '../../src/dot-env'
+import { awaitStampedExpoSwiftReady } from '../../src/expo-swift-ready'
 import { flowTimeoutScale } from '../../src/flow-timeout-scale'
 import {
   isDaemonLockfileFresh,
   isDevBridgeLockfileFresh,
+  PEACH_HOME_ENV,
   readActiveRuntime,
   readDaemonLockfile,
   readDevBridgeLockfiles,
   readLiveRuntimeVersions,
   readSimulatorDriverPreference,
+  rnxHomeDir,
   runtimeDir,
   runtimesDir,
 } from '../../src/home-paths'
 import { projectLoopbackUrl } from '../../src/host/loopback-ports'
-import { stageHostFile } from '../../src/host/staged-host-files'
+import {
+  isStagedHostFileRequest,
+  stageHostBytes,
+  stageHostFile,
+  stageHostLaunchMetadata,
+} from '../../src/host/staged-host-files'
 import { readInstalledNativePackageVersions } from '../../src/installed-package-versions'
+import { LAUNCH_METADATA_QUERY_PARAM } from '../../src/launchMetadataContract'
 import { detectBundleModeFromText } from '../../src/metro-production-bundle'
 import {
   canExtractNativeAppIdentity,
@@ -96,10 +111,11 @@ import {
   readCurrentSimId,
   saveCurrentSimId,
 } from '../current-sim'
+import { findDesktopCompanion, nativeDesktopIsDefault } from '../desktop-companion'
 import { validateDeviceOption } from '../device-option'
 import { getDriver } from '../drivers/registry'
 import { isTeamMachineSession, openUrl as openUrlInBrowser } from '../open-url'
-import { diagnosticsAllowedForCurrentProcess } from '../privacy'
+import { diagnosticsAllowedForCurrentProcess, isCi } from '../privacy'
 import { rethrowIfExit, peachExit } from '../run-rnx'
 import { collectRuntimeDiagnostics } from '../runtime-diagnostics'
 import { rnxSelfInvocation } from '../self-invocation'
@@ -117,8 +133,8 @@ import {
 } from '../ws-bridge'
 import { readNativeProjectRenderer } from './detect'
 import { inspectDescribe, inspectReadySnapshot, waitReadyReason } from './inspect/core'
-import { isAgentEnv } from './inspect/env'
 import { waitForSimReady } from './inspect/shared'
+import { runInstallDesktop } from './install-desktop'
 import { hasInstalledPeachSkills } from './skills'
 import type { DriverId, DriverLaunchResult } from '../drivers/types'
 
@@ -146,8 +162,13 @@ interface DriverConnectWaitOptions {
 const DEFAULT_DRIVER_CONNECT_TIMEOUT_MS = 120_000
 const DRIVER_CONNECT_INTERVAL_MS = 100
 const DRIVER_CONNECT_HOST_GRACE_MS = 5_000
-const OPEN_BRIDGE_SPAWN_TIMEOUT_MS = 10_000
-const OPEN_BRIDGE_RUNTIME_TIMEOUT_MS = 120_000
+// ceiling for a bridge that is alive but never becomes ready. a bridge that
+// exits fails at once and a slow one is judged by its own lockfile and
+// handshake, so this is not the expected startup time.
+const OPEN_BRIDGE_SPAWN_TIMEOUT_MS = 60_000
+const OPEN_BRIDGE_RUNTIME_TIMEOUT_MS = 600_000
+const OPEN_BRIDGE_HEALTH_TIMEOUT_MS = 10_000
+const OPEN_BRIDGE_SILENCE_MS = 30_000
 // a closed port refuses at once, so this window only matters when something
 // listens: a live bridge on a loaded machine can take longer than 250 ms to
 // finish the handshake, and missing it spawned a second bridge or reported a
@@ -191,9 +212,19 @@ function isDriverId(value: string): value is DriverId {
   return value === 'desktop' || value === 'electron' || value === 'playwright'
 }
 
-function simUsesDriver(sim: BridgeSimInfo, driverId: DriverId): boolean {
+function simUsesDriver(
+  sim: BridgeSimInfo,
+  driverId: DriverId,
+  renderer?: 'chromium' | 'native',
+  hostExecutable?: string | null,
+): boolean {
   if (driverId === 'playwright') {
-    return sim.meta?.sootsimHostDriver === 'playwright'
+    return (
+      sim.meta?.sootsimHostDriver === 'playwright' &&
+      (!renderer || sim.meta?.peachRenderer === renderer) &&
+      (hostExecutable === undefined ||
+        (hostExecutable !== null && sim.meta?.peachHostExecutable === hostExecutable))
+    )
   }
   if (driverId === 'desktop') {
     return Boolean(
@@ -230,11 +261,21 @@ function normalizeKnownTarget(target: string): string {
   return target.trim()
 }
 
+type BridgeOpenGate = {
+  newShell: boolean
+  simId?: string
+  simIdSource?: 'flag' | 'saved' | 'none'
+  driverId?: DriverId
+  renderer?: 'chromium' | 'native'
+  pinnedHostExecutable?: string | null
+}
+
 export async function ensureBridgeForOpen(
   preferredPort: number,
   explicitPort = false,
   resources?: OpenCommandResources,
   runtimeSource: 'bridge' | 'external' = 'bridge',
+  gate: BridgeOpenGate = { newShell: true },
 ): Promise<number> {
   const port = await connectBridgeForOpen(
     preferredPort,
@@ -243,22 +284,107 @@ export async function ensureBridgeForOpen(
     runtimeSource,
   )
   // a bridge accepts connections while its first runtime download is still
-  // running, and every shell page answers 503 until that finishes.
+  // running, and a shell page served by that bridge answers 503 until the
+  // runtime directory exists. a registered page is not that runtime: --new
+  // would hand the driver the 503 url. skip the wait only when this open
+  // will reuse a page whose origin already answers. a new shell waits until
+  // the bridge install settles or the shell itself answers, and does not
+  // start a second install over the one already in flight.
   if (runtimeSource === 'bridge') {
-    await waitForBridgeRuntime(port)
-    await ensureRuntimeForOpen()
+    const reusingReadyOrigin =
+      !gate.newShell && (await provenReadyReuseOrigin(port, gate))
+    if (!reusingReadyOrigin) {
+      const readiness = await waitForBridgeRuntime(port)
+      if (readiness === 'settled') await ensureRuntimeForOpen()
+    }
   }
   return port
 }
 
-async function waitForBridgeRuntime(port: number) {
+async function provenReadyReuseOrigin(
+  port: number,
+  gate: BridgeOpenGate,
+): Promise<boolean> {
+  if (!gate.driverId || !gate.simId || gate.simIdSource === 'none' || !gate.simIdSource) {
+    return false
+  }
+  const bridge = createBridge(port, { commandTimeoutMs: 2_000 })
+  try {
+    const sims = await bridge.listSims()
+    const sim = sims.find((candidate) => candidate.id === gate.simId)
+    if (!sim?.url || sim.readyState !== 'open') return false
+    if (
+      !simUsesDriver(
+        sim,
+        gate.driverId,
+        gate.renderer,
+        gate.pinnedHostExecutable ?? undefined,
+      )
+    ) {
+      return false
+    }
+    return await originServesShell(sim.url)
+  } catch {
+    return false
+  } finally {
+    bridge.close()
+  }
+}
+
+async function originServesShell(pageOrOrigin: string): Promise<boolean> {
+  try {
+    const origin = new URL(pageOrOrigin).origin
+    const res = await fetch(origin, { signal: AbortSignal.timeout(2_000) })
+    return res.status !== 503
+  } catch {
+    return false
+  }
+}
+
+// the install runs inside the bridge and reports completion through
+// /healthz. a bridge that answers is installing, so only a bridge that is gone
+// (connection refused) or silent for a while fails the wait; the ceiling only
+// bounds an install that never finishes.
+function portRefusesConnections(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let refused = false
+    const socket = net.connect(port, '127.0.0.1')
+    socket.setTimeout(OPEN_BRIDGE_HEALTH_TIMEOUT_MS, () => socket.destroy())
+    socket.once('connect', () => socket.destroy())
+    socket.once('close', () => resolve(refused))
+    socket.once('error', (err: NodeJS.ErrnoException) => {
+      refused = err.code === 'ECONNREFUSED'
+    })
+  })
+}
+
+async function waitForBridgeRuntime(port: number): Promise<'settled' | 'serving'> {
   const deadline = Date.now() + OPEN_BRIDGE_RUNTIME_TIMEOUT_MS
+  let lastAnswerAt = Date.now()
   while (Date.now() < deadline) {
     try {
-      const res = await fetch(`http://127.0.0.1:${port}/healthz`)
+      const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
+        signal: AbortSignal.timeout(OPEN_BRIDGE_HEALTH_TIMEOUT_MS),
+      })
       const health = (await res.json()) as { bootstrapping?: boolean }
-      if (!health.bootstrapping) return
-    } catch {}
+      if (!health.bootstrapping) return 'settled'
+      lastAnswerAt = Date.now()
+      // the install flag can stay true after the shell directory is already
+      // being served. a new page can use that origin, and installing again
+      // would race the download still in flight.
+      if (await originServesShell(`http://127.0.0.1:${port}/`)) return 'serving'
+    } catch {
+      if (await portRefusesConnections(port)) {
+        throw new Error(
+          `peach bridge on port ${port} exited while installing its runtime`,
+        )
+      }
+      if (Date.now() - lastAnswerAt > OPEN_BRIDGE_SILENCE_MS) {
+        throw new Error(
+          `peach bridge on port ${port} stopped answering for ${Math.round(OPEN_BRIDGE_SILENCE_MS / 1000)}s while installing its runtime`,
+        )
+      }
+    }
     await sleep(150)
   }
   throw new Error(
@@ -272,15 +398,18 @@ async function connectBridgeForOpen(
   resources: OpenCommandResources | undefined,
   runtimeSource: 'bridge' | 'external',
 ): Promise<number> {
+  isolateHomeForExplicitPort(preferredPort, explicitPort, readDaemonLockfile())
   const lock = readDaemonLockfile()
-  assertExplicitBridgeLock(preferredPort, explicitPort, lock)
   const preferredWorld = worldForBridgePort(preferredPort)
-  const handshake = await bridgeHandshake(preferredPort, LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS)
+  const handshakeTimeoutMs = LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS * flowTimeoutScale()
+  const handshake = await bridgeHandshake(preferredPort, handshakeTimeoutMs)
   if ((explicitPort || preferredWorld !== null) && handshake === 'open') {
     return preferredPort
   }
   if (explicitPort && preferredWorld !== null) {
-    throw new Error(unreachableBridgeMessage(preferredPort, handshake))
+    throw new Error(
+      unreachableBridgeMessage(preferredPort, handshake, handshakeTimeoutMs),
+    )
   }
   if (
     !explicitPort &&
@@ -288,7 +417,7 @@ async function connectBridgeForOpen(
     isDaemonLockfileFresh(lock) &&
     (lock.bridgePort === preferredPort
       ? handshake === 'open'
-      : await canConnectToBridge(lock.bridgePort, LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS))
+      : await canConnectToBridge(lock.bridgePort, handshakeTimeoutMs))
   ) {
     return lock.bridgePort
   }
@@ -331,8 +460,10 @@ async function connectBridgeForOpen(
     resources.port = preferredPort
   }
   let childExit: string | null = null
+  const exited = new AbortController()
   child.once('exit', (code, signal) => {
     childExit = String(code ?? signal ?? 'unknown')
+    exited.abort()
   })
   child.unref()
 
@@ -355,11 +486,18 @@ async function connectBridgeForOpen(
       )
     }
     const selectedPort = explicitPort ? preferredPort : nextLock?.bridgePort
+    // ready is the spawned bridge's own lockfile plus a completed handshake. a
+    // loaded machine needs the full handshake budget, not a 250ms probe.
     if (
       nextLock &&
+      nextLock.pid === child.pid &&
       isDaemonLockfileFresh(nextLock) &&
       selectedPort !== undefined &&
-      (await canConnectToBridge(selectedPort, 250))
+      (await canConnectToBridge(
+        selectedPort,
+        Math.max(1, Math.min(handshakeTimeoutMs, deadline - Date.now())),
+        exited.signal,
+      ))
     ) {
       console.error(
         `  Started a local bridge on port ${selectedPort}. Run \`peach daemon install\` to keep it ready between commands.`,
@@ -371,7 +509,7 @@ async function connectBridgeForOpen(
       return selectedPort
     }
     if (childExit) break
-    await sleep(150)
+    await sleep(Math.max(0, Math.min(150, deadline - Date.now())))
   }
 
   const reason = childExit
@@ -383,7 +521,10 @@ async function connectBridgeForOpen(
   )
 }
 
-function assertExplicitBridgeLock(
+// one bridge per peach home, so an explicit port the active daemon does not own
+// gets its own home: this command and the bridge it starts both run in it,
+// sharing the daemon's installed runtimes.
+function isolateHomeForExplicitPort(
   preferredPort: number,
   explicitPort: boolean,
   lock: ReturnType<typeof readDaemonLockfile>,
@@ -404,9 +545,14 @@ function assertExplicitBridgeLock(
   ) {
     return
   }
-  throw new Error(
-    `${rnxPublicBrand.commandName} open: requested bridge port ${preferredPort}, but the active daemon owns port ${lock.bridgePort}. explicit --port never selects another bridge; stop that daemon or use an isolated PEACH_HOME.`,
-  )
+  const sharedRuntimes = runtimesDir()
+  const home = path.join(rnxHomeDir(), 'port-homes', String(preferredPort))
+  fs.mkdirSync(home, { recursive: true })
+  const runtimes = path.join(home, 'runtimes')
+  if (fs.existsSync(sharedRuntimes) && !fs.existsSync(runtimes)) {
+    fs.symlinkSync(sharedRuntimes, runtimes)
+  }
+  process.env[PEACH_HOME_ENV] = home
 }
 
 async function ensureRuntimeForOpen() {
@@ -430,7 +576,11 @@ async function ensureRuntimeForOpen() {
 
 type BridgeHandshake = 'open' | 'refused' | 'timeout'
 
-function bridgeHandshake(port: number, timeoutMs: number): Promise<BridgeHandshake> {
+function bridgeHandshake(
+  port: number,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<BridgeHandshake> {
   return new Promise((resolve) => {
     const ws = new WebSocket(`ws://127.0.0.1:${port}`, { handshakeTimeout: timeoutMs })
     let settled = false
@@ -438,11 +588,15 @@ function bridgeHandshake(port: number, timeoutMs: number): Promise<BridgeHandsha
       if (settled) return
       settled = true
       clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
       if (ws.readyState === WebSocket.OPEN) ws.close()
       else if (ws.readyState === WebSocket.CONNECTING) ws.terminate()
       resolve(result)
     }
     const timer = setTimeout(() => finish('timeout'), timeoutMs)
+    const onAbort = () => finish('timeout')
+    if (signal?.aborted) onAbort()
+    else signal?.addEventListener('abort', onAbort)
     ws.once('open', () => finish('open'))
     ws.on('error', (err: NodeJS.ErrnoException) => {
       finish(
@@ -452,19 +606,27 @@ function bridgeHandshake(port: number, timeoutMs: number): Promise<BridgeHandsha
   })
 }
 
-function unreachableBridgeMessage(port: number, handshake: BridgeHandshake): string {
+function unreachableBridgeMessage(
+  port: number,
+  handshake: BridgeHandshake,
+  timeoutMs: number,
+): string {
   if (handshake === 'timeout') {
     const cores = Math.max(1, os.cpus().length)
     const load = os.loadavg()[0]
     if (load >= cores) {
-      return `peach open: requested bridge port ${port} did not finish its handshake within 2s while load average was ${load.toFixed(1)} on ${cores} cores.`
+      return `peach open: requested bridge port ${port} did not finish its handshake within ${timeoutMs / 1000}s while load average was ${load.toFixed(1)} on ${cores} cores.`
     }
   }
   return `peach open: requested bridge port ${port} is not reachable.`
 }
 
-function canConnectToBridge(port: number, timeoutMs: number): Promise<boolean> {
-  return bridgeHandshake(port, timeoutMs).then((result) => result === 'open')
+function canConnectToBridge(
+  port: number,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  return bridgeHandshake(port, timeoutMs, signal).then((result) => result === 'open')
 }
 
 function looksLikeSootsimUrl(target: string): boolean {
@@ -585,11 +747,12 @@ async function resolveConnectionInputForCli(target: string): Promise<ResolvedDev
   const releaseListenerScan = pinSharedListenerScan()
   try {
     for (let attempt = 0; attempt < DEV_BUNDLE_RESOLVE_ATTEMPTS; attempt++) {
+      let resolutionTarget = normalized
       if (registeredPort && registeredPort > 0) {
         const discovered = await probePort(registeredPort)
         // a provisional bundle URL is enough to LIST the server but not to open
-        // it; fall through to resolveConnectionInput, which asks the manifest
-        // again with a budget that fits a real dev server.
+        // it; resolveConnectionInput joins the scanner's pending manifest with
+        // the full startup budget instead of starting the same work again.
         if (discovered && !discovered.bundleUrlProvisional) {
           return {
             bundleUrl: projectLoopbackUrl(discovered.bundleUrl),
@@ -598,10 +761,15 @@ async function resolveConnectionInputForCli(target: string): Promise<ResolvedDev
             projectName: discovered.projectName,
           }
         }
+        // keep the scanner's answering address and join its manifest request.
+        // probing both loopback families again duplicates cold config work.
+        if (discovered?.bundleUrlProvisional && /^\d+$/.test(normalized)) {
+          resolutionTarget = new URL(discovered.bundleUrl).origin
+        }
       }
 
       try {
-        const resolved = await resolveConnectionInput(normalized)
+        const resolved = await resolveConnectionInput(resolutionTarget)
         return { ...resolved, bundleUrl: projectLoopbackUrl(resolved.bundleUrl) }
       } catch (error) {
         if (
@@ -850,7 +1018,7 @@ export function resolveShellBaseUrlForBridgePort(bridgePort: number): string {
   )
 }
 
-// stamp the engine page url with `?appFonts=<url[::family]>,...` so the
+// stamp a bounded catalog reference on the engine page url so the
 // engine's app-font-loader registers native config-only fonts at boot. fonts
 // loaded by JS already flow through normal runtime fetch capture; this covers
 // UIAppFonts-style assets that Metro can serve but the guest bundle never
@@ -865,16 +1033,18 @@ function stampAppFonts(
 ): string {
   try {
     const url = new URL(urlStr)
-    const bundleUrl = url.searchParams.get('bundle') || ''
-    if (!bundleUrl || !project) return urlStr
+    if (!url.searchParams.get('bundle') || !project) return urlStr
     const specs = discoverNativeLinkedAppFonts({
-      bundleUrl,
       projectDir: project.appDir,
       platform,
       nativeAssetOrigin,
     })
     if (specs.length === 0) return urlStr
-    url.searchParams.set('appFonts', encodeAppFontsWire(specs))
+    const catalogUrl = stageHostBytes(
+      new TextEncoder().encode(encodeAppFontsWire(specs)),
+      nativeAssetOrigin,
+    )
+    url.searchParams.set('appFonts', `@${catalogUrl}`)
     return url.toString()
   } catch {
     return urlStr
@@ -1012,6 +1182,10 @@ export interface BuildShellUrlOptions {
   // after the app path lands inside the bundle param and never reaches the
   // shell. non-foldable devices resolve it to closed at boot.
   posture?: string
+  // raster quality (high|medium|low) stamped as ?renderResolution=. high
+  // renders at the device's native scale, so a native-parity capture is not
+  // left at the interactive medium default of 2.
+  renderResolution?: string
   // interface orientation (portrait|landscape) stamped as ?orientation=,
   // which the shell reads at boot over the device's default: an open duo
   // boots landscape unless this asks for it upright.
@@ -1059,45 +1233,74 @@ export interface BuildShellUrlOptions {
   bridgePort?: number
 }
 
-function readProjectNativeFirebaseConfig(
+type ProjectExpoConfigRead = { config: Record<string, unknown> } | { error: string }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function readProjectExpoConfig(
   project: ResolvedAppProject,
-): Promise<Record<string, unknown> | null> {
+): Promise<ProjectExpoConfigRead | null> {
   const require = createRequire(path.join(project.appDir, 'package.json'))
   try {
     require.resolve('@expo/config')
   } catch {
     return Promise.resolve(null)
   }
-  return readExpoConfigAsync(project.appDir)
-    .then((config) =>
-      readNativeFirebaseConfig(project.appDir, undefined, undefined, config),
-    )
-    .catch((error: unknown) => ({
-      error: error instanceof Error ? error.message : String(error),
-    }))
+  return readExpoConfigAsync(project.appDir).then(
+    (config) => ({ config }),
+    (error: unknown) => ({ error: errorMessage(error) }),
+  )
 }
 
 // evaluating the Expo config spawns node, so `peach open` starts the read as
 // soon as the project resolves and the shell url it builds takes that read. a
 // later build reads the config again.
-const startedNativeFirebaseConfigs = new Map<
-  string,
-  Promise<Record<string, unknown> | null>
->()
-
-function startNativeFirebaseConfigRead(project: ResolvedAppProject | null) {
-  if (project)
-    startedNativeFirebaseConfigs.set(
-      project.appDir,
-      readProjectNativeFirebaseConfig(project),
-    )
+const startedExpoConfigReads = new Map<string, Promise<ProjectExpoConfigRead | null>>()
+
+function startExpoConfigRead(project: ResolvedAppProject | null) {
+  if (project) startedExpoConfigReads.set(project.appDir, readProjectExpoConfig(project))
 }
 
-function takeNativeFirebaseConfig(project: ResolvedAppProject | null | undefined) {
+function takeExpoConfigRead(project: ResolvedAppProject | null | undefined) {
   if (!project) return Promise.resolve(null)
-  const started = startedNativeFirebaseConfigs.get(project.appDir)
-  startedNativeFirebaseConfigs.delete(project.appDir)
-  return started ?? readProjectNativeFirebaseConfig(project)
+  const started = startedExpoConfigReads.get(project.appDir)
+  startedExpoConfigReads.delete(project.appDir)
+  return started ?? readProjectExpoConfig(project)
+}
+
+function nativeFirebaseFromExpoConfig(
+  project: ResolvedAppProject,
+  read: ProjectExpoConfigRead,
+): Record<string, unknown> {
+  if ('error' in read) return read
+  try {
+    return readNativeFirebaseConfig(project.appDir, undefined, undefined, read.config)
+  } catch (error) {
+    return { error: errorMessage(error) }
+  }
+}
+
+// a built bundle staged on the bridge has no packager to serve its manifest.
+// the built binary embeds its evaluated app config (expo's `app.config`
+// resource, and the Info.plist prebuild writes from it), so the bundle's
+// manifest is that config, staged beside it
+function stageBuiltBundleManifest(
+  bundleUrl: string,
+  config: Record<string, unknown>,
+): string | null {
+  const bundle = new URL(bundleUrl)
+  if (!isStagedHostFileRequest(bundle.pathname) || Object.keys(config).length === 0)
+    return null
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'peach-app-manifest-'))
+  try {
+    const file = path.join(directory, 'manifest.json')
+    fs.writeFileSync(file, JSON.stringify({ extra: { expoClient: config } }))
+    return stageHostFile(file, bundle.origin)
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true })
+  }
 }
 
 // a plain Metro carries no identity footer or header, so the page carries the
@@ -1200,6 +1403,7 @@ export async function buildShellUrl(
   // own `@expo/config` (a dependency-free recorder) leaves it to the Peach
   // Metro plugin's endpoint.
   expoStamped.searchParams.delete('nativeFirebase')
+  expoStamped.searchParams.delete('appManifest')
   expoStamped.searchParams.delete('packageVersions')
   if (project && expoStamped.searchParams.get('bundle')) {
     expoStamped.searchParams.set(
@@ -1207,9 +1411,25 @@ export async function buildShellUrl(
       JSON.stringify(readInstalledNativePackageVersions(project.appDir)),
     )
   }
-  const nativeFirebase = await takeNativeFirebaseConfig(project)
-  if (nativeFirebase && expoStamped.searchParams.get('bundle'))
-    expoStamped.searchParams.set('nativeFirebase', JSON.stringify(nativeFirebase))
+  const expoConfigRead = await takeExpoConfigRead(project)
+  const stampedBundle = expoStamped.searchParams.get('bundle')
+  if (project && !expoConfigRead && stampedBundle) {
+    // no Expo config tooling, but the native project still configures Firebase
+    const nativeFirebase = nativeFirebaseFromExpoConfig(project, { config: {} })
+    if (Object.keys(nativeFirebase).length > 0)
+      expoStamped.searchParams.set('nativeFirebase', JSON.stringify(nativeFirebase))
+  }
+  if (project && expoConfigRead && stampedBundle) {
+    expoStamped.searchParams.set(
+      'nativeFirebase',
+      JSON.stringify(nativeFirebaseFromExpoConfig(project, expoConfigRead)),
+    )
+    const manifest =
+      'config' in expoConfigRead
+        ? stageBuiltBundleManifest(stampedBundle, expoConfigRead.config)
+        : null
+    if (manifest) expoStamped.searchParams.set('appManifest', manifest)
+  }
   if (opts.bundleOriginOverride)
     expoStamped.searchParams.set('bundleOriginOverride', opts.bundleOriginOverride)
   if (opts.hostDriver) expoStamped.searchParams.set('peachHostDriver', opts.hostDriver)
@@ -1229,24 +1449,27 @@ export async function buildShellUrl(
     !opts.proof &&
     !opts.ephemeral &&
     !opts.posture &&
+    !opts.renderResolution &&
     !opts.orientation &&
     !opts.osVersion &&
     !opts.theme &&
     !opts.env?.length &&
     !opts.dotEnv
   )
-    return expoStamped.toString()
+    return stageHostLaunchMetadata(expoStamped, `http://localhost:${port.port}`)
   const url = expoStamped
   if (opts.dotEnv) url.searchParams.set('dotEnv', JSON.stringify(opts.dotEnv))
   if (opts.device) url.searchParams.set('device', opts.device)
   if (opts.posture) url.searchParams.set('posture', opts.posture)
+  if (opts.renderResolution)
+    url.searchParams.set('renderResolution', opts.renderResolution)
   if (opts.orientation) url.searchParams.set('orientation', opts.orientation)
   if (opts.osVersion) url.searchParams.set('osVersion', opts.osVersion)
   if (opts.theme) url.searchParams.set('theme', opts.theme)
   if (opts.proof) url.searchParams.set('proof', '1')
   if (opts.ephemeral) url.searchParams.set('ephemeral', '1')
   for (const entry of opts.env ?? []) url.searchParams.append('env', entry)
-  return url.toString()
+  return stageHostLaunchMetadata(url, `http://localhost:${port.port}`)
 }
 
 function deriveCurrentSimBaseUrl(
@@ -1278,6 +1501,7 @@ function deriveCurrentSimBaseUrl(
     url.searchParams.delete('nativeFirebase')
     url.searchParams.delete('packageVersions')
     url.searchParams.delete('nativeAppIdentity')
+    url.searchParams.delete(LAUNCH_METADATA_QUERY_PARAM)
     url.searchParams.delete('expoSwift')
     url.searchParams.delete('expoKotlin')
     return url.toString()
@@ -1331,13 +1555,27 @@ export async function waitForSimMatchOrHostExit(
   commandTimeoutMs: number,
   predicate: (sim: BridgeSimInfo) => boolean,
   hostPid: number | undefined,
-  opts: { attempts?: number; intervalMs?: number; signal?: AbortSignal } = {},
+  opts: {
+    attempts?: number
+    intervalMs?: number
+    signal?: AbortSignal
+    admittedFile?: string
+  } = {},
 ): Promise<WaitForSimMatchOrHostExitResult> {
   const attempts = opts.attempts ?? 30
   const intervalMs = opts.intervalMs ?? 500
   const watchHost = !!hostPid && Number.isInteger(hostPid) && hostPid > 1
   const hostExited = () =>
     watchHost && hostPid !== undefined && !isProcessRunning(hostPid)
+  // a host queued behind the machine's browser cap has not started its connect
+  // budget, so neither does this wait; the caller's signal still bounds it.
+  if (opts.admittedFile && watchHost) {
+    while (!fs.existsSync(opts.admittedFile)) {
+      opts.signal?.throwIfAborted()
+      if (hostExited()) return { kind: 'host-exit' }
+      await sleep(intervalMs)
+    }
+  }
   for (let i = 0; i < attempts; i++) {
     opts.signal?.throwIfAborted()
     if (hostExited()) {
@@ -1745,6 +1983,7 @@ export async function runOpenCommand(
     stripBooleanFlags: [
       '--new',
       '--headless',
+      '--chromium',
       '--headed',
       '--ephemeral',
       '--hot',
@@ -1764,6 +2003,7 @@ export async function runOpenCommand(
       '--cdp-port',
       '--device',
       '--posture',
+      '--render-resolution',
       '--orientation',
       '--os-version',
       '--ios-target',
@@ -1836,7 +2076,9 @@ export async function runOpenCommand(
     peachExit(1)
   }
 
-  if (isAppDeepLinkTarget(target)) {
+  // an absolute path to a built bundle is a file, not an app path
+  const prebuiltBundle = prebuiltBundleFile(target)
+  if (!prebuiltBundle && isAppDeepLinkTarget(target)) {
     if (openInNewSim) {
       console.error(
         '  peach open: deep links target the current app; remove --new, --profile, or --ephemeral',
@@ -1879,7 +2121,6 @@ export async function runOpenCommand(
     return
   }
 
-  const prebuiltBundle = prebuiltBundleFile(target)
   // a bundle file gets its url once the bridge that serves it is settled
   let resolvedBundle =
     !prebuiltBundle && shouldResolveBundleTargetInCli(target)
@@ -1895,7 +2136,7 @@ export async function runOpenCommand(
     resolvedBundle?.bundleUrl,
     projectRoot ?? (prebuiltBundle ? appDirAbove(prebuiltBundle) : undefined),
   )
-  startNativeFirebaseConfigRead(project)
+  startExpoConfigRead(project)
   // playwright is the browser-sim launcher. it owns an isolated profile and
   // can reap exactly its own browser tree. desktop opens the native host and
   // electron the Electron companion. none opens the user's browser profile.
@@ -1906,25 +2147,49 @@ export async function runOpenCommand(
     )
     peachExit(1)
   }
-  const driverId: DriverId = isDriverId(requestedDriverId)
-    ? requestedDriverId === 'electron' && process.platform !== 'win32'
-      ? 'desktop'
-      : requestedDriverId
-    : process.env.CI === '1' ||
-        process.env.CI === 'true' ||
-        process.env.GITHUB_ACTIONS === 'true' ||
-        isTeamMachineSession() ||
-        isAgentEnv() ||
-        !process.stdin.isTTY
+  // a person watching the sim, directly or through their coding agent, gets the
+  // native app where it ships. CI and Team Machine fleet sessions stay in the
+  // headless browser, as do the browser-only --headless and --chromium.
+  const defaultDriverId: DriverId =
+    isCi() ||
+    isTeamMachineSession() ||
+    args.includes('--headless') ||
+    args.includes('--chromium')
       ? 'playwright'
-      : readSimulatorDriverPreference() === 'electron' && process.platform !== 'win32'
-        ? 'desktop'
-        : readSimulatorDriverPreference() || 'playwright'
+      : (readSimulatorDriverPreference() ??
+        (nativeDesktopIsDefault() ? 'desktop' : 'playwright'))
+  const selectedDriverId = isDriverId(requestedDriverId)
+    ? requestedDriverId
+    : defaultDriverId
+  const driverId: DriverId =
+    selectedDriverId === 'electron' && process.platform !== 'win32'
+      ? 'desktop'
+      : selectedDriverId
   if (requestedDriverId === 'electron' && driverId === 'desktop')
     console.error(
       '  Electron is Windows-only; using the native desktop app (peach desktop install).',
     )
+  // the first open on a machine without the native app installs it.
+  if (driverId === 'desktop' && !findDesktopCompanion())
+    await runInstallDesktop(['--yes'])
   const driverHeadless = resolveDriverHeadless(args, driverId)
+  const chromium = args.includes('--chromium')
+  if (chromium && driverId !== 'playwright') {
+    console.error('  peach open: --chromium requires the playwright driver')
+    peachExit(1)
+  }
+  const renderer = chromium
+    ? 'chromium'
+    : driverHeadless && desktopHostPlatform() === 'linux-x64'
+      ? 'native'
+      : undefined
+  const pinnedHostExecutable =
+    !chromium &&
+    driverHeadless &&
+    desktopHostPlatform() === 'linux-x64' &&
+    desktopHostDelivery().resolvePin()
+      ? (headlessHostCommand()?.[0] ?? null)
+      : undefined
   if (cdpPort && driverId !== 'playwright') {
     console.error('  peach open: --cdp-port is only honored by the playwright driver')
     peachExit(1)
@@ -2006,9 +2271,21 @@ export async function runOpenCommand(
     parsed.wsPort,
     parsed.explicitPort,
     opts.resources,
-    !configuredRuntimeVersion && (explicitBaseUrl || looksLikeSootsimUrl(target))
+    !configuredRuntimeVersion &&
+      (explicitBaseUrl ||
+        looksLikeSootsimUrl(target) ||
+        (parsed.explicitPort &&
+          worldForBridgePort(parsed.wsPort)?.source === 'dev-bridge'))
       ? 'external'
       : 'bridge',
+    {
+      newShell: openInNewSim,
+      simId: parsed.simId,
+      simIdSource: parsed.simIdSource,
+      driverId,
+      renderer,
+      pinnedHostExecutable,
+    },
   )
   if (opts.resources) opts.resources.port = parsed.wsPort
   opts.signal?.throwIfAborted()
@@ -2035,6 +2312,18 @@ export async function runOpenCommand(
     console.error(`  peach open: --posture must be open or closed, got "${postureArg}"`)
     peachExit(1)
   }
+  const renderResolutionArg = args.find((_, i) => args[i - 1] === '--render-resolution')
+  if (
+    args.includes('--render-resolution') &&
+    renderResolutionArg !== 'high' &&
+    renderResolutionArg !== 'medium' &&
+    renderResolutionArg !== 'low'
+  ) {
+    console.error(
+      `  peach open: --render-resolution must be high, medium, or low, got "${renderResolutionArg ?? ''}"`,
+    )
+    peachExit(1)
+  }
   const orientationFlag = args.find((_, i) => args[i - 1] === '--orientation')
   const orientationArg =
     orientationFlag === 'portrait' || orientationFlag === 'landscape'
@@ -2131,6 +2420,7 @@ export async function runOpenCommand(
     hostDriver: driverId === 'desktop' ? 'desktop' : undefined,
     device: deviceArg,
     posture: postureArg,
+    renderResolution: renderResolutionArg,
     orientation: orientationArg,
     osVersion: osVersionArg,
     theme: themeArg,
@@ -2185,14 +2475,14 @@ export async function runOpenCommand(
               (sim) =>
                 sim.id === savedSimId &&
                 sim.readyState === 'open' &&
-                simUsesDriver(sim, driverId),
+                simUsesDriver(sim, driverId, renderer, pinnedHostExecutable),
             ) ?? null
           if (!targetSim) {
             clearCurrentSimId()
           }
         } else if (parsed.simIdSource === 'flag') {
           targetSim = resolveTargetSim(sims, parsed.simId)
-          if (!simUsesDriver(targetSim, driverId)) {
+          if (!simUsesDriver(targetSim, driverId, renderer, pinnedHostExecutable)) {
             throw new Error(
               `sim ${targetSim.id} is not managed by the ${driverId} driver`,
             )
@@ -2211,7 +2501,7 @@ export async function runOpenCommand(
               if (
                 sim.readyState !== 'open' ||
                 !sim.url ||
-                !simUsesDriver(sim, driverId)
+                !simUsesDriver(sim, driverId, renderer, pinnedHostExecutable)
               ) {
                 return false
               }
@@ -2279,7 +2569,7 @@ export async function runOpenCommand(
           parsed.commandTimeoutMs,
           (sim) =>
             sim.readyState === 'open' &&
-            simUsesDriver(sim, driverId) &&
+            simUsesDriver(sim, driverId, renderer, pinnedHostExecutable) &&
             simMatchesToken(sim),
           { attempts: Math.round(30 * flowTimeoutScale()) },
         )
@@ -2330,11 +2620,11 @@ export async function runOpenCommand(
   }
 
   const configuredBaseUrl = applyPeachConfigToUrl(baseUrl, runtimeConfig)
-  const openUrl = withOpenToken(
+  const builtShellUrl =
     newSimShellUrl ??
-      (await buildShellUrl(shellTarget, configuredBaseUrl, buildShellUrlOpts)),
-    token,
-  )
+    (await buildShellUrl(shellTarget, configuredBaseUrl, buildShellUrlOpts))
+  await awaitStampedExpoSwiftReady(builtShellUrl)
+  const openUrl = withOpenToken(builtShellUrl, token)
   const ownerPid = opts.ownerPid ?? getStableOwnerPid()
   if (!ownerPid) {
     console.error(
@@ -2359,6 +2649,7 @@ export async function runOpenCommand(
     // live world of its own.
     bridgePort: parsed.wsPort,
     headless: driverHeadless,
+    chromium,
     profileId,
     ephemeralProfile,
     cdpPort,
@@ -2386,6 +2677,7 @@ export async function runOpenCommand(
       attempts: connectWait.attempts,
       intervalMs: connectWait.intervalMs,
       signal: opts.signal,
+      admittedFile: result.admittedFile,
     },
   )
   if (outcome.kind === 'host-exit') {
@@ -2436,6 +2728,13 @@ export async function runOpenCommand(
       simId: match.id,
       simIdSource: 'flag',
     })
+    const attached = await bridge
+      .listSims()
+      .then((sims) => sims.find((sim) => sim.id === match.id)?.readyState ?? 'gone')
+      .catch(() => 'unknown')
+    console.error(
+      `  sim ${match.id} bridge state: ${attached}; host load ${os.loadavg()[0].toFixed(1)} on ${os.cpus().length} cpus (a loaded host slows a cold first bundle past the budget; a sim that is open but never answers has a blocked page)`,
+    )
     await printBridgeFailureDiagnostics(bridge, {
       errorsCommand: `peach get errors 5${hint}`,
       warningsCommand: `peach get warnings 5${hint}`,