rnxsim 0.1.313 → 0.1.314

package/cli/commands/control.ts

@@ -0,0 +1,2142 @@
+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 { isLoopbackHost } from '../../src/backend-origin'
+import { resolveSootsimShellBaseUrlForBridgePort } from '../../src/bridge-constants'
+import {
+  applySootSimConfigToUrl,
+  mergeSootSimConfig,
+  type SootSimConfig,
+} from '../../src/config'
+import {
+  resolveConnectionInput,
+  type ResolvedDevBundle,
+} from '../../src/dev-bundle-resolution'
+import {
+  isDaemonLockfileFresh,
+  readActiveRuntime,
+  readDaemonLockfile,
+  readLiveRuntimeVersions,
+  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 { sootsimRuntime } from '../../src/runtime-delivery'
+import { loadSootSimAppConfig } 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 {
+  BridgeSimLockedError,
+  bridgePortForShellBaseUrl,
+  createBridge,
+  createBridgeFromParsed,
+  parseBridgeCliArgs,
+  printBridgeWorldNotice,
+  resolveBridgeWorld,
+  worldForBridgePort,
+  type BridgeSimInfo,
+} from '../ws-bridge'
+import { WAIT_READY_PROBE, readyProbeHasContent, type ReadyProbe } from './inspect/core'
+import type { DriverId, DriverLaunchResult } from '../drivers/types'
+
+interface ControlCommandOptions {
+  port?: number
+  timeoutMs?: number
+}
+
+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()
+}
+
+const DEEP_LINK_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/
+
+export function normalizeDeepLinkTarget(target: string): string {
+  const trimmed = target.trim()
+  if (!trimmed) {
+    throw new Error('expected <url-or-route>')
+  }
+  if (DEEP_LINK_SCHEME_RE.test(trimmed) || trimmed.startsWith('/')) {
+    return trimmed
+  }
+  return `/${trimmed}`
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+}
+
+function shouldOpenAsDeepLink(target: string): boolean {
+  const trimmed = target.trim()
+  if (!trimmed) return false
+  if (trimmed.startsWith('/')) return true
+  if (!DEEP_LINK_SCHEME_RE.test(trimmed)) return false
+  return !/^https?:\/\//i.test(trimmed)
+}
+
+export async function ensureBridgeForOpen(
+  preferredPort: number,
+  explicitPort = false,
+): Promise<number> {
+  if (await canConnectToBridge(preferredPort, 250)) return preferredPort
+
+  const lock = readDaemonLockfile()
+  assertExplicitBridgeLock(preferredPort, explicitPort, lock)
+  if (
+    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 \`rnxsim daemon restart\` or \`rnxsim 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)
+    if (
+      nextLock &&
+      isDaemonLockfileFresh(nextLock) &&
+      (await canConnectToBridge(nextLock.bridgePort, 250))
+    ) {
+      console.error(
+        `  started local bridge on port ${nextLock.bridgePort}; run \`sootsim setup\` to install the background daemon`,
+      )
+      return nextLock.bridgePort
+    }
+    if (await canConnectToBridge(preferredPort, 250)) {
+      console.error(
+        `  started local bridge on port ${preferredPort}; run \`sootsim setup\` to install the background daemon`,
+      )
+      return preferredPort
+    }
+    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
+  }
+  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 SOOTSIM_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 entry = process.argv[1]
+  if (entry && fs.existsSync(entry)) {
+    return spawn(process.execPath, [entry, ...args], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    })
+  }
+  return spawn(rnxPublicBrand.commandName, 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()
+}
+
+// SootSim share/preview/build links (e.g. https://sootsim.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 `sootsim 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
+  }
+}
+
+async function resolveConnectionInputForCli(target: string): Promise<ResolvedDevBundle> {
+  const normalized = normalizeKnownTarget(target)
+  const registeredPort = /^\d+$/.test(normalized)
+    ? Number(normalized)
+    : localBasePort(normalized)
+
+  if (registeredPort && registeredPort > 0) {
+    const discovered = await probePort(registeredPort)
+    if (discovered) {
+      return {
+        bundleUrl: discovered.bundleUrl,
+        port: discovered.port,
+        framework: discovered.framework,
+        projectName: discovered.projectName,
+      }
+    }
+  }
+
+  return resolveConnectionInput(normalized)
+}
+
+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[]): SootSimConfig | undefined {
+  const modules: NonNullable<SootSimConfig['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('  rnxsim open: --replace expects <module>=<file>')
+        process.exit(1)
+      }
+      const eqIndex = raw.indexOf('=')
+      if (eqIndex <= 0 || eqIndex === raw.length - 1) {
+        console.error('  rnxsim open: --replace expects <module>=<file>')
+        process.exit(1)
+      }
+      const moduleName = raw.slice(0, eqIndex).trim()
+      const filePath = normalizeReplacementPath(raw.slice(eqIndex + 1).trim())
+      if (!fs.existsSync(filePath)) {
+        console.error(`  rnxsim open: replacement file not found: ${filePath}`)
+        process.exit(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('  rnxsim open: --remap expects <host:port>=<host:port>')
+        process.exit(1)
+      }
+      remap[raw.slice(0, eqIndex).trim()] = raw.slice(eqIndex + 1).trim()
+      i++
+      continue
+    }
+  }
+
+  const config: SootSimConfig = {}
+  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 resolveOpenAppProject(
+  resolvedBundle?: ResolvedDevBundle,
+): Promise<ResolvedAppProject | null> {
+  if (resolvedBundle) {
+    const advertisedRoot = await resolveMetroProjectRoot(resolvedBundle.bundleUrl)
+    if (advertisedRoot) {
+      return resolveAppProject(advertisedRoot, { trustStart: true })
+    }
+  }
+  return resolveAppProject(process.env.CONTRAST_REPO_DIR || process.cwd())
+}
+
+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 sootsimRuntime.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) return urlStr
+    // the dev server's project root identifies the exact app in a monorepo.
+    // CONTRAST_REPO_DIR is only the fallback for servers that do not advertise
+    // their root.
+    const repoDir =
+      project?.appDir ?? (await resolveMetroProjectRoot(bundleUrl)) ?? undefined
+    const specs = discoverNativeLinkedAppFonts({
+      bundleUrl,
+      repoDir,
+      exactProjectDir: !!project || !!repoDir,
+    })
+    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)) {
+    return new URL(target).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) return urlStr
+    const repoDir =
+      project?.appDir ?? (await resolveMetroProjectRoot(bundleUrl)) ?? undefined
+    const spec = discoverConfigPluginAppSplash({
+      bundleUrl,
+      repoDir,
+      exactProjectDir: !!project || !!repoDir,
+    })
+    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
+}
+
+export async function buildShellUrl(
+  target: string,
+  baseUrl: string = resolveDefaultShellBaseUrl(),
+  opts: BuildShellUrlOptions = {},
+): Promise<string> {
+  const resolved = await resolveShellUrl(target, baseUrl, opts)
+  const stamped = await stampAppSplash(
+    await stampAppFonts(resolved, opts.project),
+    opts.project,
+  )
+  if (!opts.device) return stamped
+  const url = new URL(stamped)
+  url.searchParams.set('device', opts.device)
+  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
+  } = {},
+) {
+  const attempts = opts.attempts ?? 30
+  const intervalMs = opts.intervalMs ?? 500
+  const minNodeCount = opts.minNodeCount ?? 10
+
+  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()) || 0)()',
+      })
+      if (typeof count === 'number' && count > minNodeCount) {
+        return { bridge, count }
+      }
+    } catch {
+      // still loading or disconnected
+    }
+    bridge.close()
+    await sleep(intervalMs)
+  }
+
+  return null
+}
+
+// returns a short, human-friendly description of what a sim is showing —
+// e.g. "bundle host/...path", "connect :8081", "demo bluesky". returns null
+// when there's no useful summary beyond the raw URL itself, so the caller
+// can skip the redundant `loaded:` line in that case.
+export function summarizeSimUrl(url: string | undefined): string | null {
+  if (!url) return null
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('bundle')) {
+      const bundleUrl = parsed.searchParams.get('bundle') || ''
+      try {
+        const bundle = new URL(bundleUrl)
+        const shortPath =
+          bundle.pathname.length > 36
+            ? `...${bundle.pathname.slice(-36)}`
+            : bundle.pathname
+        return `bundle ${bundle.host}${shortPath}`
+      } catch {
+        return 'bundle'
+      }
+    }
+    if (parsed.searchParams.has('port')) {
+      return `connect :${parsed.searchParams.get('port') || ''}`
+    }
+    if (parsed.searchParams.has('open')) {
+      return `connect ${parsed.searchParams.get('open') || ''}`
+    }
+    if (parsed.searchParams.has('demo')) {
+      return `demo ${parsed.searchParams.get('demo') || 'default'}`
+    }
+    if (
+      parsed.pathname.includes('/sootsim/index.html') ||
+      parsed.pathname === '/sootsim/' ||
+      parsed.pathname === '/sootsim'
+    ) {
+      return 'embedded rnx'
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+// a lock owner is either a friendly cli label ("active user") or a raw cli
+// identity key ("CLAUDE_CODE_SESSION_ID:<uuid>", "gppid-1234"). keep the list
+// readable by collapsing a "<source>:<value>" identity to a short form that
+// still says which agent holds it.
+function formatLockOwner(owner: string): string {
+  const colon = owner.indexOf(':')
+  if (colon <= 0) return owner.length > 24 ? `${owner.slice(0, 21)}…` : owner
+  const source = owner.slice(0, colon)
+  const value = owner.slice(colon + 1)
+  const short = value.length > 12 ? `${value.slice(0, 8)}…` : value
+  if (
+    source === 'TM_SESSION' ||
+    source === 'CLAUDE_CODE_SESSION_ID' ||
+    source === 'CODEX_THREAD_ID'
+  ) {
+    return `agent ${short}`
+  }
+  return `${source} ${short}`
+}
+
+export function printConnectedSims(sims: BridgeSimInfo[], selectedId?: string) {
+  if (sims.length === 0) {
+    console.log('  no sims connected')
+    return
+  }
+  console.log(`  connected sims (${sims.length}):\n`)
+  for (const sim of sims) {
+    const lockTag =
+      sim.lockedBy && sim.lockExpiresAt
+        ? `locked by ${formatLockOwner(sim.lockedBy)} (${Math.max(0, Math.round((sim.lockExpiresAt - Date.now()) / 1000))}s)`
+        : ''
+    const tags = [
+      sim.isPrimary ? 'primary' : '',
+      sim.id === selectedId ? 'selected' : '',
+      sim.readyState,
+      sim.userVisible === false ? 'hidden' : sim.userVisible === true ? 'visible' : '',
+      sim.attachedCliCount && sim.attachedCliCount > 0 ? 'in use' : '',
+      sim.userFocused ? 'focused' : '',
+      lockTag,
+    ].filter(Boolean)
+    console.log(`  ${sim.id}${tags.length ? ` [${tags.join(', ')}]` : ''}`)
+    const loaded = summarizeSimUrl(sim.url)
+    if (loaded) {
+      console.log(`    loaded: ${loaded}`)
+    } else if (sim.url) {
+      // no friendly summary — show the raw url so the caller can still copy it.
+      // truncate aggressively so a 400-char metro url doesn't dominate the list.
+      const shown = sim.url.length > 96 ? `${sim.url.slice(0, 93)}…` : sim.url
+      console.log(`    url: ${shown}`)
+    } else if (sim.origin) {
+      console.log(`    origin: ${sim.origin}`)
+    }
+    const engine = describeEngineSource(sim)
+    if (engine) console.log(`    engine: ${engine}`)
+    if (sim.title) console.log(`    title: ${sim.title}`)
+    if (sim.visibilityState && sim.visibilityState !== 'visible') {
+      console.log(`    visibility: ${sim.visibilityState}`)
+    }
+    console.log(`    connected: ${formatRelativeAge(Date.now() - sim.connectedAt)}`)
+    if (sim.lastActiveAt && sim.lastActiveAt > 0) {
+      console.log(`    last active: ${formatRelativeAge(Date.now() - sim.lastActiveAt)}`)
+    }
+  }
+}
+
+// classify which engine a sim is running so dev-vs-published is never ambiguous
+// to agents or humans reading `sootsim list`. dev shell serves local source on
+// :5173; the Contrast app embeds sootsim on :3000; the bridge/daemon and the
+// /__soot plugin serve the active runtime dir — which, inside a dev checkout, is
+// the fresh dev-stack build (resolveDevCheckoutRuntimeRoot mode boundary), not a
+// published runtime. keep this label honest so it never says "published" while
+// actually serving local build output.
+function describeEngineSource(sim: { url?: string; origin?: string }): string | null {
+  const ref = sim.url || sim.origin || ''
+  if (!ref) return null
+  try {
+    const port = new URL(ref).port
+    if (port === '5173') return 'dev — local source (:5173)'
+    if (port === '3000') return 'Contrast app embedded (:3000)'
+    if (resolveDevCheckoutRuntimeRoot()) return `dev — local build (:${port || '?'})`
+    return `runtime — published engine (:${port || '?'})`
+  } catch {
+    return null
+  }
+}
+
+function formatRelativeAge(ms: number): string {
+  const sec = Math.max(0, Math.round(ms / 1000))
+  if (sec < 60) return `${sec}s ago`
+  if (sec < 3600) return `${Math.round(sec / 60)}m ago`
+  if (sec < 86400) return `${Math.round(sec / 3600)}h ago`
+  return `${Math.round(sec / 86400)}d ago`
+}
+
+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 `sootsim 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
+// sootsim 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')
+}
+
+function printOpenedSim(
+  openUrl: string,
+  sim: BridgeSimInfo,
+  mode:
+    | 'desktop companion'
+    | 'bridge'
+    | 'direct shell open'
+    | 'current sim'
+    | `${string} driver`,
+) {
+  console.log(`  ${mode === 'current sim' ? 'loaded' : 'opened'}: ${openUrl} [${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: sim.url }, 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 `sootsim 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 `sootsim 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: ReadyProbe | null = null
+      try {
+        readyProbe = (await bridge.send({
+          type: 'evaluate',
+          code: WAIT_READY_PROBE,
+        })) as ReadyProbe | null
+      } catch {}
+      if (readyProbe) {
+        const readyEnough =
+          readyProbe.flag === true &&
+          !readyProbe.loadingText &&
+          readyProbeHasContent(readyProbe)
+        if (!readyEnough) {
+          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: rnxsim wait ready --max-ms 120000')
+        }
+      }
+      const dumpOpts = { describe: true, verbose: false, filter: '' }
+      const code = `(async () => {
+        const t = window.__sootsimTest
+        const ms = window.SootSim?.bridges?.mainShell
+        if (!t) return null
+        let shell = null
+        try { shell = ms?.getState ? await ms.getState() : null } catch {}
+        const tree = await t.dumpTree(12, ${JSON.stringify(dumpOpts)})
+        return { tree, shell }
+      })()`
+      const result = (await bridge.send({ type: 'evaluate', code })) as {
+        tree: string | null
+        shell: { state?: string; activeApp?: string } | null
+      } | null
+      if (!result?.tree) return
+      console.log('')
+      if (result.shell?.state) {
+        const parts = [
+          `state=${result.shell.state}`,
+          result.shell.activeApp ? `app=${result.shell.activeApp}` : null,
+        ].filter(Boolean)
+        console.log(`  shell: ${parts.join(' ')}`)
+      }
+      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('  rnxsim open: expected exactly one <url-or-route>')
+    console.error('  examples: rnxsim open /settings  |  rnxsim open myapp://settings')
+    process.exit(1)
+  }
+
+  let target: string
+  try {
+    target = normalizeDeepLinkTarget(parsed.positional[0] ?? '')
+  } catch (err) {
+    console.error(`  rnxsim open: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(1)
+  }
+
+  const bridge = createBridgeFromParsed(parsed)
+  const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+  try {
+    const result = await bridge.send({
+      type: 'call',
+      path: 'SootSim.bridges.test.openDeepLink',
+      args: [target],
+    })
+    if (isObjectRecord(result) && result.ok === false) {
+      throw new Error(
+        typeof result.error === 'string' ? result.error : 'deep-link dispatch failed',
+      )
+    }
+    console.log(`  opened deep link: ${target}`)
+  } catch (err) {
+    console.error(`  link failed: ${err instanceof Error ? err.message : String(err)}`)
+    await printBridgeFailureDiagnostics(bridge, {
+      errorsCommand: `rnxsim get errors 5${simHint}`,
+      warningsCommand: `rnxsim get warnings 5${simHint}`,
+      requestsCommand: `rnxsim get requests 5${simHint}`,
+    })
+    process.exit(1)
+  } finally {
+    bridge.close()
+  }
+}
+
+export async function runOpenCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: [
+      '--new',
+      '--headless',
+      '--headed',
+      '--ephemeral',
+      '--hot',
+      '--no-hmr',
+      '--no-describe',
+    ],
+    stripValueFlags: [
+      '--base-url',
+      '--replace',
+      '--driver',
+      '--profile',
+      '--cdp-port',
+      '--device',
+      '--viewport',
+    ],
+  })
+  const requestedProfileId = args.find((_, i) => args[i - 1] === '--profile')
+  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(
+      `  rnxsim open: --cdp-port must be a positive port number, got "${cdpPortArg}"`,
+    )
+    process.exit(1)
+  }
+  if (requestedProfileId && ephemeralProfile) {
+    console.error('  rnxsim open: --profile cannot be combined with --ephemeral')
+    process.exit(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(
+      '  rnxsim open: --new, --profile, and --ephemeral cannot be combined with --sim',
+    )
+    process.exit(1)
+  }
+  const target = parsed.positional[0] || ''
+
+  if (shouldOpenAsDeepLink(target)) {
+    if (openInNewSim) {
+      console.error(
+        '  rnxsim open: deep links target the current app; remove --new, --profile, or --ephemeral',
+      )
+      process.exit(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 rnxsim 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}`)
+      process.exit(1)
+    }
+    console.log(
+      isLocal
+        ? '  to drive it under the CLI, point `rnxsim open` at the app’s dev port instead (e.g. `rnxsim 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 `rnxsim open <port>`.',
+    )
+    return
+  }
+
+  const resolvedBundle = shouldResolveBundleTargetInCli(target)
+    ? await resolveConnectionInputForCli(target)
+    : undefined
+  const project = await resolveOpenAppProject(resolvedBundle)
+  const appConfig = await loadSootSimAppConfig(project)
+  const configuredRuntimeVersion = appConfig?.runtimeVersion
+  const runtimeConfig = mergeSootSimConfig(
+    appConfig ? { ...appConfig, runtimeVersion: undefined } : undefined,
+    commandConfig,
+  )
+  if (configuredRuntimeVersion) {
+    await ensureConfiguredRuntime(configuredRuntimeVersion)
+  }
+
+  // keep the bridge port and the shell base URL in one world: an explicit
+  // --base-url without --port 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).
+  const explicitBaseUrl = args.find((_, i) => args[i - 1] === '--base-url')
+  if (explicitBaseUrl && !parsed.explicitPort) {
+    const matched = bridgePortForShellBaseUrl(explicitBaseUrl)
+    if (matched) parsed.wsPort = matched
+  }
+
+  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 \`rnxsim list --drivers\``,
+    )
+    process.exit(1)
+  }
+  const driverId: DriverId = isDriverId(requestedDriverId)
+    ? requestedDriverId
+    : 'playwright'
+  const driverHeadless = resolveDriverHeadless(args, driverId)
+  if (cdpPort && driverId !== 'playwright') {
+    console.error('  rnxsim open: --cdp-port is only honored by the playwright driver')
+    process.exit(1)
+  }
+
+  // metro HMR mode. interactive opens default to hot=true so edits hot-apply
+  // through sootsim's HmrClient — expo CLI's createBundleUrlSearchParams
+  // hardcodes hot=false on every launchAsset URL (a leftover toggle real iOS
+  // sims tolerate but sootsim 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('  rnxsim open: --hot and --no-hmr cannot be combined')
+    process.exit(1)
+  }
+  const hotMode = hotFlag ? true : noHmrFlag ? false : requestedDriverId !== '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(`  rnxsim open: unknown device "${deviceArg}"`)
+    console.error(`  known devices: ${listSelectableDeviceModels().join(', ')}`)
+    process.exit(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(
+      `  rnxsim open: --viewport must be <width>x<height>, got "${viewportArg}"`,
+    )
+    process.exit(1)
+  }
+  const explicitViewport = viewportMatch
+    ? { width: Number(viewportMatch[1]), height: Number(viewportMatch[2]) }
+    : undefined
+
+  const buildShellUrlOpts: BuildShellUrlOptions = {
+    hot: hotMode,
+    device: deviceArg,
+    resolvedBundle,
+    project,
+  }
+
+  // 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
+
+  if (shouldReuseCurrentSim) {
+    const bridge = createBridgeFromParsed(parsed)
+    const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+    let fallBackToNewSim = false
+
+    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,
+            applySootSimConfigToUrl(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)
+          const shellUrl =
+            targetShellUrl ??
+            (await buildShellUrl(
+              target,
+              applySootSimConfigToUrl(resolvedBaseUrl, runtimeConfig),
+              buildShellUrlOpts,
+            ))
+          bridge
+            .send({
+              type: 'evaluate',
+              simId: targetSim.id,
+              code: `window.location.href = ${JSON.stringify(shellUrl)}`,
+            })
+            .catch(() => {})
+        }
+      } catch (err) {
+        console.error(
+          `  open failed: ${err instanceof Error ? err.message : String(err)}`,
+        )
+        await printBridgeFailureDiagnostics(bridge, {
+          errorsCommand: `rnxsim get errors 5${simHint}`,
+          warningsCommand: `rnxsim get warnings 5${simHint}`,
+          requestsCommand: `rnxsim get requests 5${simHint}`,
+        })
+        process.exit(1)
+      }
+
+      if (!fallBackToNewSim && targetSim) {
+        await sleep(1500)
+        const ready = await waitForSimReady(
+          parsed.wsPort,
+          parsed.commandTimeoutMs,
+          targetSim.id,
+        )
+        if (!ready) {
+          console.error('  timed out waiting for current sim to load target')
+          process.exit(1)
+        }
+        ready.bridge.close()
+        saveCurrentSimId(targetSim.id)
+        const resolvedBaseUrl =
+          hasExplicitBaseUrl || looksLikeSootsimUrl(target)
+            ? baseUrl
+            : deriveCurrentSimBaseUrl(targetSim, baseUrl)
+        const shellUrl =
+          targetShellUrl ??
+          (await buildShellUrl(
+            target,
+            applySootSimConfigToUrl(resolvedBaseUrl, runtimeConfig),
+            buildShellUrlOpts,
+          ))
+        printOpenedSim(shellUrl, { ...targetSim, url: shellUrl }, 'current sim')
+        await maybeDescribeAfterOpen(parsed.wsPort, targetSim.id, args)
+        return
+      }
+    } finally {
+      bridge.close()
+    }
+  }
+
+  const configuredBaseUrl = applySootSimConfigToUrl(baseUrl, runtimeConfig)
+  const token = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+  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',
+    )
+    process.exit(1)
+  }
+  const simMatchesToken = (sim: BridgeSimInfo) =>
+    sim.url?.includes(`inspectOpen=${token}`) ?? false
+
+  const driver = getDriver(driverId)
+  if (!driver) {
+    console.error(`  unknown driver "${driverId}" — run \`rnxsim list --drivers\``)
+    process.exit(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 resolved bridge port so the
+    // page does not reconnect to a stale world.
+    bridgePort: bridgePortForShellBaseUrl(baseUrl) ?? 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}`)
+    process.exit(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`)
+    process.exit(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`,
+    )
+    process.exit(1)
+  }
+  const match = outcome.sim
+  saveCurrentSimId(match.id)
+  signalDriverLaunchConnected(result)
+  printOpenedSim(openUrl, match, `${driver.name} driver`)
+  await maybeDescribeAfterOpen(parsed.wsPort, match.id, args)
+}
+
+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 `sootsim 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 \`rnxsim open --new\` for a fresh investigation sim`)
+          process.exit(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(
+            `  \`sootsim use ${target.id} --force\` to take it, or \`rnxsim open --new\` for a fresh sim`,
+          )
+          process.exit(1)
+        }
+      }
+      await bridge.focusSim(target.id)
+      saveCurrentSimId(target.id)
+      console.log(`  using: ${target.id}`)
+    } catch (err) {
+      console.error(`  use failed: ${err instanceof Error ? err.message : String(err)}`)
+      await printBridgeFailureDiagnostics(bridge, {
+        errorsCommand: `rnxsim get errors 5${simHint}`,
+        warningsCommand: `rnxsim get warnings 5${simHint}`,
+        requestsCommand: `rnxsim get requests 5${simHint}`,
+      })
+      process.exit(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 \`rnxsim open --new\` for a fresh sim`,
+        )
+        process.exit(1)
+      }
+      console.error(`  claim failed: ${err instanceof Error ? err.message : String(err)}`)
+      process.exit(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 BulkClosePlan {
+  openIds: string[]
+  keepId: string | null
+  targets: string[]
+  staleSavedId: string | null
+  missingExplicitKeepId: string | null
+  fallbackKeepId: string | null
+}
+
+export function planBulkCloseTargets(
+  sims: BridgeSimInfo[],
+  opts: {
+    closeOthers: boolean
+    explicitKeepId?: string
+    savedKeepId?: string | null
+  },
+): 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
+      }
+    }
+  }
+
+  return {
+    openIds,
+    keepId,
+    targets: missingExplicitKeepId ? [] : openIds.filter((id) => id !== keepId),
+    staleSavedId,
+    missingExplicitKeepId,
+    fallbackKeepId,
+  }
+}
+
+export async function runCloseCommand(args: string[], opts: ControlCommandOptions = {}) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    commandTimeoutMs: opts.timeoutMs,
+    stripBooleanFlags: ['--all', '--others'],
+  })
+  const bridge = createBridgeFromParsed(parsed)
+  const simHint = parsed.simId ? ` --sim ${parsed.simId}` : ''
+  const closeAll = args.includes('--all')
+  const closeOthers = args.includes('--others')
+
+  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,
+      })
+      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`,
+        )
+        process.exit(1)
+      }
+      if (plan.targets.length === 0) {
+        console.log(
+          plan.keepId
+            ? `  nothing to close — only the kept sim ${plan.keepId} is connected`
+            : 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(', ')}`)
+        process.exit(1)
+      }
+    } catch (err) {
+      console.error(`  close failed: ${err instanceof Error ? err.message : String(err)}`)
+      process.exit(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`)
+        process.exit(1)
+      }
+      await terminatePlaywrightHostsForSims(sims, [target.id])
+      if (readCurrentSimId() === target.id) {
+        if (fallbackTarget) saveCurrentSimId(fallbackTarget.id)
+        else clearCurrentSimId()
+      }
+      console.log(`  closed: ${target.id}`)
+    } catch (err) {
+      console.error(`  close failed: ${err instanceof Error ? err.message : String(err)}`)
+      await printBridgeFailureDiagnostics(bridge, {
+        errorsCommand: `rnxsim get errors 5${simHint}`,
+        warningsCommand: `rnxsim get warnings 5${simHint}`,
+        requestsCommand: `rnxsim get requests 5${simHint}`,
+      })
+      process.exit(1)
+    }
+  } finally {
+    bridge.close()
+  }
+}