peachsim 0.1.527

package/cli/ws-bridge.ts

@@ -0,0 +1,1020 @@
+// rnx CLI ↔ sim WS bridge
+//
+// the rnx runtime opens a WebSocket server (default port 7668) that
+// accepts JSON commands like `{ type: 'evaluate', code: 'window.__sootsimTest.getNodeCount()' }`
+// or `{ type: 'call', path: 'SootSim.bridges.mainShell.launchApp', args: ['photos'] }`
+// and responds with `{ id, result }` or `{ id, error }`. CLI commands use
+// this to drive a running rnx instance from the terminal.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { WebSocket } from 'ws'
+import {
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+  resolveSootsimBridgePort,
+} from '../src/bridge-constants'
+import { DEFAULT_SOOTSIM_SHELL_URL } from '../src/cli-constants'
+import {
+  isDaemonLockfileFresh,
+  isDevBridgeLockfileFresh,
+  readDaemonLockfile,
+  readDevBridgeLockfiles,
+  rnxHomeDir,
+  type DevBridgeLockfile,
+} from '../src/home-paths'
+import { createCloudBridgeForParsed } from './cloud-client'
+import {
+  clearCurrentSimId,
+  getCliIdentity,
+  readCurrentSim,
+  readCurrentSimId,
+  saveCurrentSimId,
+} from './current-sim'
+
+// --- bridge world resolution ---------------------------------------------
+//
+// two bridge kinds can coexist on one machine: Vite dev-shell bridges
+// (~/.rnx/dev-bridges/<port>.json, shells served by Vite) and the installed
+// daemon runtime (~/.rnx/daemon.json, shell served by the daemon's own
+// http server). every default — the ws port a command connects to AND the
+// shell base URL `open` builds its page from — must come from the SAME
+// world, or `open` polls one bridge while the sim registers on the other
+// (the 125s-timeout split-brain bug). resolveBridgeWorld is the single
+// source of that decision: an invocation's explicit offset wins, then its
+// checkout's dev bridge, then the canonical dev bridge, a fresh daemon, and
+// finally hardcoded defaults.
+
+export interface BridgeWorld {
+  source: 'dev-bridge' | 'daemon' | 'default'
+  bridgePort: number
+  shellBaseUrl: string
+}
+
+// where this invocation is running. the same rnx commands work in four
+// places, and the placement is what a command consults instead of growing a
+// second spelling per place. host and local-box share one transport today —
+// a local box mounts this machine's checkout and drives this machine's
+// bridge — so they differ in what is allowed, not in where packets go. a
+// cloud box is the one that moves the endpoint, and it does not exist yet.
+export type RnxPlacement = 'host' | 'local-box' | 'cloud-box'
+
+// set by `rnx box` on the shell's child processes. the box is the only thing
+// that may set it; nothing infers a placement from cwd or heuristics.
+export const RNX_PLACEMENT_ENV = 'RNX_PLACEMENT'
+
+export function resolvePlacement(): RnxPlacement {
+  return process.env[RNX_PLACEMENT_ENV] === 'local-box' ? 'local-box' : 'host'
+}
+
+/** the ws endpoint a command connects to. the single place a bridge URL is
+ *  formed, so a cloud box changes this function rather than every call site.
+ *  host and local-box both drive this machine's bridge.
+ *
+ *  changing what this returns changes real egress, and the outbound inventory
+ *  declares the CALL EXPRESSION rather than the URL, so it cannot see through
+ *  this function. a cloud endpoint added here must get its own declaration in
+ *  `outbound-endpoints.ts` instead of inheriting the local_development one. */
+export function bridgeWsUrl(wsPort: number): string {
+  return `ws://127.0.0.1:${wsPort}`
+}
+
+// resolved once per CLI process so a multi-step command keeps one world for
+// its entire invocation. separate CLI calls make the same deterministic choice
+// from the owner-scoped dev records instead of following whichever heartbeat
+// happened to run last.
+let resolvedWorld: { homeDir: string; world: BridgeWorld } | null = null
+
+function liveDevBridgeLockfiles(): DevBridgeLockfile[] {
+  return readDevBridgeLockfiles().filter((lockfile) => isDevBridgeLockfileFresh(lockfile))
+}
+
+function checkoutRoot(cwd: string): string | null {
+  let current = path.resolve(cwd)
+  while (true) {
+    if (fs.existsSync(path.join(current, '.git'))) return current
+    const parent = path.dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+function pathContains(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child)
+  return (
+    relative === '' ||
+    (relative !== '..' &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  )
+}
+
+function resolveDefaultDevBridgeLockfile(): DevBridgeLockfile | null {
+  const lockfiles = liveDevBridgeLockfiles()
+  if (lockfiles.length === 0) return null
+
+  if (
+    process.env.SOOTSIM_BRIDGE_PORT !== undefined ||
+    process.env.PORT_OFFSET !== undefined
+  ) {
+    const requestedPort = resolveSootsimBridgePort({
+      explicitPort: process.env.SOOTSIM_BRIDGE_PORT,
+      portOffset: process.env.PORT_OFFSET,
+    })
+    const requested = lockfiles.find((lockfile) => lockfile.bridgePort === requestedPort)
+    if (requested) return requested
+  }
+
+  let cwd: string | null = null
+  try {
+    cwd = process.cwd()
+  } catch {}
+  if (cwd) {
+    const currentCheckout = checkoutRoot(cwd)
+    const sameCheckout = lockfiles.filter((lockfile) => {
+      const bridgeCheckout = checkoutRoot(lockfile.cwd)
+      if (currentCheckout && bridgeCheckout) return currentCheckout === bridgeCheckout
+      return pathContains(cwd, lockfile.cwd) || pathContains(lockfile.cwd, cwd)
+    })
+    if (sameCheckout.length > 0) {
+      return (
+        sameCheckout.find(
+          (lockfile) => lockfile.bridgePort === DEFAULT_SOOTSIM_BRIDGE_PORT,
+        ) ?? sameCheckout[0]
+      )
+    }
+  }
+
+  return (
+    lockfiles.find((lockfile) => lockfile.bridgePort === DEFAULT_SOOTSIM_BRIDGE_PORT) ??
+    lockfiles[0]
+  )
+}
+
+export function resolveBridgeWorld(): BridgeWorld {
+  const homeDir = rnxHomeDir()
+  if (resolvedWorld?.homeDir === homeDir) return resolvedWorld.world
+  const world = resolveBridgeWorldFresh()
+  resolvedWorld = { homeDir, world }
+  return world
+}
+
+function resolveBridgeWorldFresh(): BridgeWorld {
+  const dev = resolveDefaultDevBridgeLockfile()
+  if (dev) {
+    return {
+      source: 'dev-bridge',
+      bridgePort: dev.bridgePort,
+      // older lockfile writers don't record the vite http port; the default
+      // shell URL is the dev shell anyway, so the fallback stays coherent.
+      shellBaseUrl: dev.shellPort
+        ? `http://localhost:${dev.shellPort}/`
+        : DEFAULT_SOOTSIM_SHELL_URL,
+    }
+  }
+  const lock = readDaemonLockfile()
+  if (lock && isDaemonLockfileFresh(lock)) {
+    return {
+      source: 'daemon',
+      bridgePort: lock.bridgePort,
+      shellBaseUrl:
+        lock.runtimePort > 0
+          ? `http://localhost:${lock.runtimePort}/`
+          : DEFAULT_SOOTSIM_SHELL_URL,
+    }
+  }
+  return {
+    source: 'default',
+    bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+    shellBaseUrl: DEFAULT_SOOTSIM_SHELL_URL,
+  }
+}
+
+/** the world a specific bridge port belongs to, or null when no fresh
+ *  lockfile claims it. lets `open --port 7669` derive the daemon's shell
+ *  base URL instead of mixing worlds. */
+export function worldForBridgePort(
+  port: number,
+): { source: 'dev-bridge' | 'daemon'; shellBaseUrl: string } | null {
+  const dev = liveDevBridgeLockfiles().find((lockfile) => lockfile.bridgePort === port)
+  if (dev) {
+    return {
+      source: 'dev-bridge',
+      shellBaseUrl: dev.shellPort
+        ? `http://localhost:${dev.shellPort}/`
+        : DEFAULT_SOOTSIM_SHELL_URL,
+    }
+  }
+  const lock = readDaemonLockfile()
+  if (lock && isDaemonLockfileFresh(lock) && lock.bridgePort === port) {
+    return {
+      source: 'daemon',
+      shellBaseUrl:
+        lock.runtimePort > 0
+          ? `http://localhost:${lock.runtimePort}/`
+          : DEFAULT_SOOTSIM_SHELL_URL,
+    }
+  }
+  return null
+}
+
+/** the bridge port of the world that serves a given shell base URL, or null
+ *  when no fresh lockfile claims it. lets `open --base-url` (without --port)
+ *  poll the bridge that actually belongs to that shell. */
+export function bridgePortForShellBaseUrl(baseUrl: string): number | null {
+  let port: number
+  try {
+    const url = new URL(baseUrl)
+    port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80
+  } catch {
+    return null
+  }
+  if (!Number.isFinite(port) || port <= 0) return null
+  const dev = liveDevBridgeLockfiles().find(
+    (lockfile) =>
+      lockfile.shellPort === port ||
+      lockfile.runtimePort === port ||
+      lockfile.bridgePort === port,
+  )
+  if (dev) {
+    return dev.bridgePort
+  }
+  const lock = readDaemonLockfile()
+  if (
+    lock &&
+    isDaemonLockfileFresh(lock) &&
+    (lock.runtimePort === port || lock.bridgePort === port)
+  ) {
+    return lock.bridgePort
+  }
+  return null
+}
+
+/** the bridge a `--base-url` pin implies. one rule for every command that takes
+ *  the flag, because they used to disagree: flow refused an unserved pin while
+ *  open kept the discovered default and then started a bridge of its own, so
+ *  the page rendered in the pinned shell and the polling waited on another
+ *  world's bridge. that reads as "saved sim <id> is gone" and gets retried
+ *  rather than fixed. an explicit --port states the world outright and wins;
+ *  otherwise the pin has to name a world something serves. */
+export function resolveBridgePortForPin(pin: {
+  baseUrl: string
+  wsPort: number
+  explicitPort: boolean
+}): { port: number; error?: undefined } | { port?: undefined; error: string } {
+  const served = bridgePortForShellBaseUrl(pin.baseUrl)
+  if (served === null) {
+    if (pin.explicitPort) return { port: pin.wsPort }
+    return {
+      error:
+        `no live rnx world serves ${pin.baseUrl} — start that shell first, ` +
+        'or name its bridge with --port <port>',
+    }
+  }
+  if (pin.explicitPort && pin.wsPort !== served) {
+    return {
+      error: `--base-url ${pin.baseUrl} belongs to bridge port ${served}, but --port ${pin.wsPort} names another world`,
+    }
+  }
+  return { port: served }
+}
+
+/** default ws bridge port for CLI commands: the fresh dev bridge when a vite
+ *  shell is live, else the fresh daemon, else the hardcoded default. one
+ *  deterministic answer regardless of how the CLI was invoked (global binary
+ *  vs repo checkout) — invocation-path heuristics made `rnx list` flap
+ *  between worlds. */
+export function resolveDefaultBridgePort(): number {
+  return resolveBridgeWorld().bridgePort
+}
+
+/** one-line stderr notice naming the bridge world a command resolved, so the
+ *  dev-bridge vs daemon pick is never silent (the split-brain bug hid behind
+ *  exactly this silence). pass the shell base URL actually used when the
+ *  caller resolved one (open); otherwise the port's own world URL prints. */
+export function printBridgeWorldNotice(
+  bridgePort: number,
+  shellBaseUrl?: string | null,
+): void {
+  const world = worldForBridgePort(bridgePort)
+  const kind =
+    world?.source === 'dev-bridge'
+      ? 'dev bridge'
+      : world?.source === 'daemon'
+        ? 'daemon bridge'
+        : 'bridge'
+  const origin =
+    world?.source === 'dev-bridge'
+      ? `dev-bridges/${bridgePort}.json`
+      : world?.source === 'daemon'
+        ? 'daemon.json'
+        : 'no lockfile'
+  const shell = shellBaseUrl ?? world?.shellBaseUrl
+  process.stderr.write(
+    `  → ${kind} :${bridgePort} (${shell ? `shell ${shell}, ` : ''}${origin})\n`,
+  )
+}
+
+export interface WsBridge {
+  readonly plane?: 'local' | 'cloud'
+  // `opts.timeoutMs` overrides the bridge-wide commandTimeoutMs for a single
+  // call — used for fast readiness probes so a dead/unresponsive sim fails in
+  // seconds instead of stalling the full command timeout.
+  send(
+    cmd: { type: string; [k: string]: any },
+    opts?: { timeoutMs?: number },
+  ): Promise<any>
+  listSims(): Promise<BridgeSimInfo[]>
+  // a guest reload retires the socket and the same page reconnects under a new
+  // or restored id. a caller that pins an id resolves that target here; null
+  // means nothing proves what replaced it.
+  resolveReloadedSim(retiredSimId: string): Promise<string | null>
+  focusSim(simId?: string): Promise<any>
+  closeSim(simId?: string): Promise<any>
+  claim(simId?: string, opts?: { force?: boolean }): Promise<BridgeClaimResult>
+  close(): void
+}
+
+export interface BridgeClaimResult {
+  simId: string
+  lockedBy: string
+  lockExpiresAt: number
+  bootedCount: number
+}
+
+export interface BridgeLockInfo {
+  by: string
+  expiresInMs: number
+}
+
+export class BridgeSimLockedError extends Error {
+  lock: BridgeLockInfo
+  constructor(message: string, lock: BridgeLockInfo) {
+    super(message)
+    this.name = 'BridgeSimLockedError'
+    this.lock = lock
+  }
+}
+
+interface WsResponse {
+  id: number
+  result?: any
+  error?: string
+}
+
+interface WsBridgeOptions {
+  commandTimeoutMs?: number
+  simId?: string
+  cliLabel?: string
+  simIdSource?: ParsedBridgeCliArgs['simIdSource']
+}
+
+// label shown in the target-sim notice. explains where the simId came
+// from so an agent can tell "I asked for a7" vs "I got default primary".
+function describeSimIdSource(
+  source: ParsedBridgeCliArgs['simIdSource'] | undefined,
+): string {
+  if (source === 'flag') return 'via --sim'
+  if (source === 'saved') return 'saved via `rnx use`'
+  return 'primary fallback — no sim pinned'
+}
+
+export interface BridgeSimInfo {
+  id: string
+  origin?: string
+  url?: string
+  title?: string
+  userAgent?: string
+  connectedAt: number
+  lastSeenAt: number
+  lastActiveAt?: number
+  isPrimary: boolean
+  readyState: 'open' | 'closing' | 'closed'
+  attachedCliCount?: number
+  lockedBy?: string
+  lockedByKind?: 'cli' | 'user-active'
+  lockExpiresAt?: number
+  /** true when this sim's lease belongs to us. computed server-side. */
+  lockedByMe?: boolean
+  userFocused?: boolean
+  userVisible?: boolean
+  visibilityState?: string
+  documentFocused?: boolean
+  /** registration kind — 'sootsim' (default) or 'contrast'. used by the
+   *  `contrast` CLI to filter, and by tooling that wants to distinguish a
+   *  Contrast IDE tab from a regular rnx runtime. */
+  kind?: string
+  /** opaque metadata supplied at register time (projectId, route, the
+   *  attached iOS sim id, etc). free-form by design. */
+  meta?: Record<string, unknown>
+}
+
+// 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.
+export 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}`
+}
+
+interface ParseBridgeCliArgsOptions {
+  port?: number
+  commandTimeoutMs?: number
+  stripBooleanFlags?: string[]
+  stripValueFlags?: string[]
+}
+
+export interface ParsedBridgeCliArgs {
+  positional: string[]
+  wsPort: number
+  explicitPort: boolean
+  simId?: string
+  simIdSource: 'flag' | 'saved' | 'none'
+  commandTimeoutMs: number
+}
+
+interface BridgeFlagState {
+  wsPort: number
+  explicitPort: boolean
+  commandTimeoutMs: number
+  simId: string | undefined
+  simIdSource: ParsedBridgeCliArgs['simIdSource']
+}
+
+// every flag parseBridgeCliArgs consumes a value for on its own, without being
+// listed in a caller's stripValueFlags. the parser iterates this table, so the
+// exported name list below cannot drift from what is actually parsed. a name
+// missing from that list is not a parse failure, it is a command that hunts a
+// positional in raw argv and takes the flag's value instead: `maestro test
+// --newflag value login.yaml` would run `value` as the flow.
+const BRIDGE_VALUE_FLAGS_TABLE: readonly {
+  names: readonly string[]
+  apply: (state: BridgeFlagState, value: string | undefined) => void
+}[] = [
+  {
+    names: ['--port', '-p'],
+    // naming the flag pins the world even when the value is missing or junk,
+    // so a later --base-url cannot quietly retarget the run to another shell.
+    apply: (state, value) => {
+      state.explicitPort = true
+      if (value !== undefined) state.wsPort = Number(value)
+    },
+  },
+  {
+    names: ['--timeout'],
+    apply: (state, value) => {
+      if (value !== undefined) state.commandTimeoutMs = Number(value)
+    },
+  },
+  {
+    // `--sim` is the canonical target flag; `--session` / `--tab` are
+    // documented aliases (CLAUDE.md, the rnx agent skills, and engine docs all
+    // say `--session <id>`). without these aliases an agent following the docs
+    // would have `--session ef` silently ignored and get the *currently
+    // pinned* sim's tree instead — wrong-app data with no error.
+    names: ['--sim', '--session', '--tab'],
+    apply: (state, value) => {
+      if (value === undefined) return
+      state.simId = value.trim() || undefined
+      state.simIdSource = 'flag'
+    },
+  },
+]
+
+export const BRIDGE_VALUE_FLAGS: readonly string[] = BRIDGE_VALUE_FLAGS_TABLE.flatMap(
+  (flag) => [...flag.names],
+)
+
+export function parseBridgeCliArgs(
+  args: string[],
+  opts: ParseBridgeCliArgsOptions = {},
+): ParsedBridgeCliArgs {
+  const flagIndices = new Set<number>()
+  const state: BridgeFlagState = {
+    wsPort: opts.port ?? resolveDefaultBridgePort(),
+    explicitPort: opts.port !== undefined,
+    commandTimeoutMs: opts.commandTimeoutMs ?? 15000,
+    simId: undefined,
+    simIdSource: 'none',
+  }
+
+  const stripBooleanFlags = new Set(opts.stripBooleanFlags ?? [])
+  const stripValueFlags = new Set(opts.stripValueFlags ?? [])
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    // both spellings for every flag in the table: `--flag value` and
+    // `--flag=value`.
+    const valueFlag = BRIDGE_VALUE_FLAGS_TABLE.find((flag) =>
+      flag.names.some((name) => arg === name || arg.startsWith(`${name}=`)),
+    )
+    if (valueFlag) {
+      flagIndices.add(i)
+      const inline = valueFlag.names.find((name) => arg.startsWith(`${name}=`))
+      if (inline) {
+        valueFlag.apply(state, arg.slice(inline.length + 1))
+        continue
+      }
+      const value = i + 1 < args.length ? args[i + 1] : undefined
+      if (value !== undefined) flagIndices.add(i + 1)
+      valueFlag.apply(state, value)
+      i++
+      continue
+    }
+    if (stripBooleanFlags.has(arg)) {
+      flagIndices.add(i)
+      continue
+    }
+    if (stripValueFlags.has(arg)) {
+      flagIndices.add(i)
+      if (i + 1 < args.length) {
+        flagIndices.add(i + 1)
+      }
+      i++
+    }
+  }
+
+  if (!state.simId) {
+    const savedSim = readCurrentSim()
+    if (savedSim) {
+      state.simId = savedSim.simId.trim() || undefined
+      state.simIdSource = 'saved'
+    }
+  }
+
+  return {
+    positional: args.filter((_, i) => !flagIndices.has(i)),
+    wsPort: state.wsPort,
+    explicitPort: state.explicitPort,
+    simId: state.simId,
+    simIdSource: state.simIdSource,
+    commandTimeoutMs: state.commandTimeoutMs,
+  }
+}
+
+export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBridge {
+  let nextId = 1
+  const commandTimeoutMs = opts.commandTimeoutMs ?? 15000
+  const pending = new Map<
+    number,
+    { resolve: (v: any) => void; reject: (e: Error) => void }
+  >()
+
+  const ws = new WebSocket(bridgeWsUrl(wsPort))
+  // always key the lease on the stable agent/terminal identity, never on the
+  // target simId. keying off `sim:<id>` conflated "which sim" with "who is
+  // driving it": a single agent's identity then flipped between its stable key
+  // (untargeted commands) and `sim:<id>` (targeted commands), so the agent
+  // could take a lease under one key and get refused under the other — locked
+  // out of a sim it owns. it also made two different agents driving the same
+  // sim collide into one identity and trample each other's lease. getCliIdentity()
+  // is already stable per agent run (CLAUDE_CODE_SESSION_ID / per-terminal) and
+  // distinct between agents — exactly what the lease wants.
+  const identity = getCliIdentity()
+
+  const ready = new Promise<void>((resolve, reject) => {
+    ws.on('open', () => {
+      // identify ourselves so the server keys leases on the agent run,
+      // not the ephemeral ws connection (CLI invocations are short-lived).
+      // when identity is unstable the server falls back to a per-socket key,
+      // which is still safer than letting multiple agents share a sim.
+      try {
+        ws.send(
+          JSON.stringify({
+            type: 'bridge:hello',
+            id: 0,
+            cliIdentityKey: identity.key,
+            cliIdentitySource: identity.source,
+            cliLabel: opts.cliLabel,
+          }),
+        )
+      } catch {}
+      resolve()
+    })
+    ws.on('error', (err) => {
+      // err.message is often empty (ECONNREFUSED surfaces with no message on
+      // some node builds) — don't emit a dangling "...7668: " with no cause.
+      const cause = err.message ? `: ${err.message}` : ''
+      reject(new Error(`could not connect to ${bridgeWsUrl(wsPort)}${cause}`))
+    })
+  })
+  // a bridge closed before its handshake finished rejects `ready` with nothing
+  // awaiting it (every send awaits ready and still sees the rejection); mark it
+  // handled so that path never surfaces as an unhandled rejection.
+  ready.catch(() => {})
+
+  let warnedAboutContention = false
+  let noticedTarget = false
+  // the browser host and connection behind each target, learned while that
+  // sim is still connected. a reload changes the connection, and sometimes the
+  // sim id, but not the host.
+  const lineageBySimId = new Map<string, { hostPid: number; connectedAt: number }>()
+  const lineageLookupBySimId = new Map<string, Promise<void>>()
+
+  // a reload retires the socket but keeps the browser host. the replacement
+  // can receive a new sim id or restore the prior one from session storage.
+  // the unloading page's socket stays listed as open until its close lands, so
+  // only a connection newer than the known one is a replacement. the restored
+  // id is definitive; a new id must be the only newer same-host match.
+  function pickReloadedTarget(sims: unknown, retiredSimId: string): string | null {
+    const lineage = lineageBySimId.get(retiredSimId)
+    if (!lineage) return null
+    const matches = (Array.isArray(sims) ? (sims as BridgeSimInfo[]) : []).filter(
+      (sim) =>
+        sim.readyState === 'open' &&
+        sim.meta?.sootsimHostPid === lineage.hostPid &&
+        sim.connectedAt > lineage.connectedAt,
+    )
+    const successor =
+      matches.find((sim) => sim.id === retiredSimId) ??
+      (matches.length === 1 ? matches[0] : null)
+    if (!successor) return null
+    lineageBySimId.set(successor.id, {
+      hostPid: lineage.hostPid,
+      connectedAt: successor.connectedAt,
+    })
+    return successor.id
+  }
+
+  // print a one-line notice on first sim-scoped command so agents/users see
+  // which sim the command actually hit. suppressed for bridge:*
+  // control commands (list/open/focus/close/claim) that don't target a
+  // single sim, and for the hidden SOOTSIM_QUIET_TARGET_NOTICE escape hatch
+  // used by scripts that prefer clean stdout.
+  function maybeNoticeTarget(cmdType: string, simId: string | undefined) {
+    if (noticedTarget) return
+    if (process.env.SOOTSIM_QUIET_TARGET_NOTICE === '1') return
+    if (cmdType.startsWith('bridge:') || cmdType === 'focus' || cmdType === 'close')
+      return
+    noticedTarget = true
+    const label = simId ?? 'primary'
+    const source = describeSimIdSource(simId ? opts.simIdSource : 'none')
+    process.stderr.write(`  → ${label} (${source})\n`)
+  }
+
+  ws.on('message', (data) => {
+    let msg: any
+    try {
+      msg = JSON.parse(data.toString())
+    } catch {
+      return
+    }
+    if (msg.id === 0) return // bridge:hello ack
+    const p = pending.get(msg.id)
+    if (!p) return
+    pending.delete(msg.id)
+
+    // warn once if another CLI identity is also targeting this sim. this is
+    // NOT a bridge-throughput / congestion warning — the bridge is a thin ws
+    // relay and handles many messages/sec. it's a *semantic* warning: two
+    // agents driving the same screen will collide on taps/scroll/keyboard
+    // state. writes already serialize via the cli lease; reads pass through.
+    if (msg._otherCliCount > 0 && !warnedAboutContention) {
+      warnedAboutContention = true
+      process.stderr.write(
+        `\n  ⚠ ${msg._otherCliCount} other CLI identity/identities are driving this sim\n` +
+          '  taps, scrolls, and keyboard input from multiple agents will collide on\n' +
+          '  the same screen state (this is not a bridge throughput limit).\n' +
+          '  use `rnx open --new` for an isolated sim per agent.\n\n',
+      )
+    }
+
+    if (msg.error) {
+      if (msg._locked) {
+        p.reject(new BridgeSimLockedError(msg.error, msg._locked as BridgeLockInfo))
+      } else {
+        p.reject(new Error(msg.error))
+      }
+    } else {
+      p.resolve(msg.result)
+    }
+  })
+
+  // when the bridge host or target sim disconnects, reject all pending commands
+  // so the CLI gets a clear error instead of silently timing out
+  ws.on('close', (code, reason) => {
+    const msg = reason?.toString() || 'connection closed'
+    for (const [id, p] of pending) {
+      pending.delete(id)
+      p.reject(new Error(`sim disconnected: ${msg} (code ${code})`))
+    }
+  })
+
+  return {
+    plane: 'local',
+    async send(cmd, callOpts) {
+      // NOTE: `opts` (the createBridge closure arg) carries simId; do not
+      // shadow it with the per-call arg.
+      const effectiveTimeoutMs = callOpts?.timeoutMs ?? commandTimeoutMs
+      const sendOnce = async (
+        defaultSimId?: string,
+        cmdOverride?: Record<string, any>,
+      ) => {
+        await ready
+        const id = nextId++
+        return new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            pending.delete(id)
+            reject(
+              new Error(
+                `command timed out after ${Math.round(effectiveTimeoutMs / 1000)}s`,
+              ),
+            )
+          }, effectiveTimeoutMs)
+
+          pending.set(id, {
+            resolve: (v) => {
+              clearTimeout(timeout)
+              resolve(v)
+            },
+            reject: (e) => {
+              clearTimeout(timeout)
+              reject(e)
+            },
+          })
+
+          const payload = { ...(cmdOverride ?? cmd), id } as Record<string, any>
+          if (payload.simId === undefined && defaultSimId) {
+            payload.simId = defaultSimId
+          }
+          maybeNoticeTarget(payload.type ?? '', payload.simId)
+          ws.send(JSON.stringify(payload))
+        })
+      }
+
+      // re-resolve the saved pin per send for bridges that were not
+      // explicitly `--sim`-targeted. a poll loop (`wait ready`) started
+      // before a concurrent `rnx open` finished connecting would
+      // otherwise stay on the primary fallback for its whole budget, probing
+      // an unrelated (often empty) sim while the intended one connects and
+      // pins itself mid-wait. falling back to the startup pin keeps the
+      // fail-closed saved-sim-gone path below when the pin file is cleared.
+      const sentSimId =
+        opts.simIdSource === 'flag' ? opts.simId : (readCurrentSimId() ?? opts.simId)
+      const targetedSimId =
+        typeof cmd.simId === 'string' && cmd.simId ? cmd.simId : sentSimId
+      try {
+        // a command can itself reload the page and retire its sim id. capture
+        // the browser-host lineage before dispatch, while the target still
+        // exists, so the caller can follow the replacement without guessing.
+        if (
+          targetedSimId &&
+          cmd.type !== 'bridge:list-sims' &&
+          !lineageBySimId.has(targetedSimId)
+        ) {
+          let lookup = lineageLookupBySimId.get(targetedSimId)
+          if (!lookup) {
+            lookup = (async () => {
+              try {
+                const sims = await sendOnce(undefined, { type: 'bridge:list-sims' })
+                if (!Array.isArray(sims)) return
+                const targeted = (sims as BridgeSimInfo[]).find(
+                  (sim) => sim.id === targetedSimId,
+                )
+                const hostPid = targeted?.meta?.sootsimHostPid
+                if (targeted && typeof hostPid === 'number') {
+                  lineageBySimId.set(targetedSimId, {
+                    hostPid,
+                    connectedAt: targeted.connectedAt,
+                  })
+                }
+              } catch {
+                // lineage enables fail-closed reload following, but a failed
+                // observation must not replace the caller's command failure.
+              } finally {
+                lineageLookupBySimId.delete(targetedSimId)
+              }
+            })()
+            lineageLookupBySimId.set(targetedSimId, lookup)
+          }
+          await lookup
+        }
+        return await sendOnce(sentSimId)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        const missingSimMessage = `no sim connected with id ${sentSimId}`
+        if (
+          opts.simIdSource !== 'flag' &&
+          sentSimId &&
+          cmd.simId === undefined &&
+          (message === missingSimMessage || message.startsWith(`${missingSimMessage};`))
+        ) {
+          // a reload retires the sim id but keeps the browser host, so the
+          // successor with the same host pid IS the same page lineage — not a
+          // guess. adopt only that, and only when it is unambiguous.
+          const successor = pickReloadedTarget(
+            await sendOnce(undefined, { type: 'bridge:list-sims' }),
+            sentSimId,
+          )
+          if (successor) {
+            saveCurrentSimId(successor)
+            process.stderr.write(
+              `  note: sim ${sentSimId} reloaded and reconnected as ${successor}; following it\n`,
+            )
+            return sendOnce(successor)
+          }
+          clearCurrentSimId()
+          // the saved sim is gone and nothing proves what replaced it. fail
+          // closed instead of driving whichever sim is primary; that is how
+          // agents end up recording the wrong app.
+          throw new Error(
+            `saved sim ${sentSimId} is gone${message.slice(missingSimMessage.length)}; ` +
+              'run `rnx list` and ' +
+              `\`rnx use <sim>\`, or open a fresh sim`,
+          )
+        }
+        throw error
+      }
+    },
+    async listSims() {
+      const sims = await this.send({ type: 'bridge:list-sims' })
+      return Array.isArray(sims) ? (sims as BridgeSimInfo[]) : []
+    },
+    // a caller holding its own pinned sim id (a flow runner sets simId on every
+    // command, so it never reaches the pin-following path in send) asks here
+    // after a reload retires its socket. the page can reconnect under a new id
+    // or restore the old id; null means no unique same-host target exists.
+    async resolveReloadedSim(retiredSimId: string) {
+      return pickReloadedTarget(await this.listSims(), retiredSimId)
+    },
+    async focusSim(simId?: string) {
+      return this.send({ type: 'focus', simId })
+    },
+    async closeSim(simId?: string) {
+      return this.send({ type: 'close', simId })
+    },
+    async claim(simId?: string, claimOpts: { force?: boolean } = {}) {
+      const result = await this.send({
+        type: 'bridge:claim',
+        simId,
+        force: claimOpts.force === true,
+      })
+      return result as BridgeClaimResult
+    },
+    close() {
+      // send an explicit goodbye so the server deregisters this socket
+      // synchronously instead of waiting on the tcp close event, which
+      // can lag the next cli invocation and produce phantom-peer warnings.
+      try {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'bridge:bye', id: 0 }))
+        }
+      } catch {}
+      ws.close()
+      // clear the grace timer on a real close, or a one-shot `rnx` command is
+      // held on the event loop for the full 250ms after its work is done. that
+      // delay lands directly in in-box prompt latency, since the shell spawns
+      // rnx and waits on child close.
+      const terminateGrace = setTimeout(() => {
+        if (ws.readyState !== WebSocket.CLOSED) {
+          ws.terminate()
+        }
+      }, 250)
+      ws.once('close', () => clearTimeout(terminateGrace))
+    },
+  }
+}
+
+/**
+ * how a command reaches a simulator. left out, it resolves the way the host
+ * CLI always has: the cloud box route when a box session is set, otherwise the
+ * local ws daemon. a box shell passes its own bridge so the same command runs
+ * in the calling process against the box's own simulator.
+ */
+export interface BridgeTransportOption {
+  createBridge?: (parsed: ParsedBridgeCliArgs) => WsBridge
+}
+
+export function createBridgeFromParsed(parsed: ParsedBridgeCliArgs): WsBridge {
+  const cloudBridge = createCloudBridgeForParsed(parsed)
+  if (cloudBridge) return cloudBridge
+  return createBridge(parsed.wsPort, {
+    commandTimeoutMs: parsed.commandTimeoutMs,
+    simId: parsed.simId,
+    simIdSource: parsed.simIdSource,
+  })
+}
+
+interface SimHealthProbe {
+  hidden?: boolean
+  visibilityState?: string
+  hasFocus?: boolean | null
+  simId?: string | null
+  url?: string
+}
+
+function describeVisibleSimCandidate(sims: BridgeSimInfo[], currentId?: string | null) {
+  const open = sims.filter((sim) => sim.readyState === 'open' && sim.id !== currentId)
+  const candidate =
+    open.find((sim) => sim.userFocused) ??
+    open.find((sim) => sim.userVisible === true && sim.isPrimary) ??
+    open.find((sim) => sim.userVisible === true) ??
+    open.find((sim) => sim.isPrimary)
+  if (!candidate) return null
+  const tags = [
+    candidate.isPrimary ? 'primary' : null,
+    candidate.userVisible === false
+      ? 'hidden'
+      : candidate.userVisible === true
+        ? 'visible'
+        : null,
+    candidate.userFocused ? 'focused' : null,
+  ].filter(Boolean)
+  return `${candidate.id}${tags.length ? ` [${tags.join(', ')}]` : ''}`
+}
+
+/**
+ * Check if the target sim is healthy for interaction. Warns on stderr if:
+ * - document.hidden is true (animations won't run, coordinates may be wrong)
+ * Returns the health state so callers can decide whether to proceed.
+ */
+export async function checkSimHealth(
+  bridge: WsBridge,
+): Promise<{ hidden: boolean; warned: boolean; simId?: string | null }> {
+  // a CPU simulator has no document to be hidden, and the probe below is an
+  // `evaluate` the cloud runtime refuses by name.
+  if (bridge.plane === 'cloud') return { hidden: false, warned: false }
+  try {
+    const probe = (await bridge.send({
+      type: 'evaluate',
+      code: `(() => ({
+        hidden: document.hidden,
+        visibilityState: document.visibilityState,
+        hasFocus: typeof document.hasFocus === 'function' ? document.hasFocus() : null,
+        simId: window.__sootsimBridge?.id ?? window.SootSim?.state?.simId ?? null,
+        url: location.href
+      }))()`,
+    })) as SimHealthProbe | boolean | null
+    const health =
+      typeof probe === 'object' && probe !== null ? probe : { hidden: probe === true }
+    const hidden = health.hidden === true
+    if (hidden === true) {
+      let candidate: string | null = null
+      try {
+        candidate = describeVisibleSimCandidate(await bridge.listSims(), health.simId)
+      } catch {}
+      process.stderr.write(
+        `\n  ⚠ target sim${health.simId ? ` ${health.simId}` : ''} is hidden (document.hidden = true)\n` +
+          (health.visibilityState ? `  visibility: ${health.visibilityState}\n` : '') +
+          '  animations and rAF callbacks are throttled — coordinates may be wrong\n' +
+          '  and launch/transition animations will not complete.\n' +
+          (candidate
+            ? `  another open sim looks usable: ${candidate}; target it with --sim.\n`
+            : '  run `rnx list` to find the visible sim and target it with --sim.\n') +
+          '  page-level window.focus() cannot unhide a browser tab.\n\n',
+      )
+      return { hidden: true, warned: true, simId: health.simId }
+    }
+    return { hidden: false, warned: false, simId: health.simId }
+  } catch {
+    return { hidden: false, warned: false }
+  }
+}
+
+/**
+ * Convenience: run arbitrary JavaScript in the rnx page and return the
+ * result. Hides the `type: 'evaluate'` message shape. Read-only by default —
+ * pass `{ acquireLock: true }` when the eval mutates user-facing state so
+ * the server takes/refreshes the cli lease and blocks concurrent agents.
+ */
+export async function evalInBridge<T = unknown>(
+  bridge: WsBridge,
+  code: string,
+  opts: { acquireLock?: boolean } = {},
+): Promise<T> {
+  const payload: { type: string; [k: string]: any } = { type: 'evaluate', code }
+  if (opts.acquireLock) payload.acquireLock = true
+  return bridge.send(payload) as Promise<T>
+}
+
+/**
+ * Invoke a function on `window.SootSim.bridges.*` over the bridge. Read-only
+ * by default for the same reason as evalInBridge.
+ */
+export async function callInBridge<T = unknown>(
+  bridge: WsBridge,
+  path: string,
+  ...args: unknown[]
+): Promise<T> {
+  return bridge.send({ type: 'call', path, args }) as Promise<T>
+}
+
+/** Write variant — takes/refreshes the cli lease on the target sim. */
+export async function callInBridgeWrite<T = unknown>(
+  bridge: WsBridge,
+  path: string,
+  ...args: unknown[]
+): Promise<T> {
+  return bridge.send({ type: 'call', path, args, acquireLock: true }) as Promise<T>
+}