sootsim 0.1.83 → 0.1.85

package/scripts/dev-server-scanner.ts

@@ -0,0 +1,674 @@
+// 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 http from 'http'
+import net from 'net'
+import { promisify } from 'util'
+
+const execP = promisify(exec)
+import { applySootSimConfigToUrl } from '../src/config.ts'
+import { normalizeNativeDevBundleUrl } from '../src/native-dev-bundle-url.ts'
+import { APPS } from './demo-app-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
+  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)
+}
+
+// per-pid cwd cache. lsof is fairly cheap but we call it per discovered
+// server per scan (every 5s in the tray), so caching the result until the
+// pid goes away avoids redundant forks.
+const cwdByPid = new Map<number, string>()
+
+/** resolve the current working directory of a pid using `lsof -d cwd`.
+ *  macOS + linux both accept this. returns null for pid 0 (unknown owner)
+ *  and whenever lsof is unavailable or the fd isn't present.
+ *  async — sync exec blocked CrBrowserMain at ~600ms on macOS. */
+export async function resolveProcessCwd(pid: number): Promise<string | null> {
+  if (pid <= 0) return null
+  const cached = cwdByPid.get(pid)
+  if (cached) return cached
+  try {
+    // -Fn → machine-readable, one field per line. lines look like:
+    //   p<pid>
+    //   fcwd
+    //   n<absolute path>
+    const { stdout } = await execP(`lsof -p ${pid} -a -d cwd -Fn 2>/dev/null`, {
+      encoding: 'utf8',
+      timeout: 1500,
+    })
+    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'],
+): DiscoveredServer {
+  return {
+    port,
+    framework,
+    bundleUrl: withRuntimeConfig(
+      port,
+      `http://localhost:${port}/index.bundle?platform=ios&dev=true&hot=true&minify=false`,
+    ),
+    hmrUrl: `ws://localhost:${port}/hot`,
+    lastSeen: Date.now(),
+  }
+}
+
+function withRuntimeConfig(port: number, bundleUrl: string): string {
+  const knownApp = APPS.find((app) => app.preferredPort === port)
+  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)
+    }
+    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 })
+}
+
+// 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,
+): Promise<DiscoveredServer | null> {
+  if (!(await tcpPing(port))) return null
+
+  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),
+        hmrUrl: `ws://localhost:${port}/hot`,
+        lastSeen: Date.now(),
+      },
+      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 applyManifest(
+      makeResult(port, expoRes && expoRes.statusCode === 200 ? 'expo' : 'metro'),
+      manifestRes,
+      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 applyManifest(
+      {
+        port,
+        framework: 'one',
+        bundleUrl: withRuntimeConfig(port, `http://localhost:${port}/__soot/bundle.js`),
+        hmrUrl: `ws://localhost:${port}/hot`,
+        lastSeen: Date.now(),
+        patched: true,
+      },
+      manifestRes,
+      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.
+  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 applyManifest(
+      {
+        port,
+        framework: 'one',
+        bundleUrl: withRuntimeConfig(
+          port,
+          `http://localhost:${port}${onePath}&minify=false`,
+        ),
+        hmrUrl: `ws://localhost:${port}/hot`,
+        lastSeen: Date.now(),
+      },
+      manifestRes,
+      buildIconProxyUrl,
+    )
+  }
+
+  knownNonPatched.add(port)
+  return null
+}
+
+// ── top-level convenience ───────────────────────────────────────────────────
+
+export interface ScanOptions {
+  excludePorts?: number[]
+  buildIconProxyUrl?: (externalUrl: string) => string
+}
+
+function isSootSelfServer(server: DiscoveredServer): boolean {
+  const projectName = server.projectName?.trim().toLowerCase()
+  if (projectName === 'soot' || projectName === 'sootsim') return true
+
+  const bundleId = server.bundleId?.trim().toLowerCase()
+  if (bundleId?.startsWith('dev.soot')) return true
+
+  return false
+}
+
+// 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. soot's own
+// api server, zero, postgres, 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 soot'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.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()
+}
+
+export async function scanDevServers(
+  opts: ScanOptions = {},
+): Promise<DiscoveredServer[]> {
+  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)
+  }
+
+  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)
+    }
+    toProbe.push({ port, pid })
+  }
+
+  if (toProbe.length > 0) {
+    const probed = await Promise.all(
+      toProbe.map((p) => probePort(p.port, opts.buildIconProxyUrl)),
+    )
+    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) result.cwd = 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) => !isSootSelfServer(r))
+}