peachsim 0.1.527

package/cli/commands/control.ts

@@ -0,0 +1,2154 @@
+import { spawn, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {
+  devices,
+  listSelectableDeviceModels,
+  type DeviceModel,
+} from 'sootsim-engine/settings'
+import { WebSocket } from 'ws'
+import { probePort } from '../../scripts/dev-server-scanner'
+import { isAppDeepLinkTarget, openAppUrl } from '../../src/app-url'
+import { isLoopbackHost } from '../../src/backend-origin'
+import { resolveSootsimShellBaseUrlForBridgePort } from '../../src/bridge-constants'
+import {
+  applyRNXConfigToUrl,
+  mergeRNXConfig,
+  RNX_CONFIG_QUERY_PARAM,
+  type RNXConfig,
+} from '../../src/config'
+import {
+  resolveConnectionInput,
+  type ResolvedDevBundle,
+} from '../../src/dev-bundle-resolution'
+import { flowTimeoutScale } from '../../src/flow-timeout-scale'
+import {
+  isDaemonLockfileFresh,
+  isDevBridgeLockfileFresh,
+  readActiveRuntime,
+  readDaemonLockfile,
+  readDevBridgeLockfiles,
+  readLiveRuntimeVersions,
+  readSimulatorDriverPreference,
+  runtimeDir,
+} from '../../src/home-paths'
+import { applyHotMode } from '../../src/native-dev-bundle-url'
+import { ensureProfile } from '../../src/profiles'
+import { rnxPublicBrand } from '../../src/public-brand'
+import {
+  resolveDevCheckoutRuntimeRoot,
+  runtimeVersionHostname,
+} from '../../src/runtime-assets'
+import { rnxRuntime } from '../../src/runtime-delivery'
+import { loadRNXAppConfig } from '../app-config'
+import {
+  type DiscoveredAppFontSpec,
+  discoverNativeLinkedAppFonts,
+  encodeAppFontsWire,
+  resolveMetroProjectRoot,
+} from '../app-fonts'
+import { resolveAppProject, type ResolvedAppProject } from '../app-project'
+import { discoverConfigPluginAppSplash, encodeAppSplashWire } from '../app-splash'
+import { printBridgeFailureDiagnostics } from '../bridge-diagnostics'
+import {
+  clearCurrentSimId,
+  getStableOwnerPid,
+  readCurrentSimId,
+  saveCurrentSimId,
+} from '../current-sim'
+import { getDriver } from '../drivers/registry'
+import { openUrl as openUrlInBrowser } from '../open-url'
+import { rethrowIfExit, rnxExit } from '../run-rnx'
+import { rnxSelfInvocation } from '../self-invocation'
+import {
+  BridgeSimLockedError,
+  createBridge,
+  createBridgeFromParsed,
+  formatLockOwner,
+  parseBridgeCliArgs,
+  printBridgeWorldNotice,
+  resolveBridgePortForPin,
+  resolveBridgeWorld,
+  worldForBridgePort,
+  type BridgeSimInfo,
+} from '../ws-bridge'
+import { inspectDescribe, inspectWaitReady } from './inspect/core'
+import { isAgentEnv } from './inspect/env'
+import type { DriverId, DriverLaunchResult } from '../drivers/types'
+
+interface ControlCommandOptions {
+  port?: number
+  timeoutMs?: number
+  runtimeConfig?: RNXConfig
+}
+
+interface DriverConnectWaitOptions {
+  attempts: number
+  intervalMs: number
+  timeoutMs: number
+  hostTimeoutMs: number
+}
+
+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
+
+// built-in shell apps use pathname-based routing, not ?bundle= params
+const SHELL_APPS: Record<string, string> = {
+  rn: '/rn',
+  connectrn: '/rn',
+  'connect-rn': '/rn',
+  clock: '/app/clock',
+  'native-ui': '/app/native-ui',
+  tamagui: '/app/tamagui',
+  settings: '/app/settings',
+  photos: '/app/photos',
+  camera: '/app/camera',
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function parsePositiveIntegerEnv(name: string): number | null {
+  const value = process.env[name]?.trim()
+  if (!value) return null
+  const parsed = Number(value)
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null
+}
+
+export function resolveDriverConnectWaitOptions(): DriverConnectWaitOptions {
+  const timeoutMs =
+    parsePositiveIntegerEnv('SOOTSIM_DRIVER_CONNECT_TIMEOUT_MS') ??
+    parsePositiveIntegerEnv('SOOTSIM_PW_CONNECT_TIMEOUT_MS') ??
+    DEFAULT_DRIVER_CONNECT_TIMEOUT_MS
+  return {
+    timeoutMs,
+    hostTimeoutMs: timeoutMs + DRIVER_CONNECT_HOST_GRACE_MS,
+    intervalMs: DRIVER_CONNECT_INTERVAL_MS,
+    attempts: Math.max(1, Math.ceil(timeoutMs / DRIVER_CONNECT_INTERVAL_MS)),
+  }
+}
+
+function isDriverId(value: string): value is DriverId {
+  return value === 'electron' || value === 'playwright'
+}
+
+function simUsesDriver(sim: BridgeSimInfo, driverId: DriverId): boolean {
+  if (driverId === 'playwright') {
+    return sim.meta?.sootsimHostDriver === 'playwright'
+  }
+  return sim.userAgent?.includes('Electron/') === true
+}
+
+// resolve headless for a driver launch. explicit flags always win
+// (--headless → true, --headed → false). otherwise: a headed default
+// on mac/windows. on linux with no DISPLAY/WAYLAND_DISPLAY there is no
+// X server, so the playwright driver auto-flips to headless with a
+// single-line note. electron ignores headless mode, so it defaults false.
+function resolveDriverHeadless(args: string[], driverId: string): boolean {
+  if (args.includes('--headless')) return true
+  if (args.includes('--headed')) return false
+  if (
+    driverId === 'playwright' &&
+    process.platform === 'linux' &&
+    !process.env.DISPLAY &&
+    !process.env.WAYLAND_DISPLAY
+  ) {
+    console.error(
+      '  no display detected → running playwright headless (override with --headed)',
+    )
+    return true
+  }
+  return false
+}
+
+function normalizeKnownTarget(target: string): string {
+  return target.trim()
+}
+
+export async function ensureBridgeForOpen(
+  preferredPort: number,
+  explicitPort = false,
+): Promise<number> {
+  const lock = readDaemonLockfile()
+  assertExplicitBridgeLock(preferredPort, explicitPort, lock)
+  const preferredWorld = worldForBridgePort(preferredPort)
+  if (
+    (explicitPort || preferredWorld !== null) &&
+    (await canConnectToBridge(preferredPort, 250))
+  ) {
+    return preferredPort
+  }
+  if (explicitPort && preferredWorld !== null) {
+    throw new Error(`rnx open: requested bridge port ${preferredPort} is not reachable.`)
+  }
+  if (
+    !explicitPort &&
+    lock &&
+    isDaemonLockfileFresh(lock) &&
+    (await canConnectToBridge(lock.bridgePort, 500))
+  ) {
+    return lock.bridgePort
+  }
+  if (lock && isDaemonLockfileFresh(lock)) {
+    throw new Error(
+      `rnx bridge lockfile is fresh (port ${lock.bridgePort}) but the bridge is not reachable. run \`rnx daemon restart\` or \`rnx daemon uninstall\`.`,
+    )
+  }
+
+  await ensureRuntimeForOpen()
+  const child = spawnSootsim(['serve', '--quiet', '--port', String(preferredPort)])
+  let childExit: string | null = null
+  child.once('exit', (code, signal) => {
+    childExit = String(code ?? signal ?? 'unknown')
+  })
+  child.unref()
+
+  const deadline = Date.now() + OPEN_BRIDGE_SPAWN_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    const nextLock = readDaemonLockfile()
+    assertExplicitBridgeLock(preferredPort, explicitPort, nextLock)
+    const selectedPort = explicitPort ? preferredPort : nextLock?.bridgePort
+    if (
+      nextLock &&
+      isDaemonLockfileFresh(nextLock) &&
+      selectedPort !== undefined &&
+      (await canConnectToBridge(selectedPort, 250))
+    ) {
+      console.error(
+        `  Started a local bridge on port ${selectedPort}. Run \`rnx daemon install\` to keep it ready between commands.`,
+      )
+      return selectedPort
+    }
+    if (childExit) {
+      throw new Error(`rnx bridge exited before becoming ready (exit ${childExit})`)
+    }
+    await sleep(150)
+  }
+
+  throw new Error(
+    `rnx bridge did not start within ${Math.round(OPEN_BRIDGE_SPAWN_TIMEOUT_MS / 1000)}s`,
+  )
+}
+
+function assertExplicitBridgeLock(
+  preferredPort: number,
+  explicitPort: boolean,
+  lock: ReturnType<typeof readDaemonLockfile>,
+): void {
+  if (
+    !explicitPort ||
+    !lock ||
+    !isDaemonLockfileFresh(lock) ||
+    lock.bridgePort === preferredPort
+  ) {
+    return
+  }
+  if (
+    readDevBridgeLockfiles().some(
+      (devBridge) =>
+        devBridge.bridgePort === preferredPort && isDevBridgeLockfileFresh(devBridge),
+    )
+  ) {
+    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 RNX_HOME.`,
+  )
+}
+
+async function ensureRuntimeForOpen() {
+  const active = readActiveRuntime()
+  if (active && fs.existsSync(runtimeDir(active))) return
+  console.error('  installing rnx engine runtime...')
+  const { runRuntime } = await import('./runtime')
+  await runRuntime(['install'], {})
+}
+
+function spawnSootsim(args: string[]) {
+  const { executable, prefixArgs } = rnxSelfInvocation()
+  return spawn(executable, [...prefixArgs, ...args], {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  })
+}
+
+function canConnectToBridge(port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`, { handshakeTimeout: timeoutMs })
+    let settled = false
+    const finish = (ok: boolean) => {
+      if (settled) return
+      settled = true
+      if (ws.readyState === WebSocket.OPEN) ws.close()
+      else if (ws.readyState === WebSocket.CONNECTING) ws.terminate()
+      resolve(ok)
+    }
+    ws.once('open', () => finish(true))
+    ws.on('error', () => finish(false))
+    setTimeout(() => finish(false), timeoutMs)
+  })
+}
+
+function looksLikeSootsimUrl(target: string): boolean {
+  try {
+    const url = new URL(target)
+    const pathname = url.pathname.replace(/\/+$/, '') || '/'
+    return (
+      url.searchParams.has('open') ||
+      url.searchParams.has('port') ||
+      url.searchParams.has('bundle') ||
+      url.searchParams.has('demo') ||
+      url.pathname.includes('/sootsim/index.html') ||
+      pathname === '/sootsim' ||
+      url.pathname === '/__soot' ||
+      url.pathname === '/__soot/' ||
+      pathname === '/rn' ||
+      /^\/rn\/[^/]+$/i.test(pathname) ||
+      /^\/app\/[^/]+$/i.test(pathname) ||
+      pathname === '/__soot/rn' ||
+      /^\/__soot\/rn\/[^/]+$/i.test(pathname) ||
+      /^\/__soot\/app\/[^/]+$/i.test(pathname)
+    )
+  } catch {
+    return false
+  }
+}
+
+function looksLikeShellPathTarget(target: string): boolean {
+  try {
+    const url = new URL(target, 'http://sootsim.local')
+    if (url.origin !== 'http://sootsim.local') return false
+    const pathname = url.pathname.replace(/\/+$/, '') || '/'
+    return (
+      pathname === '/rn' ||
+      /^\/rn\/[^/]+$/i.test(pathname) ||
+      /^\/app\/[^/]+$/i.test(pathname) ||
+      pathname === '/__soot/rn' ||
+      /^\/__soot\/rn\/[^/]+$/i.test(pathname) ||
+      /^\/__soot\/app\/[^/]+$/i.test(pathname)
+    )
+  } catch {
+    return false
+  }
+}
+
+function buildShellPathOpenUrl(target: string, baseUrl: string): string {
+  const targetUrl = new URL(target, 'http://sootsim.local')
+  const url = new URL(baseUrl)
+  const prefix = getShellRoutePrefix(url.pathname)
+  const routePath = targetUrl.pathname.startsWith('/__soot/')
+    ? targetUrl.pathname.slice('/__soot'.length)
+    : targetUrl.pathname
+
+  url.pathname = `${prefix}${routePath}`
+  url.search = targetUrl.search
+  url.hash = targetUrl.hash
+  return url.toString()
+}
+
+// rnx share/preview/build links (e.g. https://rnxsim.com/preview/<id>,
+// https://contrast.dev/build/<owner>/<repo>/<branch>) are full player pages
+// served by the Contrast app — NOT Metro bundles and NOT driveable shell sims.
+// passing one to `rnx open` used to fall through to the bundle resolver,
+// which fetched the HTML page and choked with "Unexpected token '<'". two
+// hard reasons they can't become a CLI-driveable sim:
+//   1. the engine only attaches to the local CLI bridge from a localhost /
+//      127.0.0.1 origin (see engine `mcp/ws-bridge.ts` connect gate), so a
+//      remote preview page never registers a sim.
+//   2. a captured share's transformed bundle is pinned to the engine build
+//      that produced it — its lazy `/engine-tenant/assets/*` chunk hashes
+//      only exist on that deploy, so a remote share can't be re-hosted
+//      through the local dev shell (the dynamic chunk import 404s).
+// recognize these URLs so `open` opens them for viewing instead.
+function looksLikeSootSimShareUrl(target: string): boolean {
+  try {
+    const pathname = new URL(target).pathname.replace(/\/+$/, '') || '/'
+    return /^\/preview\/[^/]+$/.test(pathname) || /^\/build\/.+/.test(pathname)
+  } catch {
+    return false
+  }
+}
+
+export async function resolveBundleTarget(target: string): Promise<string> {
+  const normalized = normalizeKnownTarget(target)
+  const resolved = await resolveConnectionInputForCli(normalized)
+  return resolved.bundleUrl
+}
+
+function localBasePort(target: string): number | null {
+  try {
+    const url = new URL(target.startsWith('http') ? target : `http://${target}`)
+    const pathname = url.pathname || '/'
+    if ((pathname !== '/' && pathname !== '') || url.search || url.hash) return null
+    if (!isLoopbackHost(url.hostname)) return null
+    const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80
+    return Number.isFinite(port) && port > 0 ? port : null
+  } catch {
+    return null
+  }
+}
+
+// a dev server started alongside open connect may still be booting when the
+// first probe lands. retry briefly so staging does not fail on a server that
+// becomes probe-ready a few seconds later.
+const DEV_BUNDLE_RESOLVE_ATTEMPTS = 15
+const DEV_BUNDLE_RESOLVE_INTERVAL_MS = 1000
+
+async function resolveConnectionInputForCli(target: string): Promise<ResolvedDevBundle> {
+  const normalized = normalizeKnownTarget(target)
+  const registeredPort = /^\d+$/.test(normalized)
+    ? Number(normalized)
+    : localBasePort(normalized)
+
+  let lastError: Error | null = null
+  for (let attempt = 0; attempt < DEV_BUNDLE_RESOLVE_ATTEMPTS; attempt++) {
+    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.
+      if (discovered && !discovered.bundleUrlProvisional) {
+        return {
+          bundleUrl: discovered.bundleUrl,
+          port: discovered.port,
+          framework: discovered.framework,
+          projectName: discovered.projectName,
+        }
+      }
+    }
+
+    try {
+      return await resolveConnectionInput(normalized)
+    } catch (error) {
+      if (!(error instanceof Error) || !error.message.startsWith("could not resolve a native bundle")) {
+        throw error
+      }
+      lastError = error
+    }
+    await sleep(DEV_BUNDLE_RESOLVE_INTERVAL_MS)
+  }
+  throw lastError ?? new Error("could not resolve a native bundle for " + normalized + " after retrying.")
+}
+
+function getShellRoutePrefix(pathname: string): string {
+  const normalized = pathname.replace(/\/+$/, '') || '/'
+  if (normalized === '/__soot' || normalized.startsWith('/__soot/')) {
+    return '/__soot'
+  }
+  return ''
+}
+
+function buildConnectOpenUrl(target: string, baseUrl: string): string {
+  const normalizedTarget = normalizeKnownTarget(target)
+  const url = new URL(baseUrl)
+  const prefix = getShellRoutePrefix(url.pathname)
+
+  url.pathname = `${prefix}/rn`
+  url.searchParams.delete('bundle')
+  url.searchParams.delete('demo')
+  url.searchParams.delete('app')
+  url.searchParams.delete('open')
+  url.searchParams.delete('port')
+
+  if (/^\d+$/.test(normalizedTarget)) {
+    url.pathname = `${prefix}/rn/${normalizedTarget}`
+  } else {
+    url.pathname = `${prefix}/rn`
+    url.searchParams.set('open', normalizedTarget)
+  }
+
+  return url.toString()
+}
+
+function shouldResolveBundleTargetInCli(target: string): boolean {
+  const normalizedTarget = normalizeKnownTarget(target)
+  if (/^\d+$/.test(normalizedTarget)) return true
+  if (/^https?:\/\//i.test(normalizedTarget)) return true
+  return /^(localhost|127\.0\.0\.1|\[::1\]|[^/]+\.localhost):\d+(?:\/.*)?$/i.test(
+    normalizedTarget,
+  )
+}
+
+async function buildResolvedBundleOpenUrl(
+  target: string,
+  baseUrl: string,
+  opts: BuildShellUrlOptions = {},
+): Promise<string> {
+  const resolved = opts.resolvedBundle ?? (await resolveConnectionInputForCli(target))
+  const url = new URL(baseUrl)
+  const prefix = getShellRoutePrefix(url.pathname)
+  url.pathname = `${prefix}/rn`
+  url.searchParams.delete('open')
+  url.searchParams.delete('port')
+  url.searchParams.delete('demo')
+  url.searchParams.delete('app')
+  const bundleUrl =
+    opts.hot === undefined
+      ? resolved.bundleUrl
+      : applyHotMode(resolved.bundleUrl, opts.hot)
+  url.searchParams.set('bundle', bundleUrl)
+  return url.toString()
+}
+
+function normalizeReplacementPath(filePath: string): string {
+  if (filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2))
+  }
+  if (path.isAbsolute(filePath)) return filePath
+  return path.resolve(process.cwd(), filePath)
+}
+
+function parseOpenRuntimeConfig(args: string[]): RNXConfig | undefined {
+  const modules: NonNullable<RNXConfig['modules']> = {}
+  const remap: Record<string, string> = {}
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--replace') {
+      const raw = args[i + 1]
+      if (!raw) {
+        console.error('  rnx open: --replace expects <module>=<file>')
+        rnxExit(1)
+      }
+      const eqIndex = raw.indexOf('=')
+      if (eqIndex <= 0 || eqIndex === raw.length - 1) {
+        console.error('  rnx open: --replace expects <module>=<file>')
+        rnxExit(1)
+      }
+      const moduleName = raw.slice(0, eqIndex).trim()
+      const filePath = normalizeReplacementPath(raw.slice(eqIndex + 1).trim())
+      if (!fs.existsSync(filePath)) {
+        console.error(`  rnx open: replacement file not found: ${filePath}`)
+        rnxExit(1)
+      }
+      modules[moduleName] = { file: filePath }
+      i++
+      continue
+    }
+    // --remap <host:port>=<host:port> rewrites a guest fetch's host:port at
+    // runtime (config.network.remap). repeatable. lets a flow against an app
+    // that hardcodes a port reach a differently-bound service.
+    if (args[i] === '--remap') {
+      const raw = args[i + 1]
+      const eqIndex = raw ? raw.indexOf('=') : -1
+      if (!raw || eqIndex <= 0 || eqIndex === raw.length - 1) {
+        console.error('  rnx open: --remap expects <host:port>=<host:port>')
+        rnxExit(1)
+      }
+      remap[raw.slice(0, eqIndex).trim()] = raw.slice(eqIndex + 1).trim()
+      i++
+      continue
+    }
+  }
+
+  const config: RNXConfig = {}
+  if (Object.keys(modules).length > 0) config.modules = modules
+  if (Object.keys(remap).length > 0) config.network = { remap }
+  return config.modules || config.network ? config : undefined
+}
+
+async function resolveAppProjectForBundleUrl(
+  bundleUrl?: string,
+): Promise<ResolvedAppProject | null> {
+  if (!bundleUrl) return null
+  const advertisedRoot = await resolveMetroProjectRoot(bundleUrl)
+  return advertisedRoot ? resolveAppProject(advertisedRoot) : null
+}
+
+async function ensureConfiguredRuntime(version: string): Promise<void> {
+  if (fs.existsSync(path.join(runtimeDir(version), 'index.html'))) return
+  console.error(`  installing configured engine runtime ${version}...`)
+  const result = await rnxRuntime.install({
+    version,
+    setActive: false,
+    protectVersions: readLiveRuntimeVersions(),
+  })
+  console.error(`  installed engine runtime ${result.version}`)
+}
+
+export function applyRuntimeGenerationOrigin(baseUrl: string, version?: string): string {
+  const selectedVersion =
+    version ??
+    (resolveDevCheckoutRuntimeRoot() ? undefined : (readActiveRuntime() ?? undefined))
+  if (!selectedVersion) return baseUrl
+  const url = new URL(baseUrl)
+  if (!isLoopbackHost(url.hostname)) {
+    if (!version) return baseUrl
+    throw new Error(
+      `runtimeVersion ${selectedVersion} requires a local rnx host; got ${url.origin}`,
+    )
+  }
+  url.hostname = runtimeVersionHostname(selectedVersion)
+  return url.toString()
+}
+
+export function resolveDefaultShellBaseUrl(): string {
+  return resolveBridgeWorld().shellBaseUrl
+}
+
+/** the shell that belongs to a bridge port: the world a fresh lockfile claims
+ *  for it, otherwise the shell that shares the port's own offset. every caller
+ *  that has already settled on a bridge port goes through this, so a page can
+ *  never open in one stack's shell while the CLI polls another's bridge. the
+ *  development bridge registry keeps every live port addressable, while this
+ *  function preserves an explicit caller's already-selected world. */
+export function resolveShellBaseUrlForBridgePort(bridgePort: number): string {
+  return (
+    worldForBridgePort(bridgePort)?.shellBaseUrl ??
+    resolveSootsimShellBaseUrlForBridgePort(bridgePort) ??
+    resolveDefaultShellBaseUrl()
+  )
+}
+
+// stamp the engine page url with `?appFonts=<url[::family]>,...` 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
+// fetches itself. auto-discovery only — scans the repo for expo-font config
+// plugin declarations, no user-facing flag.
+//
+// each discovered font is HEAD-checked against the metro host before we
+// include it on the URL. fonts whose metro asset URL 404s (typo in the
+// expo-font plugin config, missing file, or a wrong app.config picked up
+// by the scan) are dropped silently so the engine never tries to fetch a
+// known-bad URL at boot — that would just log a registration failure and
+// confuse anyone reading the page console.
+async function stampAppFonts(
+  urlStr: string,
+  project?: ResolvedAppProject | null,
+): Promise<string> {
+  try {
+    const url = new URL(urlStr)
+    const bundleUrl = url.searchParams.get('bundle') || ''
+    if (!bundleUrl || !project) return urlStr
+    const specs = discoverNativeLinkedAppFonts({
+      bundleUrl,
+      projectDir: project.appDir,
+    })
+    if (specs.length === 0) return urlStr
+    const reachable = await filterReachableAppFonts(specs)
+    if (reachable.length === 0) return urlStr
+    url.searchParams.set('appFonts', encodeAppFontsWire(reachable))
+    return url.toString()
+  } catch {
+    return urlStr
+  }
+}
+
+// HEAD-check each font URL with a short timeout. metro returns 200 (or
+// sometimes a redirect) for assets it can resolve and 500 with an ENOENT
+// trace for paths it cannot. anything not in the 2xx-3xx range gets dropped.
+async function filterReachableAppFonts(
+  specs: DiscoveredAppFontSpec[],
+): Promise<DiscoveredAppFontSpec[]> {
+  const results = await Promise.all(
+    specs.map(async (spec): Promise<DiscoveredAppFontSpec | null> => {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), 1500)
+      try {
+        const res = await fetch(spec.url, {
+          method: 'HEAD',
+          signal: controller.signal,
+        })
+        if (res.status >= 200 && res.status < 400) return spec
+        return null
+      } catch {
+        return null
+      } finally {
+        clearTimeout(timer)
+      }
+    }),
+  )
+  const reachable: DiscoveredAppFontSpec[] = []
+  for (const spec of results) {
+    if (spec !== null) reachable.push(spec)
+  }
+  return reachable
+}
+
+async function resolveShellUrl(
+  target: string,
+  baseUrl: string,
+  opts: BuildShellUrlOptions = {},
+): Promise<string> {
+  // no target = open home screen
+  if (!target) {
+    return new URL(baseUrl).toString()
+  }
+
+  if (looksLikeSootsimUrl(target)) {
+    const url = new URL(target)
+    const base = new URL(baseUrl)
+    const baseConfig = base.searchParams.get(RNX_CONFIG_QUERY_PARAM)
+    if (baseConfig && !url.searchParams.has(RNX_CONFIG_QUERY_PARAM)) {
+      url.searchParams.set(RNX_CONFIG_QUERY_PARAM, baseConfig)
+    }
+    return url.toString()
+  }
+
+  if (looksLikeShellPathTarget(target)) {
+    return buildShellPathOpenUrl(target, baseUrl)
+  }
+
+  // check if this is a shell app (pathname-based route, not bundle)
+  const shellPath = SHELL_APPS[target.toLowerCase()]
+  if (shellPath) {
+    const url = new URL(baseUrl)
+    const prefix = getShellRoutePrefix(url.pathname)
+    url.pathname = `${prefix}${shellPath}`
+    return url.toString()
+  }
+
+  if (shouldResolveBundleTargetInCli(target)) {
+    return buildResolvedBundleOpenUrl(target, baseUrl, opts)
+  }
+
+  return buildConnectOpenUrl(target, baseUrl)
+}
+
+// stamp the engine page url with `?appSplash=<encodeURIComponent(JSON)>` so the
+// engine paints the app's REAL configured splash image + background on boot
+// (instead of the contrast device-default chrome). same discovery path as
+// fonts: scan the bundle's project for the expo-splash-screen /
+// react-native-bootsplash config plugin (or legacy `expo.splash`). the metro
+// manifest fallback in the engine covers the typed-URL case; this wire is the
+// instant-first-paint optimization.
+async function stampAppSplash(
+  urlStr: string,
+  project?: ResolvedAppProject | null,
+): Promise<string> {
+  try {
+    const url = new URL(urlStr)
+    const bundleUrl = url.searchParams.get('bundle') || ''
+    if (!bundleUrl || !project) return urlStr
+    const spec = discoverConfigPluginAppSplash({
+      bundleUrl,
+      projectDir: project.appDir,
+    })
+    if (!spec) return urlStr
+    // HEAD-check the image before stamping so a typo'd/missing splash path never
+    // makes the engine fetch a known-bad URL at boot.
+    if (spec.imageUrl) {
+      const reachable = await splashImageReachable(spec.imageUrl)
+      if (!reachable) return urlStr
+    }
+    url.searchParams.set('appSplash', encodeAppSplashWire(spec))
+    return url.toString()
+  } catch {
+    return urlStr
+  }
+}
+
+async function splashImageReachable(imageUrl: string): Promise<boolean> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), 1500)
+  try {
+    const res = await fetch(imageUrl, { method: 'HEAD', signal: controller.signal })
+    return res.status >= 200 && res.status < 400
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export interface BuildShellUrlOptions {
+  // when set, forces the metro `hot` query on the resolved bundle URL. true
+  // for interactive opens (HMR runtime in bundle, edits hot-apply), false
+  // for `--driver playwright`/agent runs (no in-bundle HMR wiring, no ws
+  // chatter, deterministic e2e). undefined leaves whatever value metro's
+  // manifest emitted — matches real iOS sims so metro's bundle cache is
+  // shared. set by `runOpenCommand` only.
+  hot?: boolean
+  // device model slug (e.g. iphone-16) stamped onto the engine URL as
+  // ?device=<model> — the shell reads it at boot (main.tsx) and live-switch
+  // uses the same param. without this, every driver-opened sim silently ran
+  // whatever profile the shell last persisted.
+  device?: string
+  resolvedBundle?: ResolvedDevBundle
+  project?: ResolvedAppProject | null
+  // deterministic-capture mode, stamped onto the engine URL as ?proof=1. the
+  // shell worker, compositor worker and tenant worker each read it off the
+  // host page URL at boot (syncProofModeFromInitUrl) and pin everything that
+  // would otherwise differ frame to frame: the TextInput caret stops blinking
+  // and stays visible, and notifications stop auto-dismissing. capture-frame
+  // also reads the raw param and stops clipping the device corners, so a
+  // capture matches simctl's rectangular framebuffer. without it a
+  // screen holding a focused text field never reaches three identical idle
+  // frames, so the screenshot guard burns all 12 attempts and then fails.
+  proof?: boolean
+}
+
+function bundleUrlOf(urlStr: string): string | undefined {
+  try {
+    return new URL(urlStr).searchParams.get('bundle') || undefined
+  } catch {
+    return undefined
+  }
+}
+
+export async function buildShellUrl(
+  target: string,
+  baseUrl: string = resolveDefaultShellBaseUrl(),
+  opts: BuildShellUrlOptions = {},
+): Promise<string> {
+  const resolved = await resolveShellUrl(target, baseUrl, opts)
+  // callers that hand us a bare port or url (the flow/maestro runner, the
+  // electron companion) have no project to pass. derive it from the bundle
+  // metro advertises so those paths get the same UIAppFonts and splash
+  // stamping an `rnx open` gets. without it a flow renders the app's text in a
+  // fallback typeface, which then reads as a conformance diff.
+  const project =
+    opts.project ?? (await resolveAppProjectForBundleUrl(bundleUrlOf(resolved)))
+  const stamped = await stampAppSplash(await stampAppFonts(resolved, project), project)
+  if (!opts.device && !opts.proof) return stamped
+  const url = new URL(stamped)
+  if (opts.device) url.searchParams.set('device', opts.device)
+  if (opts.proof) url.searchParams.set('proof', '1')
+  return url.toString()
+}
+
+function deriveCurrentSimBaseUrl(
+  sim: BridgeSimInfo | null | undefined,
+  fallback: string,
+): string {
+  const source = sim?.url || sim?.origin || fallback
+  try {
+    const url = new URL(source)
+    url.searchParams.delete('bundle')
+    url.searchParams.delete('demo')
+    url.searchParams.delete('app')
+    url.searchParams.delete('open')
+    url.searchParams.delete('port')
+    url.searchParams.delete('inspectOpen')
+    // appFonts is target-specific (it points at the metro asset endpoint of
+    // the bundle being launched). carrying it over from a prior sim URL
+    // means a stale font URL from an earlier launch leaks into the new one,
+    // and `stampAppFonts` doesn't get the chance to re-derive against the
+    // current bundle. drop it so the rebuild starts clean.
+    url.searchParams.delete('appFonts')
+    // appSplash is target-specific in the same way — drop it so the configured
+    // splash re-derives against the current bundle.
+    url.searchParams.delete('appSplash')
+    return url.toString()
+  } catch {
+    return fallback
+  }
+}
+
+export async function buildOpenUrl(
+  target: string,
+  baseUrl: string,
+  openToken: string,
+  opts: BuildShellUrlOptions = {},
+): Promise<string> {
+  const url = new URL(await buildShellUrl(target, baseUrl, opts))
+  url.searchParams.set('inspectOpen', openToken)
+  return url.toString()
+}
+
+async function waitForSimReady(
+  wsPort: number,
+  commandTimeoutMs: number,
+  simId: string,
+  opts: {
+    attempts?: number
+    intervalMs?: number
+    minNodeCount?: number
+  } = {},
+) {
+  // the ceiling here is attempts * intervalMs. a hosted launchApp re-evals the
+  // whole guest bundle over a tunnel, which routinely outlasts the local
+  // default, so scale the poll ceiling by the same factor the flow runner
+  // scales its own waits. this still returns the moment the sim reports enough
+  // nodes; only the deadline moves, and locally the scale is 1.
+  const intervalMs = opts.intervalMs ?? 500
+  const attempts = opts.attempts ?? Math.round(30 * flowTimeoutScale())
+  const minNodeCount = opts.minNodeCount ?? 10
+
+  // a poll that only ever reports "timed out" cannot say whether the guest was
+  // still booting, never installed the test hook, or was unreachable, so keep
+  // the last observation and hand it to the caller for the failure message.
+  let lastCount: unknown
+  let lastError = ''
+
+  for (let i = 0; i < attempts; i++) {
+    const bridge = createBridge(wsPort, {
+      commandTimeoutMs,
+      simId,
+      simIdSource: 'flag',
+    })
+    try {
+      const count = await bridge.send({
+        type: 'evaluate',
+        code: '(async () => (await window.__sootsimTest?.getNodeCount()) ?? null)()',
+      })
+      lastCount = count
+      lastError = ''
+      if (typeof count === 'number' && count > minNodeCount) {
+        return { bridge, count }
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err)
+    }
+    bridge.close()
+    await sleep(intervalMs)
+  }
+
+  return { bridge: null, attempts, intervalMs, minNodeCount, lastCount, lastError }
+}
+
+export async function waitForSimMatch(
+  wsPort: number,
+  commandTimeoutMs: number,
+  predicate: (sim: BridgeSimInfo) => boolean,
+  opts: { attempts?: number; intervalMs?: number } = {},
+) {
+  const attempts = opts.attempts ?? 30
+  const intervalMs = opts.intervalMs ?? 500
+  for (let i = 0; i < attempts; i++) {
+    const bridge = createBridge(wsPort, { commandTimeoutMs })
+    try {
+      const sims = await bridge.listSims()
+      const match = sims.find(predicate)
+      if (match) return match
+    } catch {
+      // server/sim may still be booting
+    } finally {
+      bridge.close()
+    }
+    await sleep(intervalMs)
+  }
+  return null
+}
+
+// same as waitForSimMatch, but also watches a detached host PID so a host
+// crash mid-connect is surfaced as a distinct outcome rather than waiting
+// out the full timeout (and silently treating a stale bridge entry as
+// success). 'host-exit' wins as soon as the host process is gone, even if
+// the bridge still lists the sim.
+export type WaitForSimMatchOrHostExitResult =
+  | { kind: 'match'; sim: BridgeSimInfo }
+  | { kind: 'host-exit' }
+  | { kind: 'timeout' }
+
+export async function waitForSimMatchOrHostExit(
+  wsPort: number,
+  commandTimeoutMs: number,
+  predicate: (sim: BridgeSimInfo) => boolean,
+  hostPid: number | undefined,
+  opts: { attempts?: number; intervalMs?: number } = {},
+): 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 && !isProcessAlive(hostPid)
+  for (let i = 0; i < attempts; i++) {
+    if (hostExited()) {
+      return { kind: 'host-exit' }
+    }
+    const bridge = createBridge(wsPort, { commandTimeoutMs })
+    try {
+      const sims = await bridge.listSims()
+      const match = sims.find(predicate)
+      if (match) {
+        if (hostExited()) return { kind: 'host-exit' }
+        return { kind: 'match', sim: match }
+      }
+    } catch {
+      // server/sim may still be booting
+    } finally {
+      bridge.close()
+    }
+    if (hostExited()) {
+      return { kind: 'host-exit' }
+    }
+    await sleep(intervalMs)
+  }
+  return { kind: 'timeout' }
+}
+
+async function waitForSimGone(
+  wsPort: number,
+  commandTimeoutMs: number,
+  simId: string,
+  opts: { attempts?: number; intervalMs?: number } = {},
+) {
+  const attempts = opts.attempts ?? 20
+  const intervalMs = opts.intervalMs ?? 250
+  for (let i = 0; i < attempts; i++) {
+    const bridge = createBridge(wsPort, { commandTimeoutMs })
+    try {
+      const sims = await bridge.listSims()
+      const sim = sims.find((entry) => entry.id === simId)
+      if (!sim || sim.readyState !== 'open') {
+        return true
+      }
+    } catch {
+      return true
+    } finally {
+      bridge.close()
+    }
+    await sleep(intervalMs)
+  }
+  return false
+}
+
+export function playwrightHostPidForSim(sim: BridgeSimInfo): number | null {
+  const meta = sim.meta
+  if (!meta || meta.sootsimHostDriver !== 'playwright') return null
+  const pid = Number(meta.sootsimHostPid)
+  if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return null
+  return pid
+}
+
+export function signalDriverLaunchConnected(result: DriverLaunchResult): boolean {
+  if (!result.connectAckFile) return false
+  try {
+    fs.writeFileSync(
+      result.connectAckFile,
+      `${JSON.stringify({ connectedAt: Date.now(), pid: result.pid ?? null })}\n`,
+      { flag: 'w' },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+function printDriverDiagnosticLogTail(result: DriverLaunchResult) {
+  if (!result.diagnosticLogPath) return
+  try {
+    const detail = fs.readFileSync(result.diagnosticLogPath, 'utf8').trim()
+    if (!detail) {
+      console.error(`  ${path.basename(result.diagnosticLogPath)} was empty`)
+      return
+    }
+    const shown = detail.length > 4_000 ? `…\n${detail.slice(-4_000)}` : detail
+    console.error(`  ${path.basename(result.diagnosticLogPath)}:`)
+    console.error(shown)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    console.error(
+      `  failed to read ${path.basename(result.diagnosticLogPath)}: ${message}`,
+    )
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException)?.code === 'EPERM'
+  }
+}
+
+async function waitForProcessExit(pid: number, timeoutMs = 2_500): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true
+    await sleep(100)
+  }
+  return !isProcessAlive(pid)
+}
+
+// a sim record's host pid can outlive its process; after pid reuse the number
+// may point at an unrelated process (real incident 2026-07-14: a stale record
+// made `rnx close` SIGTERM the shared vite shell dev server, taking the
+// whole dev stack down). only signal a pid whose argv proves it is still a
+// rnx playwright host launcher.
+function isPlaywrightHostProcess(pid: number): boolean {
+  // `ps eww` prints argv then the process ENVIRONMENT for same-user
+  // processes. the marker must live in the env SUFFIX (everything past the
+  // plain argv), because argv text can contain the string coincidentally —
+  // e.g. a shell wrapper that exports SOOTSIM_PW_* vars in its script body.
+  const plain = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const withEnv = spawnSync('ps', ['eww', '-o', 'command=', '-p', String(pid)], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (plain.status !== 0 || withEnv.status !== 0) return false
+  const argv = (plain.stdout || '').trimEnd()
+  const full = (withEnv.stdout || '').trimEnd()
+  const envSuffix = full.startsWith(argv) ? full.slice(argv.length) : full
+  return envSuffix.includes('SOOTSIM_PW_URL=')
+}
+
+export async function terminatePlaywrightHostsForSims(
+  sims: BridgeSimInfo[],
+  ids: string[],
+) {
+  const wanted = new Set(ids)
+  const pids = new Set<number>()
+  for (const sim of sims) {
+    if (!wanted.has(sim.id)) continue
+    const pid = playwrightHostPidForSim(sim)
+    if (pid) pids.add(pid)
+  }
+  for (const pid of pids) {
+    if (!isPlaywrightHostProcess(pid)) {
+      console.log(`  skipped pid ${pid}: not a rnx playwright host (stale sim record)`)
+      continue
+    }
+    try {
+      process.kill(pid, 'SIGTERM')
+    } catch {}
+    if (await waitForProcessExit(pid)) {
+      console.log(`  closed playwright host process ${pid}`)
+      continue
+    }
+    try {
+      process.kill(pid, 'SIGKILL')
+      console.log(`  force-closed playwright host process ${pid}`)
+    } catch {}
+  }
+}
+
+function resolveTargetSim(sims: BridgeSimInfo[], requestedId?: string): BridgeSimInfo {
+  if (requestedId) {
+    const normalizedId = requestedId.trim()
+    const match = sims.find((sim) => sim.id === normalizedId)
+    if (!match) {
+      throw new Error(`no sim connected with id ${normalizedId}`)
+    }
+    return match
+  }
+  const primary = sims.find((sim) => sim.isPrimary && sim.readyState === 'open')
+  if (primary) return primary
+  const firstOpen = sims.find((sim) => sim.readyState === 'open')
+  if (firstOpen) return firstOpen
+  throw new Error('no sim connected')
+}
+
+export function printOpenedSim(
+  openUrl: string,
+  sim: BridgeSimInfo,
+  mode:
+    | 'desktop companion'
+    | 'bridge'
+    | 'direct shell open'
+    | 'current sim'
+    | `${string} driver`,
+  quiet = false,
+) {
+  const [printableOpenUrl, printableSimUrl] = [openUrl, sim.url].map((value) => {
+    if (!value) return value
+    try {
+      const parsed = new URL(value)
+      let changed = false
+      if (parsed.searchParams.has(RNX_CONFIG_QUERY_PARAM)) {
+        parsed.searchParams.set(RNX_CONFIG_QUERY_PARAM, '[redacted]')
+        changed = true
+      }
+      const bundle = parsed.searchParams.get('bundle')
+      if (bundle) {
+        try {
+          const parsedBundle = new URL(bundle)
+          if (parsedBundle.searchParams.has(RNX_CONFIG_QUERY_PARAM)) {
+            parsedBundle.searchParams.set(RNX_CONFIG_QUERY_PARAM, '[redacted]')
+            parsed.searchParams.set('bundle', parsedBundle.toString())
+            changed = true
+          }
+        } catch {}
+      }
+      if (changed) return parsed.toString()
+    } catch {}
+    return value
+  })
+  if (quiet) {
+    console.log(`  Opened ConnectRN [${mode}]`)
+    return
+  }
+  console.log(
+    `  ${mode === 'current sim' ? 'loaded' : 'opened'}: ${printableOpenUrl} [${mode}]`,
+  )
+  // agents pipe around the JSON to grab the id; humans just want to know
+  // the current sim got updated without scanning the JSON blob.
+  console.log(`  current sim: ${sim.id}`)
+  console.log(JSON.stringify({ simId: sim.id, url: printableSimUrl }, null, 2))
+}
+
+// after a successful open, agents almost always want to know what's on the
+// screen. running describe inline saves a separate roundtrip. tightly
+// bounded — a cold guest bundle takes 5-15s to fully route, so we don't
+// try to wait for that. instead: settle for a moment to let the first
+// paint land, then describe whatever's on screen. for cold loads that's
+// a splash; the caller can `rnx describe` again a second later. for
+// warm loads it's the real screen. guarded by --no-describe.
+async function maybeDescribeAfterOpen(wsPort: number, simId: string, args: string[]) {
+  if (args.includes('--no-describe')) return
+  const prevQuiet = process.env.SOOTSIM_QUIET_TARGET_NOTICE
+  process.env.SOOTSIM_QUIET_TARGET_NOTICE = '1'
+  try {
+    // brief settle, then dump the tree directly. don't go through
+    // runDescribeSubcommand — its screen-transition wait can block for many
+    // seconds on a still-routing guest app, which is exactly what we want
+    // to skip for the open-side describe. caller can `rnx describe`
+    // again later for post-routing state.
+    await waitForTreeStable(wsPort, simId, { stableMs: 150, maxMs: 400 })
+    const bridge = createBridge(wsPort, {
+      commandTimeoutMs: 3000,
+      simId,
+      cliLabel: 'open --describe',
+      simIdSource: 'flag',
+    })
+    try {
+      let readyProbe: Awaited<ReturnType<typeof inspectWaitReady>> | null = null
+      try {
+        readyProbe = await inspectWaitReady(bridge, 1)
+      } catch {}
+      if (readyProbe) {
+        if (!readyProbe.ready) {
+          const reason = readyProbe.loadingText
+            ? `still showing "${readyProbe.loadingText}"`
+            : readyProbe.flag !== true
+              ? 'guest ready event has not fired'
+              : readyProbe.targets <= 0
+                ? 'no visible app content is inspectable yet'
+                : 'app tree is still stabilizing'
+          console.log(
+            `  app still loading: ${reason} (nodes: ${readyProbe.nodes}, targets: ${readyProbe.targets})`,
+          )
+          console.log('  before interacting, run: rnx wait ready --max-ms 120000')
+        }
+      }
+      const result = await inspectDescribe(bridge, {
+        describe: true,
+        verbose: false,
+        filter: '',
+        compact: true,
+        hideXy: false,
+        maxDepth: 12,
+      })
+      if (!result?.tree) return
+      console.log('')
+      console.log(result.tree)
+    } finally {
+      bridge.close()
+    }
+  } catch {
+    // describe is a convenience — never fail the open command on it
+  } finally {
+    if (prevQuiet === undefined) {
+      delete process.env.SOOTSIM_QUIET_TARGET_NOTICE
+    } else {
+      process.env.SOOTSIM_QUIET_TARGET_NOTICE = prevQuiet
+    }
+  }
+}
+
+// poll node count and return as soon as two samples match across `stableMs`,
+// capped by `maxMs`. brief and bounded so this never blocks the open command.
+async function waitForTreeStable(
+  wsPort: number,
+  simId: string,
+  opts: { stableMs: number; maxMs: number },
+): Promise<void> {
+  const deadline = Date.now() + opts.maxMs
+  const probeCode = `(async () => (await window.__sootsimTest?.getNodeCount?.()) || 0)()`
+  const bridge = createBridge(wsPort, {
+    commandTimeoutMs: 2000,
+    simId,
+    simIdSource: 'flag',
+  })
+  try {
+    let lastCount = -1
+    let stableSince = 0
+    while (Date.now() < deadline) {
+      let count = -1
+      try {
+        const c = await bridge.send({ type: 'evaluate', code: probeCode })
+        if (typeof c === 'number') count = c
+      } catch {
+        // transient — try again
+      }
+      if (count >= 0 && count === lastCount) {
+        if (Date.now() - stableSince >= opts.stableMs) return
+      } else {
+        lastCount = count
+        stableSince = Date.now()
+      }
+      await sleep(50)
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+export async function runLinkCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+  })
+  if (parsed.positional.length !== 1) {
+    console.error('  rnx open: expected exactly one <url-or-route>')
+    console.error('  examples: rnx open /settings  |  rnx open myapp://settings')
+    rnxExit(1)
+  }
+
+  const bridge = createBridgeFromParsed(parsed)
+  const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+  try {
+    const target = await openAppUrl(bridge, parsed.positional[0] ?? '')
+    console.log(`  opened deep link: ${target}`)
+  } catch (err) {
+    console.error(`  link failed: ${err instanceof Error ? err.message : String(err)}`)
+    await printBridgeFailureDiagnostics(bridge, {
+      errorsCommand: `rnx get errors 5${simHint}`,
+      warningsCommand: `rnx get warnings 5${simHint}`,
+      requestsCommand: `rnx get requests 5${simHint}`,
+    })
+    rnxExit(1)
+  } finally {
+    bridge.close()
+  }
+}
+
+export async function runOpenCommand(
+  args: string[],
+  opts: ControlCommandOptions = {},
+): Promise<{ simId: string; launched: boolean } | undefined> {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: [
+      '--new',
+      '--headless',
+      '--headed',
+      '--ephemeral',
+      '--hot',
+      '--no-hmr',
+      '--no-describe',
+      '--quiet',
+      '--proof',
+    ],
+    stripValueFlags: [
+      '--base-url',
+      '--replace',
+      '--driver',
+      '--profile',
+      '--cdp-port',
+      '--device',
+      '--viewport',
+    ],
+  })
+  const requestedProfileId = args.find((_, i) => args[i - 1] === '--profile')
+  const quiet = args.includes('--quiet')
+  const ephemeralProfile = args.includes('--ephemeral')
+  // --cdp-port exposes Chrome's remote-debugging endpoint on the opened sim so
+  // it can be cpu-profiled while bridge-driven (playwright driver only).
+  const cdpPortArg = args.find((_, i) => args[i - 1] === '--cdp-port')
+  const cdpPort = cdpPortArg ? Number(cdpPortArg) : undefined
+  if (cdpPortArg && (!Number.isFinite(cdpPort) || cdpPort! <= 0)) {
+    console.error(
+      `  rnx open: --cdp-port must be a positive port number, got "${cdpPortArg}"`,
+    )
+    rnxExit(1)
+  }
+  if (requestedProfileId && ephemeralProfile) {
+    console.error('  rnx open: --profile cannot be combined with --ephemeral')
+    rnxExit(1)
+  }
+  const profileId = requestedProfileId ? ensureProfile(requestedProfileId).id : undefined
+  const openInNewSim = args.includes('--new') || !!profileId || ephemeralProfile
+  const commandConfig = parseOpenRuntimeConfig(args)
+  if (openInNewSim && parsed.simIdSource === 'flag') {
+    console.error(
+      '  rnx open: --new, --profile, and --ephemeral cannot be combined with --sim',
+    )
+    rnxExit(1)
+  }
+  const target = parsed.positional[0] || ''
+
+  if (isAppDeepLinkTarget(target)) {
+    if (openInNewSim) {
+      console.error(
+        '  rnx open: deep links target the current app; remove --new, --profile, or --ephemeral',
+      )
+      rnxExit(1)
+    }
+    await runLinkCommand(args, opts)
+    return
+  }
+
+  // a preview/build link is a viewing page, not a driveable sim target —
+  // open it in the browser and explain rather than mis-loading it as a
+  // bundle. see looksLikeSootSimShareUrl for why these can't be driven.
+  if (looksLikeSootSimShareUrl(target)) {
+    const isLocal = (() => {
+      try {
+        return isLoopbackHost(new URL(target).hostname)
+      } catch {
+        return false
+      }
+    })()
+    console.log(
+      '  that’s an rnx preview/build link — a full player page, not a driveable sim.',
+    )
+    console.log('  opening it in your browser for viewing…')
+    try {
+      await openUrlInBrowser(target, { background: false })
+    } catch (err) {
+      console.error(
+        `  could not launch a browser: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      console.error(`  open it yourself: ${target}`)
+      rnxExit(1)
+    }
+    console.log(
+      isLocal
+        ? '  to drive it under the CLI, point `rnx open` at the app’s dev port instead (e.g. `rnx open 8081`).'
+        : '  the CLI can’t drive a remote preview (the engine only attaches to the local bridge from localhost). to drive the app, run it locally and `rnx open <port>`.',
+    )
+    return
+  }
+
+  const resolvedBundle = shouldResolveBundleTargetInCli(target)
+    ? await resolveConnectionInputForCli(target)
+    : undefined
+  const project = await resolveAppProjectForBundleUrl(resolvedBundle?.bundleUrl)
+  const appConfig = await loadRNXAppConfig(project)
+  const configuredRuntimeVersion = appConfig?.runtimeVersion
+  const runtimeConfig = mergeRNXConfig(
+    mergeRNXConfig(
+      appConfig ? { ...appConfig, runtimeVersion: undefined } : undefined,
+      opts.runtimeConfig,
+    ),
+    commandConfig,
+  )
+  if (configuredRuntimeVersion) {
+    await ensureConfiguredRuntime(configuredRuntimeVersion)
+  }
+
+  // keep the bridge port and the shell base URL in one world: --base-url
+  // retargets polling at THAT world's bridge (otherwise open builds the page
+  // against one runtime while polling the other bridge for registration and
+  // times out after ~125s), and a pin nothing serves is refused rather than
+  // falling back to the discovered default, which used to send
+  // ensureBridgeForOpen below off to start a second shell.
+  const explicitBaseUrl = args.find((_, i) => args[i - 1] === '--base-url')
+  if (explicitBaseUrl) {
+    const pinned = resolveBridgePortForPin({
+      baseUrl: explicitBaseUrl,
+      wsPort: parsed.wsPort,
+      explicitPort: parsed.explicitPort,
+    })
+    if (pinned.error !== undefined) {
+      console.error(`  error: ${pinned.error}`)
+      rnxExit(1)
+    } else {
+      parsed.wsPort = pinned.port
+    }
+  }
+
+  parsed.wsPort = await ensureBridgeForOpen(parsed.wsPort, parsed.explicitPort)
+
+  // playwright is the browser-sim launcher. it owns an isolated profile and
+  // can reap exactly its own browser tree. electron remains available for the
+  // native desktop surface. neither path opens the user's browser profile.
+  const requestedDriverId = args.find((_, i) => args[i - 1] === '--driver') || ''
+  if (requestedDriverId && !isDriverId(requestedDriverId)) {
+    console.error(`  unknown driver "${requestedDriverId}" — run \`rnx list --drivers\``)
+    rnxExit(1)
+  }
+  const driverId: DriverId = isDriverId(requestedDriverId)
+    ? requestedDriverId
+    : process.env.CI === '1' ||
+        process.env.CI === 'true' ||
+        process.env.GITHUB_ACTIONS === 'true' ||
+        isAgentEnv() ||
+        !process.stdin.isTTY
+      ? 'playwright'
+      : readSimulatorDriverPreference() || 'playwright'
+  const driverHeadless = resolveDriverHeadless(args, driverId)
+  if (cdpPort && driverId !== 'playwright') {
+    console.error('  rnx open: --cdp-port is only honored by the playwright driver')
+    rnxExit(1)
+  }
+
+  // metro HMR mode. interactive opens default to hot=true so edits hot-apply
+  // through rnx's HmrClient — expo CLI's createBundleUrlSearchParams
+  // hardcodes hot=false on every launchAsset URL (a leftover toggle real iOS
+  // sims tolerate but rnx couldn't until now), so without this flip the
+  // bundle prelude doesn't include metro's HMR runtime + react-refresh and
+  // edits silently no-op. `--driver playwright` (agent / CI runs) defaults
+  // to hot=false for deterministic e2e. explicit `--hot` / `--no-hmr` win.
+  const hotFlag = args.includes('--hot')
+  const noHmrFlag = args.includes('--no-hmr')
+  if (hotFlag && noHmrFlag) {
+    console.error('  rnx open: --hot and --no-hmr cannot be combined')
+    rnxExit(1)
+  }
+  const hotMode = hotFlag ? true : noHmrFlag ? false : driverId !== 'playwright'
+
+  // --device <model> seeds the device profile for the opened sim (stamped on
+  // the engine URL, so both playwright and electron honor it). without it
+  // the sim runs whatever profile the
+  // shell last persisted, which silently skews browser comparisons.
+  const deviceArg = args.find((_, i) => args[i - 1] === '--device')
+  if (deviceArg && !(deviceArg in devices)) {
+    console.error(`  rnx open: unknown device "${deviceArg}"`)
+    console.error(`  known devices: ${listSelectableDeviceModels().join(', ')}`)
+    rnxExit(1)
+  }
+  const deviceSpec = deviceArg ? devices[deviceArg as DeviceModel] : undefined
+
+  // --viewport <WxH> sizes the driver-launched page explicitly (film and
+  // promo captures frame the 3d stage in landscape). takes precedence over
+  // the device-derived window; without either, the driver keeps its own
+  // default.
+  const viewportArg = args.find((_, i) => args[i - 1] === '--viewport')
+  const viewportMatch = viewportArg ? /^(\d+)x(\d+)$/.exec(viewportArg) : null
+  if (viewportArg && !viewportMatch) {
+    console.error(`  rnx open: --viewport must be <width>x<height>, got "${viewportArg}"`)
+    rnxExit(1)
+  }
+  const explicitViewport = viewportMatch
+    ? { width: Number(viewportMatch[1]), height: Number(viewportMatch[2]) }
+    : undefined
+
+  const buildShellUrlOpts: BuildShellUrlOptions = {
+    hot: hotMode,
+    device: deviceArg,
+    resolvedBundle,
+    project,
+    proof: args.includes('--proof'),
+  }
+
+  // resolve the shell base URL from the bridge port we settled on, so the page
+  // and the polling never split across worlds.
+  const selectedShellBaseUrl = configuredRuntimeVersion
+    ? `http://localhost:${parsed.wsPort}/`
+    : explicitBaseUrl || resolveShellBaseUrlForBridgePort(parsed.wsPort)
+  const baseUrl = applyRuntimeGenerationOrigin(
+    selectedShellBaseUrl,
+    configuredRuntimeVersion,
+  )
+  const hasExplicitBaseUrl = args.includes('--base-url')
+  printBridgeWorldNotice(parsed.wsPort, baseUrl)
+  const savedSimId = readCurrentSimId()
+  const shouldReuseCurrentSim = !openInNewSim
+  // every open stamps its page URL with a one-off token and matches the sim by
+  // it. a sim id alone cannot tell the page this open loaded from the page it
+  // replaced, which stays registered until the browser commits the navigation.
+  const token = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+  const simMatchesToken = (sim: BridgeSimInfo) =>
+    sim.url?.includes(`inspectOpen=${token}`) ?? false
+
+  if (shouldReuseCurrentSim) {
+    const bridge = createBridgeFromParsed(parsed)
+    const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+    let fallBackToNewSim = false
+    let navigatedShellUrl: string | null = null
+
+    try {
+      let targetSim: BridgeSimInfo | null = null
+      let targetShellUrl: string | null = null
+      try {
+        const sims = await bridge.listSims()
+        if (parsed.simIdSource === 'saved') {
+          targetSim =
+            sims.find(
+              (sim) =>
+                sim.id === savedSimId &&
+                sim.readyState === 'open' &&
+                simUsesDriver(sim, driverId),
+            ) ?? null
+          if (!targetSim) {
+            clearCurrentSimId()
+          }
+        } else if (parsed.simIdSource === 'flag') {
+          targetSim = resolveTargetSim(sims, parsed.simId)
+          if (!simUsesDriver(targetSim, driverId)) {
+            throw new Error(
+              `sim ${targetSim.id} is not managed by the ${driverId} driver`,
+            )
+          }
+        }
+        if (!targetSim && parsed.simIdSource !== 'flag') {
+          targetShellUrl = await buildShellUrl(
+            target,
+            applyRNXConfigToUrl(baseUrl, runtimeConfig),
+            buildShellUrlOpts,
+          )
+          const normalizedTarget = new URL(targetShellUrl)
+          normalizedTarget.searchParams.delete('inspectOpen')
+          targetSim =
+            sims.find((sim) => {
+              if (
+                sim.readyState !== 'open' ||
+                !sim.url ||
+                !simUsesDriver(sim, driverId)
+              ) {
+                return false
+              }
+              try {
+                const normalizedCurrent = new URL(sim.url)
+                normalizedCurrent.searchParams.delete('inspectOpen')
+                return normalizedCurrent.toString() === normalizedTarget.toString()
+              } catch {
+                return false
+              }
+            }) ?? null
+        }
+        if (!targetSim) {
+          if (parsed.simIdSource !== 'flag') {
+            fallBackToNewSim = true
+          } else {
+            throw new Error('no sim connected')
+          }
+        }
+        if (!fallBackToNewSim && targetSim) {
+          const resolvedBaseUrl =
+            hasExplicitBaseUrl || looksLikeSootsimUrl(target)
+              ? baseUrl
+              : deriveCurrentSimBaseUrl(targetSim, baseUrl)
+          navigatedShellUrl =
+            targetShellUrl ??
+            (await buildShellUrl(
+              target,
+              applyRNXConfigToUrl(resolvedBaseUrl, runtimeConfig),
+              buildShellUrlOpts,
+            ))
+          const navigationUrl = new URL(navigatedShellUrl)
+          navigationUrl.searchParams.set('inspectOpen', token)
+          bridge
+            .send({
+              type: 'evaluate',
+              simId: targetSim.id,
+              code: `window.location.href = ${JSON.stringify(navigationUrl.toString())}`,
+            })
+            .catch(() => {})
+        }
+      } catch (err) {
+        console.error(
+          `  open failed: ${err instanceof Error ? err.message : String(err)}`,
+        )
+        await printBridgeFailureDiagnostics(bridge, {
+          errorsCommand: `rnx get errors 5${simHint}`,
+          warningsCommand: `rnx get warnings 5${simHint}`,
+          requestsCommand: `rnx get requests 5${simHint}`,
+        })
+        rnxExit(1)
+      }
+
+      if (!fallBackToNewSim && targetSim && navigatedShellUrl) {
+        // the navigated page may keep the sim id (restored from session
+        // storage) or register a new one, so match by token, never by id.
+        const navigatedSim = await waitForSimMatch(
+          parsed.wsPort,
+          parsed.commandTimeoutMs,
+          (sim) =>
+            sim.readyState === 'open' &&
+            simUsesDriver(sim, driverId) &&
+            simMatchesToken(sim),
+          { attempts: Math.round(30 * flowTimeoutScale()) },
+        )
+        if (!navigatedSim) {
+          console.error(
+            `  timed out waiting for sim ${targetSim.id} to load ${navigatedShellUrl}`,
+          )
+          await printBridgeFailureDiagnostics(bridge, {
+            errorsCommand: `rnx get errors 5${simHint}`,
+            warningsCommand: `rnx get warnings 5${simHint}`,
+            requestsCommand: `rnx get requests 5${simHint}`,
+          })
+          rnxExit(1)
+        }
+        targetSim = navigatedSim
+        const ready = await waitForSimReady(
+          parsed.wsPort,
+          parsed.commandTimeoutMs,
+          targetSim.id,
+        )
+        if (!ready.bridge) {
+          const observed = ready.lastError
+            ? `last bridge error: ${ready.lastError}`
+            : ready.lastCount === null
+              ? 'guest never installed window.__sootsimTest'
+              : `last node count: ${String(ready.lastCount)} (needs > ${ready.minNodeCount})`
+          console.error(
+            `  timed out waiting for current sim to load target after ${ready.attempts} polls over ${Math.round((ready.attempts * ready.intervalMs) / 1000)}s; ${observed}`,
+          )
+          await printBridgeFailureDiagnostics(bridge, {
+            errorsCommand: `rnx get errors 5${simHint}`,
+            warningsCommand: `rnx get warnings 5${simHint}`,
+            requestsCommand: `rnx get requests 5${simHint}`,
+          })
+          rnxExit(1)
+        }
+        ready.bridge.close()
+        saveCurrentSimId(targetSim.id)
+        printOpenedSim(
+          navigatedShellUrl,
+          { ...targetSim, url: navigatedShellUrl },
+          'current sim',
+          quiet,
+        )
+        await maybeDescribeAfterOpen(parsed.wsPort, targetSim.id, args)
+        return { simId: targetSim.id, launched: false }
+      }
+    } finally {
+      bridge.close()
+    }
+  }
+
+  const configuredBaseUrl = applyRNXConfigToUrl(baseUrl, runtimeConfig)
+  const openUrl = await buildOpenUrl(target, configuredBaseUrl, token, buildShellUrlOpts)
+  const ownerPid = getStableOwnerPid()
+  if (!ownerPid) {
+    console.error(
+      '  could not resolve a stable owning process; refusing unsupervised sim host',
+    )
+    rnxExit(1)
+  }
+  const driver = getDriver(driverId)
+  if (!driver) {
+    console.error(`  unknown driver "${driverId}" — run \`rnx list --drivers\``)
+    rnxExit(1)
+  }
+  const connectWait = resolveDriverConnectWaitOptions()
+  const result = await driver.launch({
+    url: openUrl,
+    // the shell serves the sim page but its WS bridge may have drifted off
+    // the shell-port-implied default. inject the bridge this command settled
+    // on so the page does not reconnect to a stale world. re-deriving it from
+    // the shell URL could name a third port, since a bridge with no lockfile
+    // resolves back to the default shell URL and that shell may belong to a
+    // live world of its own.
+    bridgePort: parsed.wsPort,
+    headless: driverHeadless,
+    profileId,
+    ephemeralProfile,
+    cdpPort,
+    device: deviceArg,
+    ownerPid,
+    viewport:
+      explicitViewport ??
+      (deviceSpec
+        ? { width: deviceSpec.width + 120, height: deviceSpec.height + 60 }
+        : undefined),
+    connectTimeoutMs: connectWait.hostTimeoutMs,
+  })
+  if (!result.launched) {
+    console.error(`  ${driver.name} driver: ${result.message}`)
+    rnxExit(1)
+  }
+  const outcome = await waitForSimMatchOrHostExit(
+    parsed.wsPort,
+    parsed.commandTimeoutMs,
+    simMatchesToken,
+    result.pid,
+    { attempts: connectWait.attempts, intervalMs: connectWait.intervalMs },
+  )
+  if (outcome.kind === 'host-exit') {
+    printDriverDiagnosticLogTail(result)
+    console.error(`  ${driver.name} host crashed — sim is no longer attached`)
+    rnxExit(1)
+  }
+  if (outcome.kind === 'timeout') {
+    if (result.pid) {
+      try {
+        process.kill(result.pid, 'SIGTERM')
+        console.error(`  closed ${driver.name} host process ${result.pid}`)
+      } catch {}
+    }
+    printDriverDiagnosticLogTail(result)
+    console.error(
+      `  timed out after ${connectWait.timeoutMs}ms waiting for opened sim to connect`,
+    )
+    rnxExit(1)
+  }
+  const match = outcome.sim
+  saveCurrentSimId(match.id)
+  signalDriverLaunchConnected(result)
+  printOpenedSim(openUrl, match, `${driver.name} driver`, quiet)
+  await maybeDescribeAfterOpen(parsed.wsPort, match.id, args)
+  return { simId: match.id, launched: true }
+}
+
+async function runUseLikeCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: ['--force'],
+  })
+  const force = args.includes('--force')
+  const bridge = createBridgeFromParsed(parsed)
+  const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+
+  try {
+    try {
+      const sims = await bridge.listSims()
+      const target = resolveTargetSim(sims, parsed.positional[0] || parsed.simId)
+      // `use`/`focus` retarget the CLI at a sim — silently grabbing one a
+      // human is actively driving is the same footgun `claim` guards against,
+      // so honor the lock here too (this command historically did not, which
+      // let `rnx use <id>` steal the user's live tab).
+      if (target.lockedBy && target.lockExpiresAt && target.lockExpiresAt > Date.now()) {
+        const secs = Math.max(0, Math.round((target.lockExpiresAt - Date.now()) / 1000))
+        if (target.lockedByKind === 'user-active') {
+          // the active human is interacting with this tab. never steal it,
+          // even with --force — mirrors `claim`, which refuses to even
+          // report a user-active takeover. open a fresh sim instead.
+          console.error(
+            `  refused: ${target.id} is locked by the active user (${secs}s) — that's a live human tab`,
+          )
+          console.error(`  run \`rnx open --new\` for a fresh investigation sim`)
+          rnxExit(1)
+        }
+        if (!force) {
+          // another CLI agent leases it. don't hijack its target silently;
+          // a cli lease is short (60s, refreshes per command) so this is
+          // usually a real conflict, not a stale lock.
+          console.error(
+            `  refused: ${target.id} is leased by ${target.lockedBy} (${secs}s)`,
+          )
+          console.error(
+            `  \`rnx use ${target.id} --force\` to take it, or \`rnx open --new\` for a fresh sim`,
+          )
+          rnxExit(1)
+        }
+      }
+      await bridge.focusSim(target.id)
+      saveCurrentSimId(target.id)
+      console.log(`  using: ${target.id}`)
+    } catch (err) {
+      rethrowIfExit(err)
+      console.error(`  use failed: ${err instanceof Error ? err.message : String(err)}`)
+      await printBridgeFailureDiagnostics(bridge, {
+        errorsCommand: `rnx get errors 5${simHint}`,
+        warningsCommand: `rnx get warnings 5${simHint}`,
+        requestsCommand: `rnx get requests 5${simHint}`,
+      })
+      rnxExit(1)
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+export async function runUseCommand(args: string[], opts: ControlCommandOptions = {}) {
+  await runUseLikeCommand(args, opts)
+}
+
+export async function runFocusCommand(args: string[], opts: ControlCommandOptions = {}) {
+  await runUseLikeCommand(args, opts)
+}
+
+export async function runClaimCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: ['--force'],
+  })
+  const force = args.includes('--force')
+  const bridge = createBridgeFromParsed(parsed)
+
+  try {
+    try {
+      const sims = await bridge.listSims()
+      const target = resolveTargetSim(sims, parsed.positional[0] || parsed.simId)
+      const priorHolder =
+        force && target.lockedBy && target.lockedByKind !== 'user-active'
+          ? target.lockedBy
+          : null
+      const result = await bridge.claim(target.id, { force })
+      saveCurrentSimId(target.id)
+      const ttl = Math.max(0, Math.round((result.lockExpiresAt - Date.now()) / 1000))
+      const booted = result.bootedCount > 0 ? ` (booted ${result.bootedCount})` : ''
+      console.log(`  claimed: ${result.simId} [${ttl}s]${booted}`)
+      if (priorHolder) {
+        console.log(`  took over from: ${priorHolder}`)
+      }
+    } catch (err) {
+      if (err instanceof BridgeSimLockedError) {
+        const secs = Math.max(0, Math.round(err.lock.expiresInMs / 1000))
+        console.error(`  claim failed: locked by ${err.lock.by} for ${secs}s more`)
+        console.error(`  use --force to take it, or \`rnx open --new\` for a fresh sim`)
+        rnxExit(1)
+      }
+      console.error(`  claim failed: ${err instanceof Error ? err.message : String(err)}`)
+      rnxExit(1)
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+// close many sims at once. fires every close, then polls listSims until the
+// whole set is gone or the timeout elapses — far faster than awaiting
+// waitForSimGone serially when clearing dozens of leaked sims.
+export async function closeSimsBulk(
+  bridge: ReturnType<typeof createBridgeFromParsed>,
+  wsPort: number,
+  commandTimeoutMs: number,
+  ids: string[],
+): Promise<{ closed: string[]; remaining: string[] }> {
+  if (ids.length === 0) return { closed: [], remaining: [] }
+  await Promise.all(ids.map((id) => bridge.closeSim(id).catch(() => {})))
+  const wanted = new Set(ids)
+  for (let i = 0; i < 40; i++) {
+    let stillOpen: string[] = []
+    try {
+      const probe = createBridge(wsPort, { commandTimeoutMs })
+      try {
+        const sims = await probe.listSims()
+        stillOpen = sims
+          .filter((s) => wanted.has(s.id) && s.readyState === 'open')
+          .map((s) => s.id)
+      } finally {
+        probe.close()
+      }
+    } catch {
+      stillOpen = []
+    }
+    if (stillOpen.length === 0) {
+      return { closed: [...wanted], remaining: [] }
+    }
+    if (i === 39) {
+      return {
+        closed: [...wanted].filter((id) => !stillOpen.includes(id)),
+        remaining: stillOpen,
+      }
+    }
+    await sleep(250)
+  }
+  return { closed: [...wanted], remaining: [] }
+}
+
+export interface BulkCloseRefusal {
+  id: string
+  lockedBy: string
+  kind: 'cli' | 'user-active'
+  expiresInMs: number
+}
+
+export interface BulkClosePlan {
+  openIds: string[]
+  keepId: string | null
+  targets: string[]
+  staleSavedId: string | null
+  missingExplicitKeepId: string | null
+  fallbackKeepId: string | null
+  refused: BulkCloseRefusal[]
+}
+
+export function planBulkCloseTargets(
+  sims: BridgeSimInfo[],
+  opts: {
+    closeOthers: boolean
+    explicitKeepId?: string
+    savedKeepId?: string | null
+    force?: boolean
+    now?: number
+  },
+): BulkClosePlan {
+  const open = sims.filter((sim) => sim.readyState === 'open')
+  const openIds = open.map((sim) => sim.id)
+  const explicitKeepId = opts.explicitKeepId?.trim() || ''
+  const savedKeepId = opts.savedKeepId?.trim() || ''
+  const savedIsOpen = savedKeepId ? open.some((sim) => sim.id === savedKeepId) : false
+  const staleSavedId = savedKeepId && !savedIsOpen ? savedKeepId : null
+  let keepId: string | null = null
+  let missingExplicitKeepId: string | null = null
+  let fallbackKeepId: string | null = null
+
+  if (opts.closeOthers) {
+    if (explicitKeepId) {
+      const match = open.find((sim) => sim.id === explicitKeepId)
+      if (match) {
+        keepId = match.id
+      } else {
+        missingExplicitKeepId = explicitKeepId
+      }
+    } else if (savedKeepId && savedIsOpen) {
+      keepId = savedKeepId
+    } else {
+      const fallback = open.find((sim) => sim.isPrimary) ?? open[0] ?? null
+      if (fallback) {
+        keepId = fallback.id
+        if (savedKeepId && !savedIsOpen) fallbackKeepId = fallback.id
+      }
+    }
+  }
+
+  // a sim another agent holds is not ours to close. `use`/`focus`/`claim` all
+  // refuse a live lease; bulk close historically did not look at leases at
+  // all, so `close --all` silently killed other agents' sims mid-capture.
+  const now = opts.now ?? Date.now()
+  const refused: BulkCloseRefusal[] = []
+  for (const sim of open) {
+    if (sim.id === keepId) continue
+    const lockedBy = sim.lockedBy
+    const expiresAt = sim.lockExpiresAt
+    if (!lockedBy || !expiresAt || expiresAt <= now || sim.lockedByMe) continue
+    const kind = sim.lockedByKind ?? 'cli'
+    // --force takes over another agent's cli lease, the same escape hatch
+    // `use --force` offers. a `user-active` lease is a live human tab and is
+    // never closable, matching `claim`, which refuses to report a takeover.
+    if (kind === 'cli' && opts.force) continue
+    refused.push({
+      id: sim.id,
+      lockedBy,
+      kind,
+      expiresInMs: Math.max(0, expiresAt - now),
+    })
+  }
+  const refusedIds = new Set(refused.map((entry) => entry.id))
+
+  return {
+    openIds,
+    keepId,
+    targets: missingExplicitKeepId
+      ? []
+      : openIds.filter((id) => id !== keepId && !refusedIds.has(id)),
+    staleSavedId,
+    missingExplicitKeepId,
+    fallbackKeepId,
+    refused,
+  }
+}
+
+export async function runCloseCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: ['--all', '--others', '--force'],
+  })
+  const bridge = createBridgeFromParsed(parsed)
+  const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+  const closeAll = args.includes('--all')
+  const closeOthers = args.includes('--others')
+  const force = args.includes('--force')
+
+  if (closeAll || closeOthers) {
+    try {
+      const sims = await bridge.listSims()
+      const savedId = readCurrentSimId()
+      const explicitKeepId =
+        parsed.positional[0] || (parsed.simIdSource === 'flag' ? parsed.simId : undefined)
+      // `--others` keeps the explicitly-targeted sim, else the saved/current
+      // sim, else primary. if an explicit keep target is gone, abort instead
+      // of treating "keep nothing" as permission to close every open sim.
+      const plan = planBulkCloseTargets(sims, {
+        closeOthers,
+        explicitKeepId,
+        savedKeepId: savedId,
+        force,
+      })
+      for (const entry of plan.refused) {
+        const secs = Math.round(entry.expiresInMs / 1000)
+        console.error(
+          entry.kind === 'user-active'
+            ? `  skipped: ${entry.id} is locked by the active user (${secs}s) — that's a live human tab`
+            : `  skipped: ${entry.id} is leased by ${formatLockOwner(entry.lockedBy)} (${secs}s)`,
+        )
+      }
+      if (plan.refused.some((entry) => entry.kind === 'cli') && !force) {
+        console.error(`  \`rnx close --all --force\` to close leased sims too`)
+      }
+      if (plan.staleSavedId) {
+        clearCurrentSimId()
+      }
+      if (plan.fallbackKeepId) {
+        saveCurrentSimId(plan.fallbackKeepId)
+        console.log(
+          `  saved sim ${plan.staleSavedId} is gone — keeping primary ${plan.fallbackKeepId}`,
+        )
+      }
+      if (plan.missingExplicitKeepId) {
+        console.error(
+          `  close failed: keep sim ${plan.missingExplicitKeepId} is not connected; not closing other sims`,
+        )
+        rnxExit(1)
+      }
+      if (plan.targets.length === 0) {
+        console.log(
+          plan.keepId
+            ? `  nothing to close — only the kept sim ${plan.keepId} is connected`
+            : plan.refused.length > 0
+              ? `  nothing to close — every other connected sim is leased by someone else`
+              : plan.staleSavedId
+                ? `  nothing to close — no sims connected (cleared stale current sim ${plan.staleSavedId})`
+                : '  nothing to close — no sims connected',
+        )
+        return
+      }
+      const result = await closeSimsBulk(
+        bridge,
+        parsed.wsPort,
+        parsed.commandTimeoutMs,
+        plan.targets,
+      )
+      await terminatePlaywrightHostsForSims(sims, plan.targets)
+      // saved current sim may have just been closed — repoint or clear it.
+      const nextSavedId = readCurrentSimId()
+      if (nextSavedId && result.closed.includes(nextSavedId)) {
+        if (plan.keepId) saveCurrentSimId(plan.keepId)
+        else clearCurrentSimId()
+      }
+      const summary = `  closed ${result.closed.length} sim(s)${
+        plan.keepId ? ` (kept ${plan.keepId})` : ''
+      }`
+      console.log(summary)
+      if (result.remaining.length > 0) {
+        console.error(`  close failed: still connected: ${result.remaining.join(', ')}`)
+        rnxExit(1)
+      }
+    } catch (err) {
+      rethrowIfExit(err)
+      console.error(`  close failed: ${err instanceof Error ? err.message : String(err)}`)
+      rnxExit(1)
+    } finally {
+      bridge.close()
+    }
+    return
+  }
+
+  try {
+    try {
+      const sims = await bridge.listSims()
+      const target = resolveTargetSim(sims, parsed.positional[0] || parsed.simId)
+      const fallbackTarget = sims.find(
+        (sim) => sim.id !== target.id && sim.readyState === 'open',
+      )
+      await bridge.closeSim(target.id)
+      const closed = await waitForSimGone(
+        parsed.wsPort,
+        parsed.commandTimeoutMs,
+        target.id,
+      )
+      if (!closed) {
+        await terminatePlaywrightHostsForSims(sims, [target.id])
+        console.error(`  close failed: ${target.id} is still connected`)
+        rnxExit(1)
+      }
+      await terminatePlaywrightHostsForSims(sims, [target.id])
+      if (readCurrentSimId() === target.id) {
+        if (fallbackTarget) saveCurrentSimId(fallbackTarget.id)
+        else clearCurrentSimId()
+      }
+      console.log(`  closed: ${target.id}`)
+    } catch (err) {
+      rethrowIfExit(err)
+      console.error(`  close failed: ${err instanceof Error ? err.message : String(err)}`)
+      await printBridgeFailureDiagnostics(bridge, {
+        errorsCommand: `rnx get errors 5${simHint}`,
+        warningsCommand: `rnx get warnings 5${simHint}`,
+        requestsCommand: `rnx get requests 5${simHint}`,
+      })
+      rnxExit(1)
+    }
+  } finally {
+    bridge.close()
+  }
+}