peachsim 0.1.527

package/scripts/dev-server-scanner.ts

@@ -0,0 +1,1291 @@
+// 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 { realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
+import {
+  buildLoopbackProbeBaseUrl,
+  isLoopbackHost,
+  LOOPBACK_PROBE_HOSTNAMES,
+  normalizeHostname,
+} from '../src/backend-origin.ts'
+import { applyRNXConfigToUrl } from '../src/config.ts'
+import {
+  alignLoopbackBundleUrlWithProbe,
+  normalizeNativeDevBundleUrl,
+} from '../src/native-dev-bundle-url.ts'
+import {
+  __resetAppSettingsBundleCacheForTests,
+  readAppSettingsBundle,
+} from '../src/settings-bundle.ts'
+import { loadOptionalDemoApps, optionalDemoAppsSync } from './optional-demo-registry.ts'
+import type { AppSettingsSpecifier } from '@rnx/globals'
+
+// how long past a command's own budget we wait before deciding its exit event is
+// never coming. generous, because this only fires when the child is already
+// overdue and we are choosing between a wrong answer and a hang.
+const EXEC_EXIT_GRACE_MS = 2_000
+
+/** every subprocess in this file goes through here.
+ *
+ *  `exec`'s own `timeout` option is NOT a backstop. it kills the child and then
+ *  STILL waits for a 'close' event to settle the promise, so when that event is
+ *  lost the promise never settles — the timeout is already spent and nothing is
+ *  left to rescue it. (same failure m10843 pinned in `CheckoutFilePlane.refresh`.)
+ *  `lsof` walks every open fd on the machine, which makes it a realistic victim.
+ *
+ *  a hung scan is worse than a slow one: `inflightScan` never clears, so
+ *  `/__server-scan` stops answering at all instead of answering "could not
+ *  look". so we race the child against a real wall-clock deadline and reject
+ *  with `killed`, which callers already read as could-not-look. */
+async function execGuarded(
+  command: string,
+  timeout: number,
+  extra: { maxBuffer?: number } = {},
+): Promise<{ stdout: string }> {
+  let child: ReturnType<typeof exec> | undefined
+  const ran = new Promise<{ stdout: string }>((resolve, reject) => {
+    child = exec(command, { encoding: 'utf8', timeout, ...extra }, (err, stdout) => {
+      if (err) reject(err)
+      else resolve({ stdout })
+    })
+  })
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<never>((_resolve, reject) => {
+    deadlineTimer = setTimeout(() => {
+      child?.kill('SIGKILL')
+      const err = new Error(`\`${command}\` did not exit within ${timeout}ms`)
+      // matches the shape `wasKilledByTimeout` reads off a real exec timeout, so
+      // a lost exit event and a genuine timeout reach callers as the same fact.
+      Object.assign(err, { killed: true })
+      reject(err)
+    }, timeout + EXEC_EXIT_GRACE_MS)
+  })
+  try {
+    return await Promise.race([ran, deadline])
+  } finally {
+    // the race is settled, so drop the deadline rather than leaving it pending.
+    clearTimeout(deadlineTimer)
+  }
+}
+
+export interface DiscoveredServer {
+  port: number
+  framework: 'metro' | 'expo' | 'vxrn' | 'one' | 'unknown'
+  projectName?: string
+  bundleUrl: string
+  hmrUrl?: string
+  lastSeen: number
+  iconUrl?: string
+  iconPath?: string
+  /** the app's own brand colour from its manifest, used as the home tile's
+   *  background so the tile reads as that app before its icon decodes and
+   *  when the icon is missing entirely. */
+  primaryColor?: string
+  bundleId?: string
+  settingsBundle?: readonly AppSettingsSpecifier[]
+  settingsStorageScopeUrl?: string
+  patched?: boolean
+  /** true when `bundleUrl` was NOT derived from the server's own manifest —
+   *  the manifest probe got no answer, so this is the generic `/index.bundle`
+   *  guess. good enough to LIST the server; never good enough to open it. see
+   *  `manifestState` below for why the two are different answers. */
+  bundleUrlProvisional?: 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
+}
+
+/** how the manifest probe (`GET /` with expo-platform) actually went. the same
+ *  three answers `dev-bundle-resolution.ts` uses, deliberately spelled the same
+ *  way: a second vocabulary for one question is how the two resolvers drift.
+ *
+ *  the rule this encodes, which the whole scanner depends on: A PROBE THAT
+ *  COULD NOT LOOK MUST NEVER ANSWER AS THOUGH IT LOOKED. silence, timeout and
+ *  empty are three different answers, and only `no-manifest` means "there is
+ *  nothing there". reading `no-answer` as `no-manifest` is what made
+ *  `rnx open` hand back `<base>/index.bundle` for a One app whose manifest
+ *  names a different entry point entirely. */
+type ManifestState = 'resolved' | 'no-manifest' | 'no-answer'
+
+// 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
+// once a server has sent response headers we never abort it (see httpGet). this
+// only bounds a response that never ends, so it is deliberately far above any
+// real manifest: aborting a slow-but-answering server is the defect this whole
+// path exists to avoid.
+const BODY_TIMEOUT_MS = 30_000
+
+interface HttpResult {
+  statusCode: number
+  body: string
+  contentType?: string
+  hostname: 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.
+async function tcpPing(port: number, timeout = TCP_GATE_MS): Promise<string | null> {
+  try {
+    return await Promise.any(
+      LOOPBACK_PROBE_HOSTNAMES.map(
+        (hostname) =>
+          new Promise<string>((resolve, reject) => {
+            const sock = new net.Socket()
+            let settled = false
+            const done = (reachable: boolean) => {
+              if (settled) return
+              settled = true
+              sock.destroy()
+              if (reachable) resolve(hostname)
+              else reject(new Error(`unreachable loopback host ${hostname}`))
+            }
+            sock.setTimeout(timeout)
+            sock.once('connect', () => done(true))
+            sock.once('timeout', () => done(false))
+            sock.once('error', () => done(false))
+            sock.connect(port, hostname)
+          }),
+      ),
+    )
+  } catch {
+    return null
+  }
+}
+
+function httpGet(
+  hostname: string,
+  port: number,
+  path: string,
+  method: 'GET' | 'HEAD' = 'GET',
+  timeout = TIMEOUT_MS,
+  headers: Record<string, string> = {},
+): Promise<HttpResult | null> {
+  return new Promise((resolve) => {
+    // first answer wins: the response, the deadline, and the connection closing
+    // all race, and every one of them can arrive after another has decided.
+    let settled = false
+    const settle = (value: HttpResult | null) => {
+      if (settled) return
+      settled = true
+      resolve(value)
+    }
+    // NO socket timeout here, deliberately. `options.timeout` / `req.setTimeout`
+    // make node DESTROY the connection when the budget expires, and destroying a
+    // dev server's connection while it is still assembling its manifest fires
+    // "Cannot pipe to a closed or destroyed stream" into One's manifest
+    // middleware as an unhandled rejection — the hazard the knownOne comment
+    // below already documents, which can exit the user's dev server. measured:
+    // six probes with a socket timeout produced six of those errors, six probes
+    // that give up in JS produced none, and the request completes later with the
+    // server none the wiser.
+    //
+    // giving up WAITING and KILLING THE REQUEST are different acts, and only the
+    // first one is ours to take. the deadline below resolves the scan on time;
+    // the request runs itself out in the background and its result is discarded.
+    const req = http.request({ hostname, port, path, method, 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', () =>
+        settle({
+          statusCode: res.statusCode || 0,
+          body,
+          contentType,
+          hostname,
+        }),
+      )
+    })
+    req.on('error', () => settle(null))
+    req.end()
+    const giveUp = setTimeout(() => {
+      settle(null)
+      // nothing is waiting on it now, so it must not hold a CLI process open.
+      req.socket?.unref()
+    }, timeout)
+    // the only thing that ever destroys a connection here. by BODY_TIMEOUT_MS a
+    // server has long since answered or died, so there is no live write to cut.
+    const abandon = setTimeout(() => req.destroy(), BODY_TIMEOUT_MS)
+    req.on('close', () => {
+      clearTimeout(giveUp)
+      clearTimeout(abandon)
+      // `close` on the request fires BEFORE the response's own `end` handler,
+      // so settling synchronously here turns every successful probe into a
+      // null. defer one tick and let a real answer win; this only settles the
+      // case where the connection closed without one.
+      setImmediate(() => settle(null))
+    })
+  })
+}
+
+// ── 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 }))
+
+// sootsim's own dev server range at PORT_OFFSET=0. an isolated stack shifts its
+// shell by the same offset as every other port it owns, so the guard has to
+// shift with it: at PORT_OFFSET=90 the shell listens on :5263 and a range fixed
+// at 5170-5200 does not cover it, which lets a scan discover ITSELF and offer
+// the shell as though it were an app's dev server. a guard that is only correct
+// at offset 0 is wrong for everyone running an isolated stack, which is exactly
+// who runs concurrent scans.
+const SELF_PORT_RANGE_START = 5170
+const SELF_PORT_RANGE_END = 5200
+
+function isOwnShellPort(port: number): boolean {
+  const offset = Number(process.env.PORT_OFFSET) || 0
+  // the unshifted range still counts: another checkout's default-offset shell is
+  // no more an app dev server than our own is.
+  if (port >= SELF_PORT_RANGE_START && port <= SELF_PORT_RANGE_END) return true
+  return (
+    offset > 0 &&
+    port >= SELF_PORT_RANGE_START + offset &&
+    port <= SELF_PORT_RANGE_END + offset
+  )
+}
+
+function acceptPort(port: number, excluded: Set<number>): boolean {
+  if (port <= 0 || port >= 20000) return false
+  if (excluded.has(port)) return false
+  if (isOwnShellPort(port)) return false
+  return true
+}
+
+/** ran the listing tool and these are the listeners, versus could not run it at
+ *  all. an empty `processes` here means the tool looked and there was genuinely
+ *  nothing; `could-not-look` means we have no information. substituting the
+ *  hardcoded FALLBACK_PORTS for the second case is what made `/__server-scan`
+ *  answer `[]` — "there are no dev servers" — to a user running three of them. */
+export type ListeningProcessScan =
+  | { state: 'looked'; processes: ListeningProcess[] }
+  | { state: 'could-not-look' }
+
+/** thrown by `scanDevServers` when listener enumeration itself failed. callers
+ *  must treat it as "no information" — keep whatever list they already had, or
+ *  answer their own caller with a failure — never as an empty result. */
+export class DevServerScanUnavailableError extends Error {
+  constructor() {
+    super('could not enumerate listening processes (lsof/ss unavailable or timed out)')
+    this.name = 'DevServerScanUnavailableError'
+  }
+}
+
+// lsof walks every open fd on the machine, so on a busy host it is genuinely
+// slow — measured between 1.2s and 5.0s here with 58 matching listeners. the
+// budget has to fit the real worst case, because the alternative is not a
+// faster answer, it is a WRONG one.
+const LISTING_TIMEOUT_MS = 10_000
+
+/** true when a failed exec was killed by our own timeout rather than by the
+ *  command being absent or erroring — the difference between "could not look"
+ *  and "this tool is not available here". */
+function wasKilledByTimeout(err: unknown): boolean {
+  return !!(err && typeof err === 'object' && (err as { killed?: boolean }).killed)
+}
+
+export async function discoverListeningProcesses(
+  excludePorts: number[] = [],
+): Promise<ListeningProcess[]> {
+  const scan = await scanListeningProcesses(excludePorts)
+  return scan.state === 'looked' ? scan.processes : []
+}
+
+export async function scanListeningProcesses(
+  excludePorts: number[] = [],
+): Promise<ListeningProcessScan> {
+  const excluded = new Set(excludePorts)
+  let timedOut = false
+
+  // 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 execGuarded(
+      `lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null | grep -E '^(node|bun)'`,
+      LISTING_TIMEOUT_MS,
+    )
+    const seen = new Map<number, number>()
+    for (const line of stdout.trim() ? 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)
+    }
+    // lsof ran. an empty result is a real answer: nothing is listening.
+    return {
+      state: 'looked',
+      processes: [...seen.entries()].map(([port, pid]) => ({ port, pid })),
+    }
+  } catch (err) {
+    if (wasKilledByTimeout(err)) timedOut = true
+  }
+
+  // ss layout: State Recv-Q Send-Q Local-Address:Port Peer-Addr:Port users:(("node",pid=1234,fd=5))
+  try {
+    const { stdout } = await execGuarded(
+      `ss -tlnp 2>/dev/null | grep -E '"(node|bun)"'`,
+      LISTING_TIMEOUT_MS,
+    )
+    const seen = new Map<number, number>()
+    for (const line of stdout.trim() ? 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)
+    }
+    return {
+      state: 'looked',
+      processes: [...seen.entries()].map(([port, pid]) => ({ port, pid })),
+    }
+  } catch (err) {
+    if (wasKilledByTimeout(err)) timedOut = true
+  }
+
+  // a tool that timed out told us nothing, so say so rather than substituting
+  // the guess list below and reporting its emptiness as fact.
+  if (timedOut) return { state: 'could-not-look' }
+
+  // neither tool exists here, so probe the conventional bundler ports directly.
+  // that is a real (if narrow) look, not a substitute for one.
+  return {
+    state: 'looked',
+    processes: 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 execGuarded('netstat -anv -p tcp 2>/dev/null', 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 execGuarded(`ss -tlnp 2>/dev/null`, 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 execGuarded(
+      `lsof -b -w -p ${pid} -a -d cwd -Fn 2>/dev/null`,
+      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(
+  hostname: string,
+  port: number,
+  framework: DiscoveredServer['framework'],
+  owner: Pick<DiscoveredServer, 'cwd' | 'pid'>,
+): DiscoveredServer {
+  return {
+    port,
+    framework,
+    bundleUrl: withRuntimeConfig(
+      port,
+      `${buildLoopbackProbeBaseUrl('http:', hostname, port)}/index.bundle?platform=ios&dev=true&hot=true&minify=false`,
+      owner.cwd,
+    ),
+    hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', hostname, port)}/hot`,
+    lastSeen: Date.now(),
+    ...owner,
+  }
+}
+
+function withRuntimeConfig(port: number, bundleUrl: string, projectCwd?: string): string {
+  let physicalProjectCwd: string | undefined
+  if (projectCwd) {
+    try {
+      physicalProjectCwd = realpathSync(resolve(projectCwd))
+    } catch {}
+  }
+  const knownApps = physicalProjectCwd
+    ? optionalDemoAppsSync().filter((app) => {
+        try {
+          return realpathSync(resolve(app.dir)) === physicalProjectCwd
+        } catch {
+          return false
+        }
+      })
+    : []
+  const exactKnownApps = knownApps.filter((app) => app.preferredPort === port)
+  const knownApp =
+    exactKnownApps.length === 1
+      ? exactKnownApps[0]
+      : exactKnownApps.length === 0 && knownApps.length === 1
+        ? knownApps[0]
+        : undefined
+  const configured = knownApp?.runtimeConfig
+    ? applyRNXConfigToUrl(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
+  }
+}
+
+// a manifest icon path ("./assets/app-icons/x.png") is relative to the project
+// root. metro's asset route prefixes the whole relative path with /assets/; a
+// statically-served project answers at the literal path. the manifest says
+// nothing about which, so the two candidates are probed once per port and the
+// winner cached. keyed by port and cleared with the rest of that port's state
+// when the process disappears.
+const localIconPathCache = new Map<number, string>()
+const localIconProbeInFlight = new Set<number>()
+
+function metroAssetPath(rawIcon: string): string {
+  return `/assets/${rawIcon.replace(/^\.?\//, '')}`
+}
+
+function staticAssetPath(rawIcon: string): string {
+  return `/${rawIcon.replace(/^\.?\//, '')}`
+}
+
+// probe both shapes and cache whichever the server actually serves. resolves
+// nothing when neither answers — the tile falls back to the app's brand colour.
+async function resolveLocalIconPath(
+  hostname: string,
+  port: number,
+  rawIcon: string,
+): Promise<void> {
+  const candidates = [metroAssetPath(rawIcon), staticAssetPath(rawIcon)]
+  for (const candidate of candidates) {
+    const res = await httpGet(hostname, port, candidate, 'HEAD', ENRICH_TIMEOUT_MS)
+    if (res?.statusCode === 200) {
+      localIconPathCache.set(port, candidate)
+      // the identified result caches as a strong entry and won't re-probe on
+      // its own; drop it so the next scan republishes with the working url.
+      portCache.delete(port)
+      return
+    }
+  }
+}
+
+// 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 (typeof client.primaryColor === 'string') result.primaryColor = client.primaryColor
+    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). keep its path and query
+    // so metro shares the iOS bundle cache. when both hosts are loopback, keep
+    // the host that answered discovery so address-family drift stays reachable.
+    const rawLaunchUrl = manifest?.launchAsset?.url
+    const launchUrl =
+      typeof rawLaunchUrl === 'string'
+        ? alignLoopbackBundleUrlWithProbe(
+            rawLaunchUrl,
+            buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port),
+          )
+        : rawLaunchUrl
+    if (launchUrl && !result.patched && !isDirectOneBundleUrl(result.bundleUrl)) {
+      result.bundleUrl = withRuntimeConfig(result.port, launchUrl, result.cwd)
+    }
+    const localIcon = client.icon || client.ios?.icon
+    const remoteIcon = client.iconUrl || client.ios?.iconUrl
+    const rawIcon = localIcon || remoteIcon
+    if (rawIcon) {
+      result.iconPath = rawIcon
+      let resolvedIconUrl: string | undefined
+      if (rawIcon.startsWith('http://') || rawIcon.startsWith('https://')) {
+        let isLoopback = false
+        try {
+          const parsed = new URL(rawIcon)
+          isLoopback = isLoopbackHost(parsed.hostname)
+        } catch {}
+        if (buildIconProxyUrl) {
+          if (isLoopback) {
+            resolvedIconUrl = buildIconProxyUrl(rawIcon)
+          }
+        } else {
+          resolvedIconUrl = rawIcon
+        }
+      } else {
+        // a manifest icon path is relative to the project root, and the two
+        // server shapes we meet serve it at different URLs: metro's asset route
+        // is `/assets/` + that whole relative path (so `assets/x.png` lands at
+        // `/assets/assets/x.png`), while a statically-served project answers at
+        // the literal path. neither shape can be derived from the manifest, so
+        // resolveLocalIconPath probes the server once and caches the answer;
+        // until it lands we publish the metro form, which is the common case.
+        const base = buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port)
+        const assetPath = localIconPathCache.get(result.port) ?? metroAssetPath(rawIcon)
+        const localUrl = `${base}${assetPath}`
+        resolvedIconUrl = buildIconProxyUrl ? buildIconProxyUrl(localUrl) : localUrl
+      }
+      if (resolvedIconUrl) {
+        result.iconUrl = resolvedIconUrl
+      }
+    }
+  } catch {}
+  return result
+}
+
+export function __applyManifestForTests(
+  result: DiscoveredServer,
+  manifestBody: string,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+): DiscoveredServer {
+  return applyManifest(
+    result,
+    {
+      statusCode: 200,
+      body: manifestBody,
+      hostname: new URL(result.bundleUrl).hostname,
+    },
+    buildIconProxyUrl,
+  )
+}
+
+// ── 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>()
+
+// a result that carries a relative icon path has not had its serving shape
+// confirmed yet. probe once per port; applyManifest reads the cached answer.
+function ensureLocalIconPathResolved(result: DiscoveredServer): void {
+  const rawIcon = result.iconPath
+  if (!rawIcon) return
+  if (rawIcon.startsWith('http://') || rawIcon.startsWith('https://')) return
+  if (localIconPathCache.has(result.port)) return
+  if (localIconProbeInFlight.has(result.port)) return
+  localIconProbeInFlight.add(result.port)
+  const hostname = normalizeHostname(new URL(result.bundleUrl).hostname)
+  void resolveLocalIconPath(hostname, result.port, rawIcon).finally(() =>
+    localIconProbeInFlight.delete(result.port),
+  )
+}
+
+// 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 {
+  ensureLocalIconPathResolved(result)
+  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)
+    void fetchManifestEnrichment(result, buildIconProxyUrl).finally(() =>
+      enrichmentInFlight.delete(result.port),
+    )
+  }
+  return result
+}
+
+async function fetchManifestEnrichment(
+  result: DiscoveredServer,
+  buildIconProxyUrl?: (externalUrl: string) => string,
+): Promise<void> {
+  const hostname = normalizeHostname(new URL(result.bundleUrl).hostname)
+  const manifestRes = await httpGet(
+    hostname,
+    result.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: result.port,
+      framework: 'one',
+      bundleUrl: `${buildLoopbackProbeBaseUrl('http:', hostname, result.port)}/index.bundle`,
+      lastSeen: 0,
+    },
+    manifestRes,
+    buildIconProxyUrl,
+  )
+  if (!parsed.projectName && !parsed.iconUrl) return
+  enrichmentCache.set(result.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(result.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 `rnx 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()
+  const probeHostname = await tcpPing(port)
+  if (!probeHostname) 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(probeHostname, port, '/__soot/'),
+    httpGet(probeHostname, port, '/status'),
+    knownOne.has(port)
+      ? Promise.resolve(null)
+      : httpGet(probeHostname, port, '/', 'GET', MANIFEST_TIMEOUT_MS, {
+          'expo-platform': 'ios',
+        }),
+    knownNonExpo.has(port)
+      ? Promise.resolve(null)
+      : httpGet(probeHostname, 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) ||
+    {}
+  // `manifestRes === null` means the probe got NO answer — it timed out or the
+  // connection failed. that is not the same fact as a server that answered and
+  // turned out to have no manifest, and only the second one licenses the
+  // generic `/index.bundle` entry point below.
+  const manifestState: ManifestState = !manifestRes
+    ? 'no-answer'
+    : manifestParsed && (manifestLaunchUrl || typeof manifestClient.name === 'string')
+      ? 'resolved'
+      : 'no-manifest'
+  if (manifestState === 'resolved') {
+    knownNonPatched.add(port)
+    const launchUrl =
+      manifestLaunchUrl ||
+      `${buildLoopbackProbeBaseUrl('http:', probeHostname, 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: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, 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)
+    // `makeResult` builds the generic `<base>/index.bundle` entry point. that is
+    // the RIGHT answer for a vanilla Metro or plain Expo packager, which is a
+    // server that ANSWERED `/` and had no manifest to give. it is a guess when
+    // the manifest simply never answered: this server may well be a One app
+    // whose manifest names `node_modules/one/metro-entry.bundle`, and opening
+    // the generic path instead makes metro build the whole app a second time
+    // under a module graph the app never named. flag it so `open` refuses to
+    // act on it, while the dock still lists the server it can plainly see.
+    const result = makeResult(
+      probeHostname,
+      port,
+      expoRes && expoRes.statusCode === 200 ? 'expo' : 'metro',
+      owner,
+    )
+    if (manifestState === 'no-answer') result.bundleUrlProvisional = true
+    return enrichWithManifest(
+      applyManifest(result, 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,
+            `${buildLoopbackProbeBaseUrl('http:', probeHostname, port)}/__soot/bundle.js`,
+            owner.cwd,
+          ),
+          hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, 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(probeHostname, 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,
+            `${buildLoopbackProbeBaseUrl('http:', probeHostname, port)}${onePath}&minify=false`,
+            owner.cwd,
+          ),
+          hmrUrl: `${buildLoopbackProbeBaseUrl('ws:', probeHostname, 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 / `rnx 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 scan = await scanListeningProcesses(opts.excludePorts)
+  // we could not enumerate listeners, so we know nothing about what is running.
+  // returning [] here would evict every cache entry and report "no dev servers"
+  // to a user who has several — the caller must be able to tell the two apart.
+  if (scan.state === 'could-not-look') throw new DevServerScanUnavailableError()
+  const processes = scan.processes
+  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)
+  }
+  for (const p of [...localIconPathCache.keys()]) {
+    if (!currentPorts.has(p)) localIconPathCache.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)
+      localIconPathCache.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))
+}