rnxsim 0.1.499 → 0.1.501

package/cli/commands/test.ts

@@ -1,23 +1,33 @@
-// rnx test — choose the existing Maestro or Detox interpreter from a test path.
+// rnx test — choose Maestro or Detox, support local bundle loopback and standalone cloud execution.
 
-import { existsSync, readFileSync, statSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { createServer, type Server } from 'node:http'
-import { basename, extname, join, resolve } from 'path'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+import {
+  RNX_CLOUD_TEST_FILES_MAX_BYTES,
+  RNX_CLOUD_TEST_FILES_MAX_COUNT,
+} from '../../src/cloud-contract'
+import { authHeaderValue, resolveCliAuth } from '../auth'
 import { buildShellUrl, resolveShellBaseUrlForBridgePort } from './control'
-import { runDetox } from './detox'
-import { runMaestro } from './maestro'
-
-type TestRunner = 'maestro' | 'detox'
+import { hoistLeadingSimFlag } from './flow'
+import { resolveDefaultUploadOrigin } from './upload'
 
 export interface RunTestOptions {
   port?: number
   verbose?: boolean
+  pollIntervalMs?: number
+  timeoutMs?: number
+}
+
+interface TestAppTarget {
+  target: string
+  close: () => Promise<void>
 }
 
-const MAESTRO_CONFIG_NAMES = new Set(['config.yaml', 'config.yml'])
-const DETOX_CONFIG_NAME = /^jest\.config\.(?:[cm]?[jt]s)$/
 const VALUE_FLAGS = new Set([
   '--app',
+  '--bundle',
+  '--bundle-url',
   '--config',
   '--sim',
   '--session',
@@ -33,51 +43,16 @@ const VALUE_FLAGS = new Set([
   '--maxWorkers',
   '--shard',
   '--outputFile',
+  '--origin',
+  '--owner',
+  '--repo',
+  '--poll-interval',
+  '--timeout',
 ])
 
-function isDetoxPackageConfig(path: string): boolean {
-  if (basename(path) !== 'package.json') return false
-  try {
-    const value: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    if (!value || typeof value !== 'object' || Array.isArray(value)) return false
-    return 'detox' in value || 'jest' in value
-  } catch {
-    return false
-  }
-}
-
-function classifyTestPath(path: string): TestRunner | null {
-  const name = basename(path)
-  const extension = extname(path).toLowerCase()
-  if (MAESTRO_CONFIG_NAMES.has(name) || extension === '.yaml' || extension === '.yml') {
-    return 'maestro'
-  }
-  if (DETOX_CONFIG_NAME.test(name) || isDetoxPackageConfig(path)) return 'detox'
-  if (
-    ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.tsx', '.jsx'].includes(extension)
-  ) {
-    return 'detox'
-  }
-  if (!existsSync(path) || !statSync(path).isDirectory()) return null
-  if (existsSync(join(path, 'config.yaml')) || existsSync(join(path, 'config.yml'))) {
-    return 'maestro'
-  }
-  if (existsSync(join(path, '.maestro')) || basename(path) === '.maestro')
-    return 'maestro'
-  if (
-    existsSync(join(path, 'rnx-detox.config.cjs')) ||
-    existsSync(join(path, 'jest.config.cjs')) ||
-    existsSync(join(path, 'jest.config.js')) ||
-    isDetoxPackageConfig(join(path, 'package.json')) ||
-    existsSync(join(path, 'e2e')) ||
-    existsSync(join(path, 'detox'))
-  ) {
-    return 'detox'
-  }
-  return null
-}
-
 function valueAfter(args: string[], name: string): string | null {
+  const inline = args.find((arg) => arg.startsWith(`${name}=`))
+  if (inline) return inline.slice(name.length + 1) || null
   const index = args.indexOf(name)
   if (index < 0) return null
   const value = args[index + 1]
@@ -91,31 +66,28 @@ function targetFromArgs(args: string[]): string | null {
       index += 1
       continue
     }
+    if (arg.startsWith('--') && arg.includes('=')) {
+      continue
+    }
     if (!arg.startsWith('-')) return arg
   }
   return null
 }
 
 function withoutApp(args: string[]): string[] {
-  const appIndex = args.indexOf('--app')
-  return args.filter((_, index) => index !== appIndex && index !== appIndex + 1)
-}
-
-function isDetoxConfigPath(path: string): boolean {
-  return DETOX_CONFIG_NAME.test(basename(path)) || isDetoxPackageConfig(path)
-}
-
-function restoreRnxUrl(previous: string | undefined): void {
-  if (previous === undefined) {
-    delete process.env.RNX_URL
-  } else {
-    process.env.RNX_URL = previous
+  const result: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--app') {
+      i += 1
+      continue
+    }
+    if (arg.startsWith('--app=')) {
+      continue
+    }
+    result.push(arg)
   }
-}
-
-interface TestAppTarget {
-  target: string
-  close: () => Promise<void>
+  return result
 }
 
 function closeServer(server: Server): Promise<void> {
@@ -127,7 +99,7 @@ function closeServer(server: Server): Promise<void> {
   })
 }
 
