rnxsim 0.0.0 → 0.1.313

package/scripts/dev-server-scanner.ts

@@ -0,0 +1,941 @@
+// shared dev-server scanner used by both the electron main process
+// (`src-electron/main.ts`) and the vite plugin (`vite.config.ts`). discovers
+// running dev servers on localhost by listing every node/bun process that's
+// listening, then probes each port for known bundler signatures.
+//
+// precedence during probing:
+//   1. one/vxrn        (node_modules/one/metro-entry.bundle reachable)
+//   2. metro/expo      (packager-status:running + /_expo/status)
+//   3. expo manifest   (JSON manifest at /)
+//   4. sootsim-patched (/__soot/ middleware present) → /__soot/bundle.js
+//
+// scans are cached per (port, pid). repeat scans with no process changes issue
+// zero HTTP requests; probes only fire when a port appears, disappears, or its
+// pid changes. before any HTTP, a TCP connect gate skips unreachable ports.
+
+import { exec } from 'child_process'
+import { readlink } from 'fs/promises'
+import http from 'http'
+import net from 'net'
+import { resolve } from 'node:path'
+import { promisify } from 'util'
+import type { AppSettingsSpecifier } from '@sootsim/globals'
+
+const execP = promisify(exec)
+import { applySootSimConfigToUrl } from '../src/config.ts'
+import { normalizeNativeDevBundleUrl } from '../src/native-dev-bundle-url.ts'
+import {
+  __resetAppSettingsBundleCacheForTests,
+  readAppSettingsBundle,
+} from '../src/settings-bundle.ts'
+import { loadOptionalDemoApps, optionalDemoAppsSync } from './optional-demo-registry.ts'
+
+export interface DiscoveredServer {
+  port: number
+  framework: 'metro' | 'expo' | 'vxrn' | 'one' | 'unknown'
+  projectName?: string
+  bundleUrl: string
+  hmrUrl?: string
+  lastSeen: number
+  iconUrl?: string
+  iconPath?: string
+  bundleId?: string
+  settingsBundle?: readonly AppSettingsSpecifier[]
+  settingsStorageScopeUrl?: string
+  patched?: boolean
+  /** absolute cwd of the owning node/bun process — resolved from `lsof -d cwd`
+   *  when the scanner can see the pid. used to auto-attach the project for
+   *  agent sessions without requiring a manual `sootsim agent attach`. */
+  cwd?: string
+  pid?: number
+}
+
+// localhost dev servers respond in well under 100ms when alive. drop dead
+// branches fast so a non-bundler process doesn't drag scan latency.
+const TIMEOUT_MS = 250
+// the expo-style manifest GET / is intentionally slower than the cheap
+// signature probes — for One framework apps it serializes app.config.js
+// (including embedded googleServicesFile blobs), which can push the
+// response to 200–400ms on first hit. when this probe times out we fall
+// back to the One-HEAD legacy URL `/node_modules/one/metro-entry.bundle`,
+// which is the path that originally caused the "failed to fetch bundle
+// (404|502)" regression on monorepo One projects (apps/<name>/...). give
+// the manifest more headroom so the canonical launchAsset.url wins.
+const MANIFEST_TIMEOUT_MS = 1500
+// cheap TCP-connect check gate for HTTP probes — if we can't open a socket
+// within this budget the port isn't actually reachable, and all 5 HTTP probes
+// would just time out for nothing.
+const TCP_GATE_MS = 120
+
+interface HttpResult {
+  statusCode: number
+  body: string
+  contentType?: string
+}
+
+// cheap TCP-connect gate. lsof already says the socket is LISTEN, but the
+// process can be closing, the fd can be a different protocol, or a zombie
+// can linger — none of those cases are worth firing 5 HTTP probes at.
+function tcpPing(port: number, timeout = TCP_GATE_MS): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = new net.Socket()
+    let settled = false
+    const done = (ok: boolean) => {
+      if (settled) return
+      settled = true
+      sock.destroy()
+      resolve(ok)
+    }
+    sock.setTimeout(timeout)
+    sock.once('connect', () => done(true))
+    sock.once('timeout', () => done(false))
+    sock.once('error', () => done(false))
+    sock.connect(port, 'localhost')
+  })
+}
+
+function httpGet(
+  port: number,
+  path: string,
+  method: 'GET' | 'HEAD' = 'GET',
+  timeout = TIMEOUT_MS,
+  headers: Record<string, string> = {},
+): Promise<HttpResult | null> {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { hostname: 'localhost', port, path, method, timeout, headers },
+      (res) => {
+        let body = ''
+        res.on('data', (c: Buffer) => (body += c.toString()))
+        const contentType = (() => {
+          const raw = res.headers['content-type']
+          if (typeof raw === 'string') return raw
+          if (Array.isArray(raw)) return raw[0]
+          return undefined
+        })()
+        res.on('end', () =>
+          resolve({ statusCode: res.statusCode || 0, body, contentType }),
+        )
+      },
+    )
+    req.on('error', () => resolve(null))
+    req.setTimeout(timeout, () => {
+      req.destroy()
+      resolve(null)
+    })
+    req.end()
+  })
+}
+
+// ── discovery ───────────────────────────────────────────────────────────────
+
+export interface ListeningProcess {
+  port: number
+  pid: number
+}
+
+// bare-port fallback list used when neither lsof nor ss are usable. pid 0
+// signals "unknown owner" — the cache layer will re-probe these each scan.
+const FALLBACK_PORTS: ListeningProcess[] = [
+  8081, 8082, 8083, 8084, 8085, 8086, 3000, 3001, 19000,
+].map((port) => ({ port, pid: 0 }))
+
+function acceptPort(port: number, excluded: Set<number>): boolean {
+  if (port <= 0 || port >= 20000) return false
+  if (excluded.has(port)) return false
+  // sootsim's own dev server range — we never want to discover ourselves.
+  if (port >= 5170 && port <= 5200) return false
+  return true
+}
+
+export async function discoverListeningProcesses(
+  excludePorts: number[] = [],
+): Promise<ListeningProcess[]> {
+  const excluded = new Set(excludePorts)
+
+  // lsof layout: COMMAND PID USER FD TYPE DEVICE SIZE NODE NAME
+  // NAME looks like "*:8081" or "127.0.0.1:8081" for a LISTEN line.
+  // async exec — sync blocked CrBrowserMain for ~600ms/scan on macOS.
+  try {
+    const { stdout } = await execP(
+      `lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null | grep -E '^(node|bun)'`,
+      { encoding: 'utf8', timeout: 2000 },
+    )
+    if (stdout.trim()) {
+      const seen = new Map<number, number>()
+      for (const line of stdout.trim().split('\n')) {
+        const parts = line.trim().split(/\s+/)
+        if (parts.length < 9) continue
+        const pid = Number(parts[1])
+        const addr = parts[8]
+        const m = addr.match(/:(\d+)$/)
+        if (!m) continue
+        const port = Number(m[1])
+        if (!acceptPort(port, excluded)) continue
+        if (!seen.has(port)) seen.set(port, pid)
+      }
+      if (seen.size > 0) {
+        return [...seen.entries()].map(([port, pid]) => ({ port, pid }))
+      }
+    }
+  } catch {}
+
+  // ss layout: State Recv-Q Send-Q Local-Address:Port Peer-Addr:Port users:(("node",pid=1234,fd=5))
+  try {
+    const { stdout } = await execP(`ss -tlnp 2>/dev/null | grep -E '"(node|bun)"'`, {
+      encoding: 'utf8',
+      timeout: 2000,
+    })
+    if (stdout.trim()) {
+      const seen = new Map<number, number>()
+      for (const line of stdout.trim().split('\n')) {
+        const portMatch = line.match(/:(\d+)\s/)
+        const pidMatch = line.match(/pid=(\d+)/)
+        if (!portMatch) continue
+        const port = Number(portMatch[1])
+        const pid = pidMatch ? Number(pidMatch[1]) : 0
+        if (!acceptPort(port, excluded)) continue
+        if (!seen.has(port)) seen.set(port, pid)
+      }
+      if (seen.size > 0) {
+        return [...seen.entries()].map(([port, pid]) => ({ port, pid }))
+      }
+    }
+  } catch {}
+
+  return FALLBACK_PORTS.filter((p) => acceptPort(p.port, excluded))
+}
+
+// kept for backwards compatibility with any external callers that only need
+// port numbers. internal paths should prefer discoverListeningProcesses so
+// the (port, pid) cache can detect process restarts.
+export async function discoverListeningPorts(
+  excludePorts: number[] = [],
+): Promise<number[]> {
+  const processes = await discoverListeningProcesses(excludePorts)
+  return processes.map((p) => p.port)
+}
+
+/** parse `netstat -anv -p tcp` output for the pid listening on one port.
+ *
+ *  macOS lays a LISTEN row out as
+ *    tcp4 0 0 127.0.0.1.8090 *.* LISTEN 0 0 131072 131072 node:97330 ...
+ *  so the local address is the 4th column with a DOT before the port (which is
+ *  what keeps port 8137 from matching a row for 18137), and the owner is the
+ *  only token shaped "<name>:<pid>".
+ *
+ *  exported because this column layout is the fragile part and a child process
+ *  cannot exercise it under bun's test runner, which hands back empty stdout. */
+export function pidFromNetstat(stdout: string, port: number): number | null {
+  for (const line of stdout.split('\n')) {
+    if (!line.includes('LISTEN')) continue
+    const parts = line.trim().split(/\s+/)
+    if (!parts[3]?.endsWith(`.${port}`)) continue
+    for (const token of parts) {
+      const owner = token.match(/^\S+:(\d+)$/)
+      if (owner) {
+        const pid = Number(owner[1])
+        if (pid > 0) return pid
+      }
+    }
+  }
+  return null
+}
+
+/** resolve the pid of the process listening on one local port.
+ *
+ *  `lsof` walks every descriptor of every process, which measures 2-4s on a
+ *  loaded machine — longer than any timeout worth giving it, so
+ *  `discoverListeningProcesses` above degrades to its pid-less port list
+ *  exactly when the machine is busy. netstat (macOS/BSD) and ss (linux) read
+ *  the kernel socket table instead and answer in well under a second, and both
+ *  carry the owning pid. use this whenever the question is "who owns this one
+ *  port"; `discoverListeningProcesses` answers the different question of what
+ *  is listening at all. */
+export async function resolveListeningPid(port: number): Promise<number | null> {
+  if (!Number.isInteger(port) || port <= 0) return null
+
+  // macOS netstat: "tcp4 0 0 127.0.0.1.8090 *.* LISTEN ... node:97330 ..."
+  // the local address uses a dot before the port, and the owner column is the
+  // only token shaped "<name>:<pid>".
+  try {
+    const { stdout } = await execP('netstat -anv -p tcp 2>/dev/null', {
+      encoding: 'utf8',
+      timeout: 8000,
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    const pid = pidFromNetstat(stdout, port)
+    if (pid !== null) return pid
+  } catch {}
+
+  // linux ss: 'LISTEN 0 511 0.0.0.0:8081 0.0.0.0:* users:(("node",pid=1234,fd=5))'
+  try {
+    const { stdout } = await execP(`ss -tlnp 2>/dev/null`, {
+      encoding: 'utf8',
+      timeout: 8000,
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    for (const line of stdout.split('\n')) {
+      if (!new RegExp(`:${port}\\s`).test(line)) continue
+      const pid = Number(line.match(/pid=(\d+)/)?.[1])
+      if (pid > 0) return pid
+    }
+  } catch {}
+
+  return null
+}
+
+// per-pid cwd cache. lsof is the only way to read another process's cwd on
+// macOS and it is NOT cheap — measured at 3-8s for a single pid on a machine
+// running a few dozen node processes — so caching the result until the pid
+// goes away is what keeps the 5s tray scan viable.
+const cwdByPid = new Map<number, string>()
+
+/** resolve the current working directory of a pid. returns null for pid 0
+ *  (unknown owner) and whenever neither mechanism below can see the process.
+ *  async — sync exec blocked CrBrowserMain at ~600ms on macOS.
+ *
+ *  `-b -w` skips the blocking stat calls lsof otherwise makes against every
+ *  mount, which roughly halves it. the timeout is generous because the answer
+ *  is cached per pid: too tight a limit silently returns null on exactly the
+ *  busy machines where auto-attaching a project matters most. */
+export async function resolveProcessCwd(pid: number): Promise<string | null> {
+  if (pid <= 0) return null
+  const cached = cwdByPid.get(pid)
+  if (cached) return cached
+
+  // linux publishes the cwd as a symlink, which costs one readlink and no
+  // subprocess at all. macOS has no /proc and has to pay for lsof below.
+  try {
+    const cwd = await readlink(`/proc/${pid}/cwd`)
+    if (cwd) {
+      cwdByPid.set(pid, cwd)
+      return cwd
+    }
+  } catch {}
+
+  try {
+    // -Fn → machine-readable, one field per line. lines look like:
+    //   p<pid>
+    //   fcwd
+    //   n<absolute path>
+    const { stdout } = await execP(`lsof -b -w -p ${pid} -a -d cwd -Fn 2>/dev/null`, {
+      encoding: 'utf8',
+      timeout: 8000,
+    })
+    for (const line of stdout.split('\n')) {
+      if (line.startsWith('n') && line.length > 1) {
+        const cwd = line.slice(1).trim()
+        if (cwd) {
+          cwdByPid.set(pid, cwd)
+          return cwd
+        }
+      }
+    }
+  } catch {}
+  return null
+}
+
+// ── per-port probe orchestration ────────────────────────────────────────────
+
+function makeResult(
+  port: number,
+  framework: DiscoveredServer['framework'],
+  owner: Pick<DiscoveredServer, 'cwd' | 'pid'>,
+): DiscoveredServer {
+  return {
+    port,
+    framework,
+    bundleUrl: withRuntimeConfig(
+      port,
+      `http://localhost:${port}/index.bundle?platform=ios&dev=true&hot=true&minify=false`,
+      owner.cwd,
+    ),
+    hmrUrl: `ws://localhost:${port}/hot`,
+    lastSeen: Date.now(),
+    ...owner,
+  }
+}
+
+function withRuntimeConfig(port: number, bundleUrl: string, projectCwd?: string): string {
+  const knownApp = projectCwd
+    ? optionalDemoAppsSync().find(
+        (app) => app.preferredPort === port && resolve(app.dir) === resolve(projectCwd),
+      )
+    : undefined
+  const configured = knownApp?.runtimeConfig
+    ? applySootSimConfigToUrl(bundleUrl, knownApp.runtimeConfig)
+    : bundleUrl
+  return normalizeNativeDevBundleUrl(configured)
+}
+
+function isDirectOneBundleUrl(bundleUrl: string): boolean {
+  return bundleUrl.includes('/node_modules/one/metro-entry.bundle')
+}
+
+function safeParseManifest(body: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+// fold expo manifest fields (name, icon, bundleId, launchAsset) into a result.
+// the manifest body is always the GET / response we already have from probePort,
+// so this never issues another http request.
+function applyManifest(
+  result: DiscoveredServer,
+  manifestRes: HttpResult | null,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+): DiscoveredServer {
+  if (!manifestRes) return result
+  try {
+    const manifest = JSON.parse(manifestRes.body)
+    const client = manifest?.extra?.expoClient || manifest?.extra || {}
+    if (client.name) result.projectName = client.name
+    if (client.ios?.bundleIdentifier) result.bundleId = client.ios.bundleIdentifier
+    if (result.framework === 'metro' && client.sdkVersion) result.framework = 'expo'
+    // preserve a confirmed direct one/vxrn metro-entry bundle. expo manifests
+    // and one/vxrn manifests point at a launchAsset URL with `hot=false`
+    // (hardcoded by @expo/cli — see metroOptions.ts). that's the same URL
+    // real iOS sims load, so sootsim uses it verbatim to share metro's
+    // bundle cache; HMR still works via sootsim's HmrClient.
+    const launchUrl = manifest?.launchAsset?.url
+    if (launchUrl && !result.patched && !isDirectOneBundleUrl(result.bundleUrl)) {
+      result.bundleUrl = withRuntimeConfig(result.port, launchUrl, result.cwd)
+    }
+    const rawIconUrl =
+      client.iconUrl || client.ios?.iconUrl || client.icon || client.ios?.icon
+    if (rawIconUrl) {
+      result.iconPath = rawIconUrl
+      if (buildIconProxyUrl) {
+        if (rawIconUrl.startsWith('http')) {
+          result.iconUrl = buildIconProxyUrl(rawIconUrl)
+        } else {
+          const cleanPath = rawIconUrl.replace(/^\.\//, '')
+          result.iconUrl = buildIconProxyUrl(
+            `http://localhost:${result.port}/assets/${cleanPath}`,
+          )
+        }
+      } else {
+        // no proxy requested — use the raw URL
+        result.iconUrl = rawIconUrl.startsWith('http')
+          ? rawIconUrl
+          : `http://localhost:${result.port}/assets/${rawIconUrl.replace(/^\.\//, '')}`
+      }
+    }
+  } catch {}
+  return result
+}
+
+export function __applyManifestForTests(
+  result: DiscoveredServer,
+  manifestBody: string,
+): DiscoveredServer {
+  return applyManifest(result, { statusCode: 200, body: manifestBody })
+}
+
+// ── name/icon enrichment ────────────────────────────────────────────────────
+// a server's display name + icon come ONLY from its expo manifest (GET / with
+// expo-platform), which is far slower than the cheap signature probes: One apps
+// serialize app.config per request, and some (expo-updates / asset resolution)
+// block several seconds. the fast probe race times the manifest out at
+// MANIFEST_TIMEOUT_MS, so a slow-manifest server is identified via /status or
+// the One HEAD with no projectName and shows as ":<port>" in the dock — never
+// re-probed, because that nameless result caches as a strong (expo/one) entry.
+// bumping the race timeout isn't an option: it would stall every probe (and a
+// non-bundler node process) for seconds. instead capture name/icon out-of-band:
+// when a server is identified without them, fetch the manifest ONCE with a
+// generous timeout, cache the fields per port, and drop the strong port-cache
+// entry so the next scan re-probes and publishes the enriched server. discovery
+// stays fast; name/icon fill in a scan or two after the app first appears.
+const ENRICH_TIMEOUT_MS = 20_000
+interface ManifestEnrichment {
+  projectName?: string
+  iconUrl?: string
+  iconPath?: string
+  bundleId?: string
+}
+const enrichmentCache = new Map<number, ManifestEnrichment>()
+const enrichmentInFlight = new Set<number>()
+
+// apply already-captured name/icon, or kick off a single background manifest
+// fetch to capture them. a no-op once the in-race manifest already named the
+// server, so it's safe to wrap every identified return.
+function enrichWithManifest(
+  result: DiscoveredServer,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+): DiscoveredServer {
+  if (result.projectName) return result
+
+  const cached = enrichmentCache.get(result.port)
+  if (cached) {
+    if (cached.projectName) result.projectName = cached.projectName
+    if (cached.iconUrl && !result.iconUrl) {
+      result.iconUrl = cached.iconUrl
+      result.iconPath = cached.iconPath
+    }
+    if (cached.bundleId && !result.bundleId) result.bundleId = cached.bundleId
+    return result
+  }
+
+  if (!enrichmentInFlight.has(result.port)) {
+    enrichmentInFlight.add(result.port)
+    const port = result.port
+    void fetchManifestEnrichment(port, buildIconProxyUrl).finally(() =>
+      enrichmentInFlight.delete(port),
+    )
+  }
+  return result
+}
+
+async function fetchManifestEnrichment(
+  port: number,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+): Promise<void> {
+  const manifestRes = await httpGet(port, '/', 'GET', ENRICH_TIMEOUT_MS, {
+    'expo-platform': 'ios',
+  })
+  if (!manifestRes || manifestRes.statusCode !== 200) return
+  // reuse applyManifest's exact field extraction against a throwaway result.
+  const parsed = applyManifest(
+    { port, framework: 'one', bundleUrl: '', lastSeen: 0 },
+    manifestRes,
+    buildIconProxyUrl,
+  )
+  if (!parsed.projectName && !parsed.iconUrl) return
+  enrichmentCache.set(port, {
+    projectName: parsed.projectName,
+    iconUrl: parsed.iconUrl,
+    iconPath: parsed.iconPath,
+    bundleId: parsed.bundleId,
+  })
+  // the nameless result cached as a strong entry and won't re-probe on its own;
+  // drop it so the next scan re-runs probePort and publishes the enriched name.
+  portCache.delete(port)
+}
+
+// ports confirmed to be running a non-sootsim dev server — safe to skip the
+// /__soot/ probe on subsequent scans. cleared when the port disappears from the
+// listening set (process restarted, could now be a different server).
+const knownNonPatched = new Set<number>()
+
+// ports confirmed to not answer /_expo/status as an expo packager — safe to
+// skip that probe on subsequent scans. same invalidation rule as
+// knownNonPatched: cleared when the port's owning pid changes.
+const knownNonExpo = new Set<number>()
+
+// ports confirmed to be a one/vxrn dev server. on these, we skip the manifest
+// probe (`GET /` with expo-platform headers) on subsequent scans: one already
+// served the bundle HEAD so we know what it is, AND one's Expo Go manifest
+// middleware crashes the whole server when a probe aborts mid-stream
+// (Cannot pipe to a closed or destroyed stream → unhandled rejection → exit).
+// the bundle URL is enough; no information is lost by skipping the manifest.
+// same invalidation rules as knownNonPatched/knownNonExpo: cleared on port
+// disappearance, owning-pid change, and __resetScannerCache.
+const knownOne = new Set<number>()
+
+// fire signature probes in waves and pick the best match by precedence:
+//   1. expo manifest   (JSON manifest at /)
+//   2. metro/expo      (packager-status:running on /status)
+//   3. sootsim-patched (/__soot/)
+//   4. one/vxrn        (HEAD on /node_modules/one/metro-entry.bundle) — only
+//                       fires as a true last resort; on expo apps this probe
+//                       crashes metro by triggering HmrServer.registerEntryPoint
+//                       for a path metro can't resolve, so we never fire it
+//                       when one of the higher-precedence probes already
+//                       identified the server.
+// cheapest check first: a TCP connect gate short-circuits all HTTP probes when
+// the port isn't actually reachable (zombie listener, non-http protocol,
+// process mid-shutdown). after that, racing the safe probes is fast —
+// localhost refuses/closes connections quickly, and Promise.all finishes at
+// the slowest single probe rather than the sum.
+export async function probePort(
+  port: number,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+  listeningProcess?: ListeningProcess,
+): Promise<DiscoveredServer | null> {
+  // callers such as `sootsim open <port>` probe one port directly instead of
+  // going through scanDevServers. wait for the optional in-repo registry here
+  // too, or a cold CLI process can build the known app's bundle url before its
+  // runtime config is available.
+  await loadOptionalDemoApps()
+  if (!(await tcpPing(port))) return null
+
+  const suppliedPid = listeningProcess?.pid
+  const ownerPid =
+    suppliedPid && suppliedPid > 0 ? suppliedPid : await resolveListeningPid(port)
+  const ownerCwd = ownerPid ? await resolveProcessCwd(ownerPid) : null
+  const owner: Pick<DiscoveredServer, 'cwd' | 'pid'> = {
+    ...(ownerPid ? { pid: ownerPid } : {}),
+    ...(ownerCwd ? { cwd: ownerCwd } : {}),
+  }
+
+  const onePath = `/node_modules/one/metro-entry.bundle?platform=ios&dev=true`
+
+  // wave 1 — safe parallel probes. none of these mutate metro state.
+  const [sootsimRes, statusRes, manifestRes, expoRes] = await Promise.all([
+    knownNonPatched.has(port) ? Promise.resolve(null) : httpGet(port, '/__soot/'),
+    httpGet(port, '/status'),
+    knownOne.has(port)
+      ? Promise.resolve(null)
+      : httpGet(port, '/', 'GET', MANIFEST_TIMEOUT_MS, { 'expo-platform': 'ios' }),
+    knownNonExpo.has(port) ? Promise.resolve(null) : httpGet(port, '/_expo/status'),
+  ])
+
+  // remember negative /_expo/status responses so we don't keep probing this
+  // endpoint on ports that clearly aren't expo packagers (one/vxrn, vite,
+  // random node processes). a 200 flips the port out of the non-expo set.
+  if (expoRes && expoRes.statusCode === 200) {
+    knownNonExpo.delete(port)
+  } else if (!knownNonExpo.has(port)) {
+    knownNonExpo.add(port)
+  }
+
+  // expo manifest (One framework + expo apps both serve this at `/` with the
+  // expo-platform header). when present, `launchAsset.url` is the canonical
+  // bundle URL the app actually serves — for One projects it's the
+  // monorepo-aware path (e.g. /apps/one/node_modules/one/metro-entry.bundle
+  // with full hermes transform params), and for Expo it's /index.bundle with
+  // the right transforms. either way it's strictly better than the bare
+  // /node_modules/one/metro-entry.bundle constant we used as a discriminator
+  // below, so we check the manifest FIRST.
+  const manifestParsed = manifestRes
+    ? (safeParseManifest(manifestRes.body) as {
+        launchAsset?: { url?: unknown }
+        extra?: { expoClient?: { name?: unknown }; name?: unknown }
+      } | null)
+    : null
+  const manifestLaunchUrl =
+    typeof manifestParsed?.launchAsset?.url === 'string'
+      ? manifestParsed.launchAsset.url
+      : null
+  const manifestClient =
+    (manifestParsed?.extra?.expoClient as { name?: unknown } | undefined) ||
+    (manifestParsed?.extra as { name?: unknown } | undefined) ||
+    {}
+  if (manifestParsed && (manifestLaunchUrl || typeof manifestClient.name === 'string')) {
+    knownNonPatched.add(port)
+    const launchUrl =
+      manifestLaunchUrl ||
+      `http://localhost:${port}/index.bundle?platform=ios&dev=true&hot=true&minify=false`
+    // call the framework "one" only when launchAsset clearly points at
+    // a One metro entry; otherwise treat it as plain expo so downstream
+    // bundle handling uses the right path semantics.
+    const framework: DiscoveredServer['framework'] = launchUrl.includes(
+      '/one/metro-entry.bundle',
+    )
+      ? 'one'
+      : 'expo'
+    return applyManifest(
+      {
+        port,
+        framework,
+        bundleUrl: withRuntimeConfig(port, launchUrl, owner.cwd),
+        hmrUrl: `ws://localhost:${port}/hot`,
+        lastSeen: Date.now(),
+        ...owner,
+      },
+      manifestRes,
+      buildIconProxyUrl,
+    )
+  }
+
+  // metro/expo — packager-status:running on /status. checked BEFORE the one
+  // HEAD because the HEAD has a known side-effect: it triggers metro's
+  // HmrServer.registerEntryPoint for `/node_modules/one/metro-entry.bundle`,
+  // and on metro instances where that path doesn't resolve (i.e. any plain
+  // expo app) metro crashes with "UnableToResolveError" and exits. by
+  // identifying expo/metro instances here from their /status response we
+  // never fire the HEAD against them.
+  if (statusRes && statusRes.body.includes('packager-status:running')) {
+    knownNonPatched.add(port)
+    return enrichWithManifest(
+      applyManifest(
+        makeResult(port, expoRes && expoRes.statusCode === 200 ? 'expo' : 'metro', owner),
+        manifestRes,
+        buildIconProxyUrl,
+      ),
+      buildIconProxyUrl,
+    )
+  }
+
+  // patched sootsim — fallback for legacy /__soot/ patched servers. also
+  // checked before the one HEAD for the same reason.
+  if (
+    sootsimRes &&
+    sootsimRes.statusCode === 200 &&
+    sootsimRes.body.includes('sootsim-patched')
+  ) {
+    knownNonPatched.delete(port)
+    return enrichWithManifest(
+      applyManifest(
+        {
+          port,
+          framework: 'one',
+          bundleUrl: withRuntimeConfig(
+            port,
+            `http://localhost:${port}/__soot/bundle.js`,
+            owner.cwd,
+          ),
+          hmrUrl: `ws://localhost:${port}/hot`,
+          lastSeen: Date.now(),
+          patched: true,
+          ...owner,
+        },
+        manifestRes,
+        buildIconProxyUrl,
+      ),
+      buildIconProxyUrl,
+    )
+  }
+
+  // wave 2 — one/vxrn HEAD probe. only fired as a true last resort, since
+  // it has the metro side-effect documented above. older One bare-dev-server
+  // setups that don't serve a manifest still resolve through this path; new
+  // expo/metro/one setups are caught above and never reach here.
+  //
+  // hard safety gate (the recurring "metro on 8081 crashes" regression): a
+  // plain expo/metro packager that is still BOOTING serves `/status`,
+  // `/_expo/status`, and the `/` manifest a few seconds apart, so during the
+  // boot window all three wave-1 catches above can miss (status body not yet
+  // `packager-status:running`, manifest not yet parseable). without this gate
+  // we then fire the lethal HEAD against a metro that IS a metro — and the
+  // engine, handed a bogus `one/metro-entry.bundle` URL, opens an HMR socket
+  // whose `register-entrypoints` throws UnableToResolveError inside
+  // HmrServer._registerEntryPoint → unhandledRejection → metro exits. a real
+  // legacy bare-One dev server answers NONE of these metro/expo endpoints, so
+  // skipping the HEAD here never hides a genuine One server — it just defers
+  // this port to the next scan, by which point wave 1 identifies it cleanly.
+  const looksLikeMetroPackager =
+    (statusRes && statusRes.statusCode === 200) ||
+    (expoRes && expoRes.statusCode === 200) ||
+    (manifestRes && manifestRes.statusCode === 200 && manifestParsed != null)
+  if (looksLikeMetroPackager) {
+    // do NOT cache as knownNonPatched — we want a fresh wave-1 pass next scan
+    // once the packager finishes booting and its manifest/status are ready.
+    return null
+  }
+
+  const oneRes = await httpGet(port, onePath, 'HEAD')
+  if (
+    oneRes &&
+    oneRes.statusCode > 0 &&
+    oneRes.statusCode < 400 &&
+    /application\/javascript/i.test(oneRes.contentType || '')
+  ) {
+    knownNonPatched.add(port)
+    knownOne.add(port)
+    return enrichWithManifest(
+      applyManifest(
+        {
+          port,
+          framework: 'one',
+          bundleUrl: withRuntimeConfig(
+            port,
+            `http://localhost:${port}${onePath}&minify=false`,
+            owner.cwd,
+          ),
+          hmrUrl: `ws://localhost:${port}/hot`,
+          lastSeen: Date.now(),
+          ...owner,
+        },
+        manifestRes,
+        buildIconProxyUrl,
+      ),
+      buildIconProxyUrl,
+    )
+  }
+
+  knownNonPatched.add(port)
+  return null
+}
+
+// ── top-level convenience ───────────────────────────────────────────────────
+
+export interface ScanOptions {
+  excludePorts?: number[]
+  buildIconProxyUrl?: (externalUrl: string) => string
+}
+
+function isSootSimSelfServer(server: DiscoveredServer): boolean {
+  const bundleId = server.bundleId?.trim().toLowerCase()
+  if (bundleId?.startsWith('dev.sootsim.')) return true
+
+  return false
+}
+
+export const __isSootSimSelfServerForTests = isSootSimSelfServer
+
+// per-(port, pid) probe cache. as long as the same process still owns the
+// port, its signature endpoints can't have changed, so we return the cached
+// result without issuing any HTTP. negative results (null) are cached too,
+// which prevents repeat-probing node/bun processes that aren't dev servers.
+// invalidation is cheap: we drop any entry whose port dropped out of lsof,
+// and any entry whose pid changed (process restart).
+interface PortCacheEntry {
+  pid: number
+  result: DiscoveredServer | null
+  cachedAt: number
+}
+const portCache = new Map<number, PortCacheEntry>()
+
+// negative-cache holds a node/bun port that isn't a bundler (e.g. Contrast's own
+// api server, Zero, SQLite sync host, a dev tool). at scan interval 3s and a 1.5s ttl
+// we used to re-probe every scan, which hits `/` on the port every 3s — that
+// waking Contrast's SSR router ~20x/min was a real memory-leak driver. 30s gives
+// the scanner a much lighter touch on unrelated node processes while still
+// catching pid-change invalidation immediately when a process restarts.
+const NEGATIVE_CACHE_TTL_MS = 30_000
+const WEAK_RESULT_CACHE_TTL_MS = 1_500
+
+function isWeakCachedResult(result: DiscoveredServer | null): boolean {
+  if (!result) return true
+  if (result.framework === 'metro' || result.framework === 'unknown') return true
+  return false
+}
+
+function hasCurrentRuntimeConfig(result: DiscoveredServer | null): boolean {
+  if (!result) return true
+  return withRuntimeConfig(result.port, result.bundleUrl, result.cwd) === result.bundleUrl
+}
+
+export function __shouldReuseScannerCacheEntry(
+  entry: { pid: number; result: DiscoveredServer | null; cachedAt: number },
+  pid: number,
+  now = Date.now(),
+): boolean {
+  if (pid === 0) return false
+  if (entry.pid !== pid) return false
+  if (!hasCurrentRuntimeConfig(entry.result)) return false
+
+  const ageMs = now - entry.cachedAt
+  if (entry.result === null && ageMs >= NEGATIVE_CACHE_TTL_MS) return false
+  if (isWeakCachedResult(entry.result) && ageMs >= WEAK_RESULT_CACHE_TTL_MS) return false
+  return true
+}
+
+// exported for tests / `sootsim debug` — forces the next scan to re-probe.
+export function __resetScannerCache() {
+  portCache.clear()
+  knownNonPatched.clear()
+  knownNonExpo.clear()
+  knownOne.clear()
+  enrichmentCache.clear()
+  enrichmentInFlight.clear()
+  __resetAppSettingsBundleCacheForTests()
+}
+
+async function attachAppSettingsBundle(
+  result: DiscoveredServer,
+  projectRoot: string,
+): Promise<void> {
+  const settingsBundle = await readAppSettingsBundle(projectRoot)
+  if (settingsBundle) {
+    result.settingsBundle = settingsBundle
+    result.settingsStorageScopeUrl = result.bundleUrl
+  } else {
+    delete result.settingsBundle
+    delete result.settingsStorageScopeUrl
+  }
+}
+
+export const __attachAppSettingsBundleForTests = attachAppSettingsBundle
+
+export async function scanDevServers(
+  opts: ScanOptions = {},
+): Promise<DiscoveredServer[]> {
+  // optionalDemoAppsSync() returns [] until the dynamic import resolves, and
+  // an empty registry is indistinguishable from a published install. await it
+  // before cache validation so a known app cannot lose its runtimeConfig when
+  // disk contention delays the import. memoized, so this is free after the
+  // first call.
+  await loadOptionalDemoApps()
+  const processes = await discoverListeningProcesses(opts.excludePorts)
+  const currentPorts = new Set(processes.map((p) => p.port))
+
+  // evict cache entries for ports that disappeared. a restarted process may
+  // bring up a different server (possibly sootsim-patched) on the same port,
+  // and both caches need to let go so the next probe sees the new state.
+  for (const p of [...portCache.keys()]) {
+    if (!currentPorts.has(p)) portCache.delete(p)
+  }
+  for (const p of [...knownNonPatched]) {
+    if (!currentPorts.has(p)) knownNonPatched.delete(p)
+  }
+  for (const p of [...knownNonExpo]) {
+    if (!currentPorts.has(p)) knownNonExpo.delete(p)
+  }
+  for (const p of [...knownOne]) {
+    if (!currentPorts.has(p)) knownOne.delete(p)
+  }
+  for (const p of [...enrichmentCache.keys()]) {
+    if (!currentPorts.has(p)) enrichmentCache.delete(p)
+  }
+
+  const results: DiscoveredServer[] = []
+  const toProbe: ListeningProcess[] = []
+
+  for (const { port, pid } of processes) {
+    const cached = portCache.get(port)
+    // pid 0 means the platform couldn't identify the owner (fallback path),
+    // so we can't trust the cache — reprobe.
+    if (cached && __shouldReuseScannerCacheEntry(cached, pid)) {
+      if (cached.result) results.push(cached.result)
+      continue
+    }
+    // pid changed or cache expired — drop any endpoint-specific verdicts so
+    // the re-probe starts from scratch. otherwise a restarted process that
+    // swapped frameworks keeps the old skip-/__soot/ or skip-/_expo/status
+    // decisions, and the scanner never discovers the new server.
+    if (cached && cached.pid !== pid) {
+      knownNonPatched.delete(port)
+      knownNonExpo.delete(port)
+      knownOne.delete(port)
+      // a restarted process may be a different app — drop its captured name/icon.
+      enrichmentCache.delete(port)
+    }
+    toProbe.push({ port, pid })
+  }
+
+  if (toProbe.length > 0) {
+    const probed = await Promise.all(
+      toProbe.map((p) => probePort(p.port, opts.buildIconProxyUrl, p)),
+    )
+    probed.forEach((result, i) => {
+      const { port, pid } = toProbe[i]
+      // only cache when we have a real pid to key the entry against.
+      // fallback-list ports (pid 0) always reprobe so we catch state changes.
+      if (pid !== 0) portCache.set(port, { pid, result, cachedAt: Date.now() })
+      if (result) results.push(result)
+    })
+  }
+
+  // attach pid + cwd. pid comes from the listening-process scan; cwd is
+  // lsof-resolved and cached per pid. both enable auto-attach of agent
+  // sessions to the right project without a manual `sootsim agent attach`.
+  const pidByPort = new Map<number, number>()
+  for (const { port, pid } of processes) {
+    if (pid > 0) pidByPort.set(port, pid)
+  }
+  await Promise.all(
+    results.map(async (result) => {
+      const pid = pidByPort.get(result.port)
+      if (!pid) return
+      result.pid = pid
+      const cwd = await resolveProcessCwd(pid)
+      if (!cwd) return
+      result.cwd = cwd
+      await attachAppSettingsBundle(result, cwd)
+    }),
+  )
+  // evict stale cwd cache entries for pids no longer listening
+  const livePids = new Set(pidByPort.values())
+  for (const pid of [...cwdByPid.keys()]) {
+    if (!livePids.has(pid)) cwdByPid.delete(pid)
+  }
+
+  return results.filter((r) => !isSootSimSelfServer(r))
+}