-async function servePrebuiltBundle(path: string): Promise<TestAppTarget> {
+export async function servePrebuiltBundle(path: string): Promise<TestAppTarget> {
   const file = resolve(process.cwd(), path)
   const stat = statSync(file)
   if (!stat.isFile() || extname(file) !== '.js') {
@@ -167,56 +139,392 @@ async function servePrebuiltBundle(path: string): Promise<TestAppTarget> {
   }
 }
 
-async function resolveTestAppTarget(app: string): Promise<TestAppTarget> {
+export async function resolveTestAppTarget(app: string): Promise<TestAppTarget> {
   const localPath = resolve(process.cwd(), app)
   if (existsSync(localPath)) return servePrebuiltBundle(localPath)
   return { target: app, close: async () => {} }
 }
 
-export async function runTest(
+function restoreRnxUrl(previous: string | undefined): void {
+  if (previous === undefined) {
+    delete process.env.RNX_URL
+  } else {
+    process.env.RNX_URL = previous
+  }
+}
+
+// dispatch only: each interpreter retains its own selection and execution rules.
+export function resolveTestCommand(args: string[], cwd = process.cwd()) {
+  const forwarded = hoistLeadingSimFlag(args)
+  const target = forwarded[0]?.startsWith('-') ? undefined : forwarded[0]
+  const config = forwarded.some(
+    (arg) => arg === '--config' || arg.startsWith('--config='),
+  )
+  if (config) return { command: 'detox', args: forwarded }
+  if (!target) {
+    throw new Error(
+      'pass a Maestro flow/directory, a Jest suite, or --config <jest-config>',
+    )
+  }
+  const absolute = resolve(cwd, target)
+  if (!existsSync(absolute)) throw new Error(`test target not found: ${target}`)
+  const directory = statSync(absolute).isDirectory()
+  if (
+    !directory &&
+    /^(?:jest|rnx-detox)\.config\.[cm]?[jt]s$|^jest\.config\.json$/.test(
+      basename(absolute),
+    )
+  ) {
+    return { command: 'detox', args: ['--config', target, ...forwarded.slice(1)] }
+  }
+  const maestro = directory
+    ? readdirSync(absolute).some((name) => /\.ya?ml$/.test(name)) ||
+      ['.maestro', 'maestro'].includes(basename(absolute))
+    : /\.ya?ml$/.test(extname(absolute))
+  if (maestro) {
+    return {
+      command: 'maestro',
+      args: [
+        'test',
+        ...forwarded.map((arg, index) => {
+          if (index === 0 && !directory && /^config\.ya?ml$/.test(basename(absolute)))
+            return dirname(absolute)
+          return arg === '--app' || arg.startsWith('--app=')
+            ? arg.replace('--app', '--url')
+            : arg
+        }),
+      ],
+    }
+  }
+  if (!directory && !/\.[cm]?[jt]sx?$/.test(extname(absolute))) {
+    throw new Error(`expected Maestro YAML or a Detox/Jest suite: ${target}`)
+  }
+  return { command: 'detox', args: forwarded }
+}
+
+function collectTestFiles(
+  targetPath: string,
+  ignoredPath: string | null,
+): Record<string, string> {
+  const files: Record<string, string> = {}
+  let sourceBytes = 0
+  const add = (path: string, relativePath: string) => {
+    if (Object.keys(files).length >= RNX_CLOUD_TEST_FILES_MAX_COUNT) {
+      throw new Error(
+        `cloud test suites may contain at most ${RNX_CLOUD_TEST_FILES_MAX_COUNT} files`,
+      )
+    }
+    sourceBytes += statSync(path).size
+    if (sourceBytes > RNX_CLOUD_TEST_FILES_MAX_BYTES) {
+      throw new Error(
+        `cloud test files may contain at most ${RNX_CLOUD_TEST_FILES_MAX_BYTES} bytes`,
+      )
+    }
+    files[relativePath] = readFileSync(path, 'utf8')
+  }
+  const stat = statSync(targetPath)
+  if (stat.isDirectory()) {
+    function walk(dir: string, base: string) {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') && entry.name !== '.maestro') continue
+        if (['node_modules', 'dist', 'build', '.git'].includes(entry.name)) continue
+        const full = join(dir, entry.name)
+        if (ignoredPath && resolve(full) === ignoredPath) continue
+        const rel = base ? `${base}/${entry.name}` : entry.name
+        if (entry.isDirectory()) {
+          walk(full, rel)
+        } else if (entry.isFile()) {
+          add(full, rel)
+        }
+      }
+    }
+    walk(targetPath, '')
+  } else if (stat.isFile()) {
+    add(targetPath, basename(targetPath))
+    const parent = dirname(targetPath)
+    for (const configName of [
+      'rnx-detox.config.cjs',
+      'jest.config.cjs',
+      'jest.config.js',
+    ]) {
+      const configPath = join(parent, configName)
+      if (existsSync(configPath) && !files[configName]) {
+        add(configPath, configName)
+      }
+    }
+  }
+  const serializedBytes = Buffer.byteLength(JSON.stringify(files))
+  if (serializedBytes > RNX_CLOUD_TEST_FILES_MAX_BYTES) {
+    throw new Error(
+      `cloud test files serialize to ${serializedBytes} bytes; the limit is ${RNX_CLOUD_TEST_FILES_MAX_BYTES}`,
+    )
+  }
+  return files
+}
+
+export async function runCloudTest(
   args: string[],
   opts: RunTestOptions = {},
 ): Promise<number> {
-  const target = targetFromArgs(args)
-  const app = valueAfter(args, '--app')
-  if (!target || !app) {
-    console.error('  usage: rnx test <flow-or-suite> --app <bundle>')
+  const forwarded = args.filter((a) => a !== '--cloud' && a !== '--hosted')
+  const originFlag = valueAfter(forwarded, '--origin')
+  const origin = await resolveDefaultUploadOrigin(originFlag ?? undefined)
+  const app =
+    valueAfter(forwarded, '--app') ||
+    valueAfter(forwarded, '--bundle') ||
+    valueAfter(forwarded, '--bundle-url') ||
+    valueAfter(forwarded, '--url') ||
+    forwarded.find((a) => a.startsWith('--app='))?.split('=')[1] ||
+    forwarded.find((a) => a.startsWith('--bundle='))?.split('=')[1] ||
+    forwarded.find((a) => a.startsWith('--url='))?.split('=')[1]
+
+  const owner = valueAfter(forwarded, '--owner')
+  const repo = valueAfter(forwarded, '--repo')
+
+  let target = targetFromArgs(forwarded)
+  const config = valueAfter(forwarded, '--config')
+  if (!target && config) {
+    target = config
+  }
+  if (!target) {
+    for (const cand of ['.maestro', 'maestro', 'flows', 'e2e']) {
+      if (existsSync(resolve(process.cwd(), cand))) {
+        target = cand
+        break
+      }
+    }
+  }
+  if (!target) {
+    console.error('  usage: rnx test <flow-or-suite> --app <bundle> --cloud')
     return 1
   }
 
   const targetPath = resolve(process.cwd(), target)
-  const runner = classifyTestPath(targetPath)
-  if (!runner) {
-    console.error(`  error: could not detect a Maestro flow or Detox suite at ${target}`)
+  if (!existsSync(targetPath)) {
+    console.error(`  error: test target not found: ${target}`)
+    return 1
+  }
+
+  if (!app) {
+    console.error(
+      '  error: rnx test --cloud requires --app <bundle.js|https://bundle-url>',
+    )
+    return 1
+  }
+
+  const auth = resolveCliAuth()
+  if (!auth) {
+    console.error('  error: rnx test --cloud requires `rnx login` or RNX_API_KEY')
     return 1
   }
 
-  const forwarded = withoutApp(args).filter((arg) => arg !== target)
-  const appTarget = await resolveTestAppTarget(app)
+  const pollIntervalFlag = valueAfter(forwarded, '--poll-interval')
+  const timeoutFlag = valueAfter(forwarded, '--timeout')
+  const pollIntervalMs =
+    pollIntervalFlag === null ? (opts.pollIntervalMs ?? 1000) : Number(pollIntervalFlag)
+  const timeoutMs =
+    timeoutFlag === null ? (opts.timeoutMs ?? 20 * 60 * 1000) : Number(timeoutFlag)
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 1) {
+    console.error('  error: --poll-interval must be a positive number of milliseconds')
+    return 1
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+    console.error('  error: --timeout must be a positive number of milliseconds')
+    return 1
+  }
+
+  let bundleUrl: string | undefined
+  let bundle: string | undefined
+  let bundleShareId: string | undefined
+
+  if (app.startsWith('http://') || app.startsWith('https://')) {
+    bundleUrl = app
+  } else if (app.startsWith('srb_') || app.includes('/api/preview/share/bundle')) {
+    bundleShareId = app.replace(/^.*id=/, '')
+  } else {
+    const localBundle = resolve(process.cwd(), app)
+    if (!existsSync(localBundle) || !statSync(localBundle).isFile()) {
+      console.error(`  error: --app bundle file not found: ${app}`)
+      return 1
+    }
+    bundle = readFileSync(localBundle, 'utf8')
+  }
+
+  const targetName = basename(targetPath)
+  const collectionPath =
+    statSync(targetPath).isFile() &&
+    (/^(?:jest|rnx-detox)\.config\.[cm]?[jt]s$|^jest\.config\.json$/.test(targetName) ||
+      /\.[cm]?[jt]sx?$/.test(extname(targetPath)))
+      ? dirname(targetPath)
+      : targetPath
+  const localBundlePath =
+    app.startsWith('http://') ||
+    app.startsWith('https://') ||
+    app.startsWith('srb_') ||
+    app.includes('/api/preview/share/bundle')
+      ? null
+      : resolve(process.cwd(), app)
+  const testFiles = collectTestFiles(collectionPath, localBundlePath)
+  if (Object.keys(testFiles).length === 0) {
+    console.error(`  error: no test files found at ${target}`)
+    return 1
+  }
+
+  const submitPayload: Record<string, unknown> = {
+    kind: 'test',
+    testFiles,
+  }
+  if (bundleUrl) submitPayload.bundleUrl = bundleUrl
+  if (bundle) submitPayload.bundle = bundle
+  if (bundleShareId) submitPayload.bundleShareId = bundleShareId
+  if (owner) submitPayload.owner = owner
+  if (repo) submitPayload.repo = repo
+
+  const endpoint = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs`
+  let response: Response
   try {
-    if (runner === 'maestro') {
-      const code = await runMaestro(
-        ['test', targetPath, '--url', appTarget.target, ...forwarded],
-        opts,
+    response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: authHeaderValue(auth),
+      },
+      body: JSON.stringify(submitPayload),
+    })
+  } catch (err) {
+    console.error(
+      `  error: could not connect to ${endpoint}: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return 1
+  }
+
+  if (!response.ok) {
+    const body = await response.text()
+    let message = body
+    try {
+      const json = JSON.parse(body)
+      if (json.message) message = json.message
+    } catch {}
+    console.error(
+      `  error: cloud test submission failed (${response.status}): ${message}`,
+    )
+    return 1
+  }
+
+  const { id } = (await response.json()) as { id: string }
+  console.log(`  cloud test job submitted: ${id}`)
+
+  const pollUrl = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs?id=${encodeURIComponent(id)}`
+  const startedAt = Date.now()
+
+  while (Date.now() - startedAt < timeoutMs) {
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+    let pollRes: Response
+    try {
+      pollRes = await fetch(pollUrl, {
+        headers: { authorization: authHeaderValue(auth) },
+      })
+    } catch (err) {
+      console.warn(
+        `  warn: error polling job: ${err instanceof Error ? err.message : String(err)}`,
       )
+      continue
+    }
+    if (!pollRes.ok) {
+      console.warn(`  warn: polling error: HTTP ${pollRes.status}`)
+      continue
+    }
+    const job = (await pollRes.json()) as {
+      id: string
+      status: string
+      result?: {
+        previewId?: string | null
+        previewUrl?: string | null
+        runId?: string | null
+        exitCode?: number | null
+        failureReason?: string | null
+      } | null
+    }
+
+    if (job.status === 'done' || job.status === 'failed' || job.status === 'expired') {
+      const result = job.result
+      const exitCode = result?.exitCode ?? (job.status === 'done' ? 0 : 1)
+      console.log(`  status:    ${job.status}`)
+      console.log(`  exit code: ${exitCode}`)
+      if (result?.previewUrl) {
+        console.log(`  preview:   ${result.previewUrl}`)
+      } else if (result?.previewId) {
+        console.log(
+          `  preview:   ${origin.replace(/\/$/, '')}/preview/${result.previewId}`,
+        )
+      }
+      if (result?.runId) {
+        console.log(`  run:       ${result.runId}`)
+      }
+      if (result?.failureReason) {
+        console.error(`  failure:   ${result.failureReason}`)
+      }
+      return exitCode
+    }
+  }
+
+  console.error(`  error: cloud test timed out after ${Math.round(timeoutMs / 1000)}s`)
+  return 1
+}
+
+export async function runTest(
+  args: string[],
+  opts: RunTestOptions = {},
+): Promise<number> {
+  if (args.includes('--cloud') || args.includes('--hosted')) {
+    return runCloudTest(args, opts)
+  }
+
+  const selected = resolveTestCommand(args)
+  const app = valueAfter(args, '--app')
+  const appTarget = app
+    ? await resolveTestAppTarget(app)
+    : { target: '', close: async () => {} }
+
+  try {
+    if (selected.command === 'maestro') {
+      const { flowTimeoutScale } = await import('../../src/flow-timeout-scale')
+      if (flowTimeoutScale() !== 1) {
+        throw new Error(
+          'rnx test requires original flow timeouts; unset SOOTSIM_FLOW_TIMEOUT_SCALE',
+        )
+      }
+      const { runMaestro } = await import('./maestro')
+      const maestroArgs = appTarget.target
+        ? selected.args.map((arg, idx) => {
+            const prev = selected.args[idx - 1]
+            if (prev === '--url') return appTarget.target
+            if (arg.startsWith('--url=')) return `--url=${appTarget.target}`
+            return arg
+          })
+        : selected.args
+      const code = await runMaestro(maestroArgs, opts)
       return typeof code === 'number' ? code : 0
     }
 
-    const detoxArgs = isDetoxConfigPath(targetPath)
-      ? ['--config', targetPath, ...forwarded]
-      : [targetPath, ...forwarded]
+    const { runDetox } = await import('./detox')
+    const detoxArgs = withoutApp(selected.args)
     const previousRnxUrl = process.env.RNX_URL
-    process.env.RNX_URL = await buildShellUrl(
-      appTarget.target,
-      resolveShellBaseUrlForBridgePort(
-        opts.port ?? (Number(process.env.SOOTSIM_PORT) || 5173),
-      ),
-    )
+    if (appTarget.target) {
+      process.env.RNX_URL = await buildShellUrl(
+        appTarget.target,
+        resolveShellBaseUrlForBridgePort(
+          opts.port ?? (Number(process.env.SOOTSIM_PORT) || 5173),
+        ),
+      )
+    }
     try {
       await runDetox(detoxArgs, opts)
       return 0
     } finally {
-      restoreRnxUrl(previousRnxUrl)
+      if (appTarget.target) {
+        restoreRnxUrl(previousRnxUrl)
+      }
     }
   } finally {
     await appTarget.close()

package/cli/main.ts

@@ -496,6 +496,17 @@ try {
           await exitWithFlush(1)
         }
         const platform = parsed.commandArgs[0]
+        if (platform === 'close') {
+          const { dispatchCloudBoundary } = await import('./cloud-dispatch')
+          const result = await dispatchCloudBoundary({
+            command: 'close',
+            args: parsed.commandArgs.slice(1),
+          })
+          if (result.handled) {
+            await exitWithFlush(result.code)
+          }
+          await exitWithFlush(0)
+        }
         if (platform === 'ios' || platform === 'android') {
           const { runRemotePlatformCommand } = await import('./commands/platform')
           const code = await runRemotePlatformCommand(

package/cli/outbound-endpoints.ts

@@ -146,6 +146,8 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     { category: 'rnx_cloud_sim', count: 1 },
   'packages/sootsim/cli/cloud-client.ts :: fetch :: `${session.apiOrigin}/v1/boxes/${encodeURIComponent(session.boxId)}`':
     { category: 'rnx_cloud_sim', count: 1 },
+  'packages/sootsim/cli/cloud-client.ts :: fetch :: `${session.apiOrigin}/v1/boxes/${encodeURIComponent(session.boxId)}/stop`':
+    { category: 'rnx_cloud_sim', count: 1 },
   'packages/sootsim/cli/cloud-client.ts :: fetch :: `${this.session.apiOrigin}/v1/sims/${encodeURIComponent(this.session.simId)}/commands`':
     { category: 'rnx_cloud_sim', count: 1 },
   'packages/sootsim/cli/cloud-client.ts :: fetch :: `${this.session.apiOrigin}/v1/boxes/${encodeURIComponent(this.session.boxId)}/commands`':
@@ -154,6 +156,14 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'guest_app_network',
     count: 1,
   },
+  'packages/sootsim/cli/commands/test.ts :: fetch :: endpoint': {
+    category: 'contrast_user_action',
+    count: 1,
+  },
+  'packages/sootsim/cli/commands/test.ts :: fetch :: pollUrl': {
+    category: 'contrast_user_action',
+    count: 1,
+  },
   'packages/sootsim/src/cloud.ts :: fetch :: `${origin}/v1/boxes`': {
     category: 'rnx_cloud_sim',
     count: 1,

package/cli/ws-bridge.ts

@@ -324,9 +324,9 @@ export interface WsBridge {
     opts?: { timeoutMs?: number },
   ): Promise<any>
   listSims(): Promise<BridgeSimInfo[]>
-  // a guest reload retires the sim id and re-registers the same page under a
-  // new one. a caller that pins an id resolves the successor here; null means
-  // nothing proves what replaced it.
+  // 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>
@@ -621,21 +621,20 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
   const hostPidBySimId = new Map<string, number>()
   const lineageLookupBySimId = new Map<string, Promise<void>>()
 
-  // a reload retires the sim id but keeps the browser host, so a successor
-  // sharing that host pid IS the same page lineage rather than a guess. only
-  // an unambiguous match counts; callers fail closed on null.
-  function pickReloadedSuccessor(sims: unknown, retiredSimId: string): string | null {
+  // 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 restored id is definitive; a new id must be the only same-host match.
+  function pickReloadedTarget(sims: unknown, retiredSimId: string): string | null {
     const pinnedHostPid = hostPidBySimId.get(retiredSimId)
     if (pinnedHostPid === undefined) return null
-    const successors = (Array.isArray(sims) ? (sims as BridgeSimInfo[]) : []).filter(
-      (sim) =>
-        sim.id !== retiredSimId &&
-        sim.readyState === 'open' &&
-        sim.meta?.sootsimHostPid === pinnedHostPid,
+    const matches = (Array.isArray(sims) ? (sims as BridgeSimInfo[]) : []).filter(
+      (sim) => sim.readyState === 'open' && sim.meta?.sootsimHostPid === pinnedHostPid,
     )
-    if (successors.length !== 1) return null
-    hostPidBySimId.set(successors[0].id, pinnedHostPid)
-    return successors[0].id
+    const restored = matches.find((sim) => sim.id === retiredSimId)
+    if (restored) return restored.id
+    if (matches.length !== 1) return null
+    hostPidBySimId.set(matches[0].id, pinnedHostPid)
+    return matches[0].id
   }
 
   // print a one-line notice on first sim-scoped command so agents/users see
@@ -801,7 +800,7 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
           // 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 = pickReloadedSuccessor(
+          const successor = pickReloadedTarget(
             await sendOnce(undefined, { type: 'bridge:list-sims' }),
             sentSimId,
           )
@@ -831,10 +830,10 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
     },
     // 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 that id. null means nothing proves what replaced
-    // it, and the caller must fail rather than guess.
+    // 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 pickReloadedSuccessor(await this.listSims(), retiredSimId)
+      return pickReloadedTarget(await this.listSims(), retiredSimId)
     },
     async focusSim(simId?: string) {
       return this.send({ type: 'focus', simId })