sootsim 0.1.82 → 0.1.84

package/src/host/bridge-host.ts

@@ -0,0 +1,2293 @@
+import { spawn } from 'child_process'
+import fs from 'fs'
+import { createServer, type IncomingMessage, type ServerResponse } from 'http'
+import path from 'path'
+import { WebSocket, WebSocketServer } from 'ws'
+import {
+  scanDevServers,
+  type DiscoveredServer,
+} from '../../scripts/dev-server-scanner.ts'
+import {
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+  SOOTSIM_BRIDGE_SIM_CLOSE_CODE,
+  SOOTSIM_BRIDGE_SIM_CLOSE_REASON,
+} from '../bridge-constants.ts'
+import { getCliVersion } from '../cli-version.ts'
+import {
+  activeRuntimeDir as getActiveRuntimeDir,
+  claimDaemonLockfile,
+  ensureSootsimHome,
+  listInstalledRuntimes,
+  readActiveRuntime,
+  readSharedConfig,
+  removeDaemonLockfile,
+  writeActiveRuntime,
+  writeDaemonLockfile,
+  writeSharedConfig,
+  type DaemonLockfile,
+  type SharedConfig,
+} from '../home-paths.ts'
+import { updateRuntimeToLatest } from '../runtime-delivery.ts'
+import { AgentHost, type AgentHostOptions } from './agent-host.ts'
+import {
+  handleAppApiRequest,
+  handleFetchProxyRequest,
+  isAppApiRequestUrl,
+  isFetchProxyRequestUrl,
+} from './fetch-proxy-handler'
+import { openUrl as openUrlInBrowser, type OpenUrlOptions } from './open-url.ts'
+
+export interface BridgeSimInfo {
+  id: string
+  origin?: string
+  url?: string
+  title?: string
+  userAgent?: string
+  connectedAt: number
+  lastSeenAt: number
+  lastActiveAt?: number
+  isPrimary: boolean
+  readyState: 'open' | 'closing' | 'closed'
+  attachedCliCount?: number
+  lockedBy?: string
+  lockedByKind?: 'cli' | 'user-active'
+  lockExpiresAt?: number
+  userFocused?: boolean
+  userVisible?: boolean
+  visibilityState?: string
+  documentFocused?: boolean
+  /** registration "kind" — lets a single daemon host multiple surface
+   *  types. omitted / unknown defaults to 'sootsim'. the sootbean web
+   *  IDE registers with kind='sootbean'; CLI consumers filter by this
+   *  rather than running a parallel bridge. */
+  kind?: string
+  /** opaque metadata supplied at register time (e.g. projectId, route,
+   *  attached iOS sim id for a sootbean tab). free-form by design — the
+   *  daemon does not interpret it, only stores + reports it back. */
+  meta?: Record<string, unknown>
+}
+
+export interface BridgeLockInfo {
+  by: string
+  expiresInMs: number
+}
+
+export interface BridgeSimCommand {
+  id: number
+  type: 'evaluate' | 'screenshot' | 'tap' | 'keyboard' | 'tree' | 'focus' | 'close'
+  code?: string
+  x?: number
+  y?: number
+  action?: string
+  text?: string
+  depth?: number
+  simId?: string
+}
+
+interface BridgeSimRegistrationMessage {
+  type: 'bridge:register'
+  simId?: string
+  url?: string
+  title?: string
+  userAgent?: string
+  /** see BridgeSimInfo.kind — defaults to 'sootsim' when omitted. */
+  kind?: string
+  /** see BridgeSimInfo.meta — free-form metadata for filtering/routing. */
+  meta?: Record<string, unknown>
+}
+
+interface BridgeSimUserFocusStateMessage {
+  type: 'bridge:user-focus-state'
+  focused?: boolean
+  visible?: boolean
+  visibilityState?: string
+  documentFocused?: boolean
+}
+
+interface BridgeSimClientStateMessage {
+  type: 'bridge:client-state'
+  attachedCliCount: number
+  activeAgentCommandCount: number
+  recentActions: BridgeRecentAction[]
+  lockedBy?: string
+  lockedByKind?: 'cli' | 'user-active'
+  lockExpiresAt?: number
+  userFocused?: boolean
+  userVisible?: boolean
+  visibilityState?: string
+  documentFocused?: boolean
+}
+
+interface BridgeRecentAction {
+  label: string
+  at: number
+}
+
+interface BridgeSimConnection {
+  id: string
+  ws: WebSocket
+  origin?: string
+  url?: string
+  title?: string
+  userAgent?: string
+  connectedAt: number
+  lastSeenAt: number
+  lastActiveAt: number
+  recentActions: BridgeRecentAction[]
+  cliLease?: BridgeCliLease
+  userFocused?: boolean
+  userVisible?: boolean
+  visibilityState?: string
+  documentFocused?: boolean
+  /** see BridgeSimInfo.kind. */
+  kind?: string
+  /** see BridgeSimInfo.meta. */
+  meta?: Record<string, unknown>
+}
+
+interface BridgeCliLease {
+  kind: 'cli' | 'user-active'
+  cliIdentityKey: string
+  cliLabel?: string
+  expiresAt: number
+}
+
+// interactive commands change app state and must respect the lease.
+// observational/lifecycle commands (evaluate/tree/screenshot/focus/call/close)
+// pass through without taking or checking a lease so cleanup never gets stuck
+// behind a stale cli owner.
+// `call` used to acquire a lease too, but most call paths are queries
+// (`__sootsimTest.findByTestId`, state reads, etc.). the CLI opts write
+// calls into lease acquisition via msg.acquireLock=true.
+const WRITE_COMMAND_TYPES = new Set(['tap', 'keyboard'])
+
+// how long a `close` waits for the sim page to tear itself down before the
+// host disconnects the sim socket. the close code is part of the protocol:
+// browser clients treat it as terminal and skip their normal reconnect loop.
+const FORCE_CLOSE_GRACE_MS = 2000
+const FORCE_CLOSE_TERMINATE_MS = 1000
+
+// note: `unrefTimer` is declared once, below (with the `UnrefableTimer`
+// type). a duplicate copy used to live here from a concurrent edit and
+// broke the standalone CLI esbuild bundle ("symbol already declared").
+
+function shouldAcquireLease(msg: any): boolean {
+  if (!msg || typeof msg.type !== 'string') return false
+  if (msg.acquireLock === true) return true
+  if (msg.readOnly === true) return false
+  return WRITE_COMMAND_TYPES.has(msg.type)
+}
+
+interface BridgeRestorableSimState {
+  recentActions: BridgeRecentAction[]
+  lastActiveAt: number
+  cliLease?: BridgeCliLease
+  expiresAt: number
+}
+
+interface BridgePendingCommand {
+  simId: string
+  resolve: (value: any) => void
+  reject: (error: Error) => void
+}
+
+interface BridgeForwardedCommand {
+  simId: string
+  ws: WebSocket
+  originalId: number | string
+}
+
+export interface BridgeHostOptions {
+  port?: number
+  openUrl?: (url: string, options?: OpenUrlOptions) => Promise<void> | void
+  /** soot-specific excludes for the agent host's dev-server scan. passed
+   *  through to AgentHost; see packages/sootsim-engine/src/dev-scan-excludes.ts
+   *  for the canonical list. when omitted, AgentHost reads env vars directly. */
+  agentScanExcludes?: AgentHostOptions['getExcludePorts']
+  /** try preferred port, then port+1, port+2, …, up to this many attempts
+   *  before giving up. defaults to 10. set 1 to disable fallback. */
+  portFallbackCount?: number
+  /** when true, write ~/.sootsim/daemon.json on successful bind + update
+   *  it on a heartbeat interval + remove it on close. only the standalone
+   *  `sootsim server` process should set this — tests, vite plugin, and
+   *  anything embedded should leave it off to avoid clobbering a real
+   *  daemon's lockfile. defaults to false. */
+  writeLockfile?: boolean
+  /** the sootbean origin this daemon's runtimes should talk to for auth,
+   *  billing, and preview uploads — inlined into served runtime html as
+   *  `window.__sootsimSootbeanOrigin`. without it the engine's origin.ts
+   *  resolves the daemon's own loopback host (localhost:<runtimePort>) to
+   *  the dev `localhost:3000` stack, so a *prod* CLI user's preview
+   *  recording would upload to a localhost stack that doesn't exist. the
+   *  `sootsim server` command resolves this with the same probe the
+   *  upload itself uses (`resolveDefaultUploadOrigin`). */
+  sootbeanOrigin?: string
+  /** override the abandoned-sim GC TTL (ms). defaults to
+   *  SIM_IDLE_REAP_TTL_MS (30 min). exists so the reaper integration test
+   *  can drive the real timer path deterministically instead of mocking
+   *  time. production callers should never set this. */
+  simIdleReapTtlMs?: number
+}
+
+const DAEMON_HEARTBEAT_INTERVAL_MS = 5_000
+const DEFAULT_RUNTIME_UPDATE_INTERVAL_MS = 60 * 60 * 1000
+const RUNTIME_UPDATE_INTERVAL_ENV = 'SOOTSIM_RUNTIME_UPDATE_INTERVAL_MS'
+
+const HTTP_MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript',
+  '.cjs': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.wasm': 'application/wasm',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.map': 'application/json',
+  '.txt': 'text/plain; charset=utf-8',
+}
+
+/** inject host-provided globals into the served runtime html:
+ *   - `window.__sootsimSharedConfig` — parsed `~/.sootsim/config.json`,
+ *     read during engine settingsStore module init (see
+ *     settings/persistence.ts). mirrors the inject-into-html plugin in the
+ *     shell vite dev server so dev and prod surfaces both produce it.
+ *   - `window.__sootsimCliVersion` — the CLI version serving this runtime,
+ *     so the shell can surface CLI vs runtime version (MacMenuBar footer,
+ *     ReportBody) and users can tell what they're actually running.
+ *   - `window.__sootsimBridgePort` — the ws bridge port this daemon is
+ *     actually listening on. the runtime http server and the ws bridge are
+ *     the same server on the same port, but a daemon whose preferred 7668
+ *     was taken falls back to 7669+. without this the runtime page would
+ *     hardcode the 7668 default in `resolveBridgePort` and register on a
+ *     *different* daemon (or none), so `sootsim open` times out waiting for
+ *     a sim that connected to the wrong bridge.
+ *   - `window.__sootsimSootbeanOrigin` — the sootbean origin for auth /
+ *     billing / preview uploads. the daemon serves runtimes from its own
+ *     loopback host, and engine `origin.ts` otherwise resolves any
+ *     loopback host to the dev `localhost:3000` stack — so without this a
+ *     prod CLI user's preview recording would upload to a localhost stack
+ *     that does not exist. */
+function injectSharedConfigIntoHtml(
+  data: Buffer,
+  bridgePort: number,
+  sootbeanOrigin: string | null,
+): string {
+  let payload: string
+  try {
+    const cfg: SharedConfig = readSharedConfig()
+    payload = JSON.stringify(cfg)
+  } catch {
+    payload = '{}'
+  }
+  const bridgePortTag = bridgePort > 0 ? `window.__sootsimBridgePort=${bridgePort};` : ''
+  const sootbeanOriginTag = sootbeanOrigin
+    ? `window.__sootsimSootbeanOrigin=${JSON.stringify(sootbeanOrigin)};`
+    : ''
+  const tag =
+    `<script>window.__sootsimSharedConfig=${payload};` +
+    bridgePortTag +
+    sootbeanOriginTag +
+    `window.__sootsimCliVersion=${JSON.stringify(getCliVersion())};</script>`
+  const html = data.toString('utf8')
+  if (html.includes('</head>')) return html.replace('</head>', tag + '</head>')
+  if (html.includes('</body>')) return html.replace('</body>', tag + '</body>')
+  // no recognized injection point — prepend so the global is defined
+  // before any inline scripts further down in the document.
+  return tag + html
+}
+
+type UnrefableTimer = { unref: () => void }
+
+function unrefTimer(timer: ReturnType<typeof setTimeout>) {
+  if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
+    ;(timer as UnrefableTimer).unref()
+  }
+}
+
+export class SootSimBridgeHost {
+  private port: number
+  private openUrlHandler?: (url: string, options?: OpenUrlOptions) => Promise<void> | void
+  private httpServer: ReturnType<typeof createServer> | null = null
+  private wss: WebSocketServer | null = null
+  private nextCommandId = 1
+  private nextSimNumber = 0xa1
+  private sims = new Map<string, BridgeSimConnection>()
+  private primarySimId: string | null = null
+  private pendingCommands = new Map<number, BridgePendingCommand>()
+  private cliBySentId = new Map<number, BridgeForwardedCommand>()
+  private cliSimBySocket = new Map<WebSocket, string>()
+  private cliLastCommandAt = new Map<WebSocket, number>()
+  private cliIdentityKeyBySocket = new Map<WebSocket, string>()
+  private cliLabelBySocket = new Map<WebSocket, string>()
+  private restorableSims = new Map<string, BridgeRestorableSimState>()
+  private nextCliFallbackId = 1
+  private cliIdleTimer: NodeJS.Timeout | null = null
+  private agentHost: AgentHost
+  private static CLI_IDLE_TIMEOUT_MS = 60_000
+  private static CLI_LEASE_TTL_MS = 600_000
+  private static USER_ACTIVE_LEASE_TTL_MS = 8_000
+  // explicit user actions (clicking Boot, focusing the sim to take it over)
+  // hold the sim longer than passive canvas interaction so reconnecting clis
+  // can't immediately reclaim while the user gets oriented.
+  private static USER_BOOT_LEASE_TTL_MS = 60_000
+  private static SIM_RECONNECT_TTL_MS = 30_000
+  // abandoned-tab GC. the ws heartbeat only reaps sims whose socket went
+  // dead — but a background tab from a prior `sootsim open` / QA / test run
+  // keeps its socket alive (the page still pongs) forever, so `sootsim list`
+  // accretes dozens of zombie sims that all time out on every command (QA
+  // F21-3, carried F19-2). reap a sim only when it is provably nobody's:
+  // not primary, not user-focused, no CLI attached, no active lease, and no
+  // CLI-driven activity for this long. closeSimSocketFromHost sends the
+  // terminal 4001 code, so the client closes the abandoned window instead
+  // of reconnecting the zombie straight back in.
+  private static SIM_IDLE_REAP_TTL_MS = 30 * 60_000
+
+  private preferredPort: number
+  private portFallbackCount: number
+  private simIdleReapTtlMs: number
+  private shouldWriteLockfile: boolean
+  private sootbeanOrigin: string | null = null
+  private effectivePort = 0
+  private startedAt = 0
+  private heartbeatTimer: NodeJS.Timeout | null = null
+  // ws-level heartbeat: sims that hang up uncleanly (page navigated, network
+  // dropped, sim crashed) leave their server-side WebSocket sitting "open"
+  // forever. ping every WS_HEARTBEAT_INTERVAL_MS; if the previous round's
+  // ping was never answered, terminate(). that fires 'close' which runs the
+  // sim-cleanup path and stops `sootsim list` from showing 8 zombie
+  // sims that all time out on every command.
+  private wsHeartbeatTimer: NodeJS.Timeout | null = null
+  private wsIsAlive = new WeakMap<WebSocket, boolean>()
+  private static WS_HEARTBEAT_INTERVAL_MS = 30_000
+  private runtimeUpdateTimer: NodeJS.Timeout | null = null
+  private runtimeUpdateInFlight: Promise<void> | null = null
+  private activeRuntimeVersion: string | null = null
+  private activeRuntimeDirPath: string | null = null
+  // /__server-scan cache. mirrors the shell vite dev-middleware so engine
+  // ConnectRN / DemoConnectApp see the same JSON shape whether they boot
+  // from vite dev or from this daemon. without this, the SPA fallback below
+  // would serve index.html for /__server-scan and tenant-worker .json()
+  // crashes with "Unexpected token '<', "<!doctype "... is not valid JSON".
+  private scanCache: DiscoveredServer[] | null = null
+  private scanCacheAt = 0
+  private inflightScan: Promise<DiscoveredServer[]> | null = null
+  private static SCAN_FRESH_MS = 2000
+
+  constructor(opts: BridgeHostOptions = {}) {
+    this.preferredPort = opts.port || DEFAULT_SOOTSIM_BRIDGE_PORT
+    this.port = this.preferredPort
+    // default off — callers that want the lockfile (sootsim server) opt in.
+    this.shouldWriteLockfile = opts.writeLockfile === true
+    // fallback freely on port collision regardless of who owns the lockfile.
+    // server.ts already refuses to start if a fresh daemon.json exists, so
+    // two daemons can't race the lockfile. without this, an unrelated process
+    // on 7668 (another worktree's vite dev fallback bridge, etc.) was enough
+    // to keep the daemon from binding at all — and launchd's KeepAlive then
+    // respawned it forever.
+    this.portFallbackCount = Math.max(1, opts.portFallbackCount ?? 10)
+    this.openUrlHandler = opts.openUrl
+    this.agentHost = new AgentHost({ getExcludePorts: opts.agentScanExcludes })
+    this.sootbeanOrigin = opts.sootbeanOrigin?.replace(/\/$/, '') || null
+    this.simIdleReapTtlMs =
+      opts.simIdleReapTtlMs ?? SootSimBridgeHost.SIM_IDLE_REAP_TTL_MS
+  }
+
+  /** expose the agent host so tests and embedders can inspect state or
+   *  inject behavior. not part of the public WS protocol. */
+  getAgentHost(): AgentHost {
+    return this.agentHost
+  }
+
+  /** run the abandoned-sim GC pass on demand. the reaper normally fires off
+   *  the 30s idle-sweep timer; this lets the F21-3 integration test drive
+   *  the real path without waiting for the timer. not part of the public
+   *  WS protocol. */
+  reapIdleSimsForTest(now = Date.now()): void {
+    this.reapIdleSims(now)
+  }
+
+  /** synchronous wrapper around startAsync for callers that don't care
+   *  about port fallback outcomes. returns immediately; actual binding
+   *  happens on the event loop. callers that need to know the bound port
+   *  should await startAsync() instead. */
+  start(options?: { silent?: boolean }): void {
+    void this.startAsync(options)
+  }
+
+  async startAsync(options?: { silent?: boolean }): Promise<number> {
+    if (this.httpServer || this.wss) return this.effectivePort
+
+    // seed active runtime state from disk so the http routes + lockfile
+    // reflect reality at boot. we reread this on runtime:use messages.
+    this.refreshActiveRuntime()
+
+    for (let attempt = 0; attempt < this.portFallbackCount; attempt++) {
+      const candidate = this.preferredPort + attempt
+      try {
+        await this.bindOnce(candidate, options?.silent === true)
+        this.effectivePort = candidate
+        this.port = candidate
+        this.startedAt = Date.now()
+        if (attempt > 0 && !options?.silent) {
+          process.stderr.write(
+            `ws bridge bound to port ${candidate} (preferred ${this.preferredPort} was taken)\n`,
+          )
+        }
+        this.afterBind()
+        return candidate
+      } catch (err: unknown) {
+        const e = err as NodeJS.ErrnoException
+        if (e?.code !== 'EADDRINUSE') {
+          throw err
+        }
+        if (!options?.silent) {
+          process.stderr.write(
+            `ws bridge port ${candidate} already in use, trying ${candidate + 1}\n`,
+          )
+        }
+        // bindOnce already cleaned up httpServer/wss on failure
+      }
+    }
+    throw new Error(
+      `could not bind ws bridge after ${this.portFallbackCount} attempts starting at ${this.preferredPort}`,
+    )
+  }
+
+  private bindOnce(port: number, _silent: boolean): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const server = createServer((req, res) => this.handleHttpRequest(req, res))
+      let settled = false
+
+      const onError = (err: NodeJS.ErrnoException) => {
+        if (settled) return
+        settled = true
+        try {
+          server.close()
+        } catch {}
+        this.httpServer = null
+        this.wss = null
+        reject(err)
+      }
+      server.once('error', onError)
+
+      // loopback-only bind. we listen on 127.0.0.1 explicitly because the
+      // daemon serves the active runtime's dist as plain static files —
+      // never expose that to LAN peers. tests + the electron renderer use
+      // 127.0.0.1 explicitly to avoid the localhost-vs-::1 DNS coinflip.
+      server.listen(port, '127.0.0.1', () => {
+        if (settled) return
+        settled = true
+        server.removeListener('error', onError)
+        server.on('error', (err) => {
+          process.stderr.write(`ws bridge http error: ${String(err)}\n`)
+        })
+        this.httpServer = server
+        this.wss = new WebSocketServer({ server })
+        this.wireWebSocketServer()
+        resolve()
+      })
+    })
+  }
+
+  /** attach the WS connection handler to the current wss. called from
+   *  bindOnce() after WebSocketServer is freshly created. */
+  private wireWebSocketServer() {
+    if (!this.wss) return
+    this.wss.on('connection', (ws, req) => {
+      const origin = req.headers.origin
+      const role: 'sim' | 'cli' = origin ? 'sim' : 'cli'
+      let sim: BridgeSimConnection | null = null
+
+      // ws emits 'error' for late peer-side socket faults (write EIO after
+      // sleep/wake, abrupt sim close, etc). without a listener, node's
+      // EventEmitter rethrows as uncaughtException and crashes the host.
+      // 'close' fires right after and runs the cleanup below.
+      ws.on('error', () => {})
+
+      // ws-level heartbeat. pong responses come for free from the ws
+      // protocol — we just need to track them so the heartbeat sweep
+      // (started in afterBind) can terminate connections that stop
+      // answering. fresh connections start alive.
+      this.wsIsAlive.set(ws, true)
+      ws.on('pong', () => {
+        this.wsIsAlive.set(ws, true)
+      })
+
+      // register the socket with the agent host so session-status pushes
+      // reach it even before it subscribes to any specific session, and so
+      // subscriptions get cleaned up automatically on close.
+      this.agentHost.registerSocket(ws)
+
+      if (role === 'sim') {
+        sim = {
+          id: this.allocateSimId(),
+          ws,
+          origin,
+          connectedAt: Date.now(),
+          lastSeenAt: Date.now(),
+          lastActiveAt: 0,
+          recentActions: [],
+        }
+        this.sims.set(sim.id, sim)
+        if (this.shouldPromoteSim(sim)) {
+          this.primarySimId = sim.id
+        }
+        this.broadcastSimAssignments()
+        this.broadcastSimClientStates()
+      } else {
+        const fallbackKey = `ws-${this.nextCliFallbackId++}`
+        this.cliIdentityKeyBySocket.set(ws, fallbackKey)
+      }
+
+      ws.on('message', (data) => {
+        let msg: any
+        try {
+          msg = JSON.parse(data.toString())
+        } catch {
+          return
+        }
+        if (!msg || typeof msg !== 'object') return
+
+        // agent:* messages are routed uniformly regardless of socket role.
+        // CLI (`sootsim agent …`), electron main (daemon client), and
+        // sim shells all use the same envelope, and agent event
+        // subscriptions work from any of them — this is the whole point of
+        // moving session ownership into the daemon.
+        if (typeof msg.type === 'string' && msg.type.startsWith('agent:')) {
+          void this.agentHost.handleMessage(ws, msg)
+          return
+        }
+
+        // runtime:* messages manage installed engine runtimes. list / use
+        // are handled in-daemon; install runs entirely inside the CLI so
+        // we don't need a daemon-side handler for it.
+        if (msg.type === 'runtime:list') {
+          const versions = listInstalledRuntimes()
+          const active = this.getActiveRuntime()
+          const reply = {
+            type: 'runtime:list:ok',
+            id: msg.id,
+            installed: versions,
+            active: active.version,
+            activeRuntimeDir: active.runtimeDir,
+          }
+          try {
+            ws.send(JSON.stringify(reply))
+          } catch {}
+          return
+        }
+        if (msg.type === 'runtime:use') {
+          const version = typeof msg.version === 'string' ? msg.version : ''
+          const installed = listInstalledRuntimes()
+          if (!installed.includes(version)) {
+            try {
+              ws.send(
+                JSON.stringify({
+                  type: 'runtime:use:error',
+                  id: msg.id,
+                  error: `runtime ${version || '(missing)'} is not installed`,
+                }),
+              )
+            } catch {}
+            return
+          }
+          const result = this.setActiveRuntime(version)
+          try {
+            ws.send(
+              JSON.stringify({
+                type: 'runtime:use:ok',
+                id: msg.id,
+                version: result.version,
+                runtimeDir: result.runtimeDir,
+              }),
+            )
+          } catch {}
+          return
+        }
+        if (msg.type === 'runtime:get') {
+          const active = this.getActiveRuntime()
+          try {
+            ws.send(
+              JSON.stringify({
+                type: 'runtime:get:ok',
+                id: msg.id,
+                active: active.version,
+                activeRuntimeDir: active.runtimeDir,
+              }),
+            )
+          } catch {}
+          return
+        }
+
+        if (role === 'sim') {
+          if (sim) {
+            sim.lastSeenAt = Date.now()
+          }
+          if (msg.type === 'bridge:register' && sim) {
+            const registration = msg as BridgeSimRegistrationMessage
+            const restored = this.tryRestoreSimId(sim, registration.simId)
+            sim.url = registration.url
+            sim.title = registration.title
+            sim.userAgent = registration.userAgent
+            // kind/meta are optional and free-form. only update if the
+            // sender supplied a value so we don't accidentally clear
+            // state on a heartbeat-style re-register.
+            if (typeof registration.kind === 'string' && registration.kind.trim()) {
+              sim.kind = registration.kind.trim()
+            }
+            if (registration.meta && typeof registration.meta === 'object') {
+              sim.meta = registration.meta as Record<string, unknown>
+            }
+            // re-evaluate primary now that the sim has a real page. promotion
+            // is otherwise decided once at bare-connect, before `url` is
+            // known — so a page-less sim that grabbed primary as the
+            // last-resort fallback (or a stale zombie still holding it)
+            // would never be superseded by this freshly-registered, actually
+            // driveable sim (QA F19-2). only adopt a *different* sim so a
+            // routine heartbeat re-register doesn't churn the assignment.
+            const reElected = this.primarySimId !== sim.id && this.shouldPromoteSim(sim)
+            if (reElected) this.primarySimId = sim.id
+            if (restored || reElected) {
+              this.broadcastSimAssignments()
+              this.broadcastSimClientStates()
+            }
+            return
+          }
+
+          if (msg.type === 'bridge:user-focus-state' && sim) {
+            const focusState = msg as BridgeSimUserFocusStateMessage
+            this.updateUserFocusLease(sim, focusState)
+            return
+          }
+
+          if (msg.type === 'bridge:user-interact' && sim) {
+            this.updateUserActivity(sim)
+            return
+          }
+
+          // write a partial patch into ~/.sootsim/config.json. fired by the
+          // engine's settingsStore when a persisted key flips in a browser
+          // tab (which has no fs access of its own). after the merge, we
+          // broadcast the new full snapshot to every connected sim so any
+          // tab that has the engine config global picks up the change live
+          // — same shape as electron's `config:changed` IPC.
+          if (msg.type === 'bridge:write-shared-config') {
+            const patch =
+              msg.patch && typeof msg.patch === 'object'
+                ? (msg.patch as Partial<SharedConfig>)
+                : null
+            if (!patch) return
+            let next: SharedConfig
+            try {
+              next = writeSharedConfig(patch)
+            } catch (err) {
+              process.stderr.write(
+                `sootsim: bridge:write-shared-config failed: ${err instanceof Error ? err.message : String(err)}\n`,
+              )
+              return
+            }
+            const payload = JSON.stringify({
+              type: 'bridge:shared-config-changed',
+              config: next,
+            })
+            for (const peer of this.sims.values()) {
+              if (peer.ws.readyState !== WebSocket.OPEN) continue
+              try {
+                peer.ws.send(payload)
+              } catch {}
+            }
+            return
+          }
+
+          // open a source file in the user's editor. triggered by tappable
+          // stack frames in sootsim's RedBox overlay.
+          if (msg.type === 'bridge:open-path') {
+            const filePath = typeof msg.path === 'string' ? msg.path : ''
+            const line =
+              typeof msg.line === 'number' && Number.isFinite(msg.line)
+                ? msg.line
+                : undefined
+            const column =
+              typeof msg.column === 'number' && Number.isFinite(msg.column)
+                ? msg.column
+                : undefined
+            if (filePath) {
+              void this.openPathInEditor(filePath, line, column)
+            }
+            return
+          }
+
+          // boot-clients: disconnect all CLI clients attached to this sim
+          // and hand the sim to the user. an explicit Boot is a strong claim,
+          // so we install a user-active lease instead of clearing — otherwise
+          // a reconnecting agent (most spawn a fresh socket within ms of close)
+          // claims the empty slot before the user can interact and the boot
+          // becomes a no-op the user has to repeat indefinitely.
+          if (msg.type === 'bridge:boot-clients' && sim) {
+            const booted: WebSocket[] = []
+            for (const [cliWs, attachedSimId] of this.cliSimBySocket) {
+              if (attachedSimId === sim.id) {
+                booted.push(cliWs)
+              }
+            }
+            for (const cliWs of booted) {
+              this.cliSimBySocket.delete(cliWs)
+              try {
+                cliWs.close(1000, 'booted by sim')
+              } catch {}
+            }
+            const hadLease = !!sim.cliLease
+            sim.cliLease = {
+              kind: 'user-active',
+              cliIdentityKey: '__user-active__',
+              cliLabel: 'active user',
+              expiresAt: Date.now() + SootSimBridgeHost.USER_BOOT_LEASE_TTL_MS,
+            }
+            process.stderr.write(
+              `sootsim booted ${booted.length} cli client(s)${hadLease ? ' (overrode prior lease)' : ''}; held sim for user [${sim.id}]\n`,
+            )
+            this.recordSimAction(sim.id, 'sim booted cli clients')
+            this.broadcastSimClientStates()
+            return
+          }
+
+          const internalPending = this.pendingCommands.get(msg.id)
+          if (internalPending) {
+            this.pendingCommands.delete(msg.id)
+            if (msg.error) internalPending.reject(new Error(msg.error))
+            else internalPending.resolve(msg.result)
+            return
+          }
+
+          const entry = this.cliBySentId.get(msg.id)
+          if (entry) {
+            this.cliBySentId.delete(msg.id)
+            if (entry.ws.readyState === WebSocket.OPEN) {
+              // include other CLI count so the client can warn about contention
+              const otherCliCount = this.getOtherCliIdentityCount(entry.ws, entry.simId)
+              const response =
+                otherCliCount > 0
+                  ? { ...msg, id: entry.originalId, _otherCliCount: otherCliCount }
+                  : { ...msg, id: entry.originalId }
+              entry.ws.send(JSON.stringify(response))
+            }
+          }
+          return
+        }
+
+        void (async () => {
+          this.cliLastCommandAt.set(ws, Date.now())
+          try {
+            if (msg.type === 'bridge:bye') {
+              // explicit goodbye from a cli about to exit. drop its socket
+              // state immediately so the next invocation from the same agent
+              // doesn't see this one as a phantom peer. the subsequent tcp
+              // close event becomes a no-op.
+              const hadSim = this.cliSimBySocket.delete(ws)
+              this.cliLastCommandAt.delete(ws)
+              this.cliIdentityKeyBySocket.delete(ws)
+              this.cliLabelBySocket.delete(ws)
+              for (const [sentId, entry] of this.cliBySentId) {
+                if (entry.ws === ws) this.cliBySentId.delete(sentId)
+              }
+              if (hadSim) this.broadcastSimClientStates()
+              return
+            }
+
+            if (msg.type === 'bridge:hello') {
+              const key =
+                typeof msg.cliIdentityKey === 'string' && msg.cliIdentityKey.trim()
+                  ? msg.cliIdentityKey.trim()
+                  : this.cliIdentityKeyBySocket.get(ws) ||
+                    `ws-${this.nextCliFallbackId++}`
+              this.cliIdentityKeyBySocket.set(ws, key)
+              if (typeof msg.cliLabel === 'string' && msg.cliLabel.trim()) {
+                this.cliLabelBySocket.set(ws, msg.cliLabel.trim())
+              }
+              // same-identity cli sockets are allowed to coexist. this avoids
+              // self-disconnects when agent tooling issues multiple commands
+              // in parallel from the same logical identity key.
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(
+                  JSON.stringify({
+                    id: msg.id,
+                    result: {
+                      cliIdentityKey: key,
+                      leaseTtlMs: SootSimBridgeHost.CLI_LEASE_TTL_MS,
+                      leasing: true,
+                    },
+                  }),
+                )
+              }
+              return
+            }
+
+            if (msg.type === 'bridge:list-sims') {
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(
+                  JSON.stringify({
+                    id: msg.id,
+                    result: this.listSims(),
+                  }),
+                )
+              }
+              return
+            }
+
+            if (msg.type === 'bridge:open') {
+              if (typeof msg.url !== 'string' || !msg.url) {
+                throw new Error('bridge:open requires a url')
+              }
+              await this.openUrl(msg.url, { newWindow: msg.newWindow === true })
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(
+                  JSON.stringify({
+                    id: msg.id,
+                    result: { ok: true, url: msg.url },
+                  }),
+                )
+              }
+              return
+            }
+
+            if (msg.type === 'bridge:claim') {
+              const targetSim = await this.waitForSim(msg.simId)
+              const outcome = this.tryAcquireLease(ws, targetSim, {
+                force: msg.force === true,
+              })
+              if (!outcome.granted) {
+                if (ws.readyState === WebSocket.OPEN) {
+                  ws.send(
+                    JSON.stringify({
+                      id: msg.id,
+                      error: `sim ${targetSim.id} is locked by another cli`,
+                      _locked: outcome.lock,
+                    }),
+                  )
+                }
+                return
+              }
+              this.setCliSimTarget(ws, targetSim.id)
+              this.recordSimAction(
+                targetSim.id,
+                outcome.bootedCount > 0
+                  ? `cli force-claimed sim (booted ${outcome.bootedCount})`
+                  : 'cli claimed sim',
+              )
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(
+                  JSON.stringify({
+                    id: msg.id,
+                    result: {
+                      simId: targetSim.id,
+                      lockedBy: outcome.lease.cliIdentityKey,
+                      lockExpiresAt: outcome.lease.expiresAt,
+                      bootedCount: outcome.bootedCount,
+                    },
+                  }),
+                )
+              }
+              return
+            }
+
+            const targetSim = await this.waitForSim(msg.simId)
+            if (shouldAcquireLease(msg)) {
+              const outcome = this.tryAcquireLease(ws, targetSim)
+              if (!outcome.granted) {
+                if (ws.readyState === WebSocket.OPEN) {
+                  ws.send(
+                    JSON.stringify({
+                      id: msg.id,
+                      error: `sim ${targetSim.id} is locked by another cli — use \`sootsim claim ${targetSim.id} --force\` or \`sootsim open --new\``,
+                      _locked: outcome.lock,
+                    }),
+                  )
+                }
+                return
+              }
+            } else {
+              // read-only / observational pass-through: still register this
+              // cli as attached so list/describe shows it, but never block.
+              this.ensureCliIdentityKey(ws)
+            }
+            this.setCliSimTarget(ws, targetSim.id)
+            this.recordSimAction(targetSim.id, this.describeForwardedCommand(msg))
+            const sentId = this.nextCommandId++
+            this.cliBySentId.set(sentId, {
+              simId: targetSim.id,
+              ws,
+              originalId: msg.id,
+            })
+            const { simId: _simId, ...forwarded } = msg
+            targetSim.ws.send(JSON.stringify({ ...forwarded, id: sentId }))
+            // `close` must never hang on the sim page. a frozen sim never
+            // processes the forwarded close and never replies, so the CLI
+            // command would otherwise time out after the full command
+            // window (M3). treat close as fire-and-forget: ack the CLI now,
+            // drop the pending relay entry so a late sim reply is harmless,
+            // and disconnect the sim socket with the terminal close code if
+            // the page has not closed itself within the grace window.
+            if (forwarded.type === 'close') {
+              this.cliBySentId.delete(sentId)
+              if (ws.readyState === WebSocket.OPEN) {
+                ws.send(
+                  JSON.stringify({
+                    id: msg.id,
+                    result: { requested: true, simId: targetSim.id },
+                  }),
+                )
+              }
+              const simWs = targetSim.ws
+              const closeTimer = setTimeout(() => {
+                this.closeSimSocketFromHost(simWs)
+              }, FORCE_CLOSE_GRACE_MS)
+              unrefTimer(closeTimer)
+            }
+          } catch (err) {
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(
+                JSON.stringify({
+                  id: msg.id,
+                  error: err instanceof Error ? err.message : String(err),
+                }),
+              )
+            }
+          }
+        })()
+      })
+
+      ws.on('close', () => {
+        // always drop agent subscriptions first — the FIFO refcount needs
+        // to settle before any later broadcast fan-out fires.
+        this.agentHost.unregisterSocket(ws)
+        if (role === 'sim' && sim) {
+          this.rememberDisconnectedSim(sim)
+          if (this.primarySimId === sim.id) {
+            this.primarySimId = this.getOpenSim()?.id ?? null
+          }
+          for (const [id, pending] of this.pendingCommands) {
+            if (pending.simId !== sim.id) continue
+            pending.reject(new Error('sim disconnected'))
+            this.pendingCommands.delete(id)
+          }
+          for (const [sentId, entry] of this.cliBySentId) {
+            if (entry.simId !== sim.id) continue
+            if (entry.ws.readyState === WebSocket.OPEN) {
+              entry.ws.send(
+                JSON.stringify({
+                  id: entry.originalId,
+                  error: 'sim disconnected before responding',
+                }),
+              )
+            }
+            this.cliBySentId.delete(sentId)
+          }
+          this.broadcastSimAssignments()
+          this.broadcastSimClientStates()
+        } else if (role === 'cli') {
+          const detached = this.cliSimBySocket.delete(ws)
+          this.cliLastCommandAt.delete(ws)
+          this.cliIdentityKeyBySocket.delete(ws)
+          this.cliLabelBySocket.delete(ws)
+          for (const [sentId, entry] of this.cliBySentId) {
+            if (entry.ws === ws) this.cliBySentId.delete(sentId)
+          }
+          if (detached) {
+            this.broadcastSimClientStates()
+          }
+        }
+      })
+    })
+  }
+
+  /** after a successful bind: start the cli idle sweep, write the daemon
+   *  lockfile (if this host owns it), seed the agent host, kick off the
+   *  heartbeat loop. idempotent across rebinds because close() tears down
+   *  every timer and the lockfile. */
+  private afterBind() {
+    process.stderr.write(`ws bridge listening on port ${this.port}\n`)
+
+    this.cliIdleTimer = setInterval(
+      () => this.sweepIdleCliClients(),
+      30_000,
+    ) as unknown as NodeJS.Timeout
+    this.cliIdleTimer.unref()
+
+    this.wsHeartbeatTimer = setInterval(
+      () => this.sweepDeadWebSockets(),
+      SootSimBridgeHost.WS_HEARTBEAT_INTERVAL_MS,
+    ) as unknown as NodeJS.Timeout
+    this.wsHeartbeatTimer.unref()
+
+    if (this.shouldWriteLockfile) {
+      try {
+        ensureSootsimHome()
+        // atomic claim: bail if another fresh daemon's lockfile already
+        // exists (stale ones are overwritten). last line of defense
+        // against two daemons clobbering the same file between the
+        // freshness check in server.ts and here.
+        const claimed = claimDaemonLockfile(this.buildLockfileSnapshot())
+        if (!claimed) {
+          throw new Error(
+            'another sootsim daemon wrote the lockfile during startup — aborting',
+          )
+        }
+      } catch (err) {
+        process.stderr.write(
+          `ws bridge failed to claim daemon lockfile: ${String(err)}\n`,
+        )
+        throw err
+      }
+      this.heartbeatTimer = setInterval(() => {
+        try {
+          this.writeLockfileSnapshot()
+        } catch {}
+      }, DAEMON_HEARTBEAT_INTERVAL_MS) as unknown as NodeJS.Timeout
+      this.heartbeatTimer.unref()
+      this.startRuntimeUpdater()
+    }
+
+    // seed the attached-projects store from the demo registry on first
+    // daemon boot. idempotent; no-ops once the store has anything in it.
+    void this.agentHost.seedOnBoot()
+  }
+
+  private bootstrapping = true
+
+  private buildLockfileSnapshot(): DaemonLockfile {
+    return {
+      schema: 1,
+      pid: process.pid,
+      platform: process.platform,
+      bridgePort: this.effectivePort,
+      runtimePort: this.effectivePort,
+      activeRuntime: this.activeRuntimeVersion,
+      activeRuntimeDir: this.activeRuntimeDirPath,
+      startedAt: this.startedAt,
+      heartbeatAt: Date.now(),
+      bootstrapping: this.bootstrapping,
+    }
+  }
+
+  private writeLockfileSnapshot() {
+    writeDaemonLockfile(this.buildLockfileSnapshot())
+  }
+
+  private refreshActiveRuntime() {
+    this.activeRuntimeVersion = readActiveRuntime()
+    this.activeRuntimeDirPath = getActiveRuntimeDir()
+  }
+
+  private runServerScan(): Promise<DiscoveredServer[]> {
+    if (this.inflightScan) return this.inflightScan
+    const excludePorts = this.effectivePort > 0 ? [this.effectivePort] : []
+    this.inflightScan = scanDevServers({
+      excludePorts,
+      buildIconProxyUrl: (externalUrl) =>
+        `/__bundle-proxy?url=${encodeURIComponent(externalUrl)}`,
+    })
+      .then((results) => {
+        this.scanCache = results
+        this.scanCacheAt = Date.now()
+        return results
+      })
+      .catch((err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err)
+        console.error('[sootsim] /__server-scan failed:', message)
+        return this.scanCache ?? []
+      })
+      .finally(() => {
+        this.inflightScan = null
+      })
+    return this.inflightScan
+  }
+
+  private handleServerScan(res: ServerResponse) {
+    const sendJson = (body: DiscoveredServer[]) => {
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+      })
+      res.end(JSON.stringify(body))
+    }
+    const age = Date.now() - this.scanCacheAt
+    if (this.scanCache && age < SootSimBridgeHost.SCAN_FRESH_MS) {
+      sendJson(this.scanCache)
+      return
+    }
+    if (this.scanCache) {
+      // stale-while-revalidate: return last known good immediately, kick a
+      // fresh scan in the background.
+      sendJson(this.scanCache)
+      void this.runServerScan().catch(() => {})
+      return
+    }
+    void this.runServerScan().then((results) => sendJson(results))
+  }
+
+  private resolveRuntimeUpdateIntervalMs() {
+    const raw = Number(process.env[RUNTIME_UPDATE_INTERVAL_ENV])
+    if (Number.isFinite(raw) && raw > 0) return Math.max(100, Math.round(raw))
+    return DEFAULT_RUNTIME_UPDATE_INTERVAL_MS
+  }
+
+  private startRuntimeUpdater() {
+    if (!this.shouldWriteLockfile || this.runtimeUpdateTimer) return
+    void this.runRuntimeUpdate('startup')
+    const intervalMs = this.resolveRuntimeUpdateIntervalMs()
+    this.runtimeUpdateTimer = setInterval(() => {
+      void this.runRuntimeUpdate('periodic')
+    }, intervalMs) as unknown as NodeJS.Timeout
+    this.runtimeUpdateTimer.unref()
+  }
+
+  private runRuntimeUpdate(reason: 'startup' | 'periodic'): Promise<void> {
+    if (this.runtimeUpdateInFlight) return this.runtimeUpdateInFlight
+    this.runtimeUpdateInFlight = (async () => {
+      try {
+        if (reason === 'startup') {
+          process.stderr.write('sootsim: checking for runtime updates…\n')
+        }
+        const result = await updateRuntimeToLatest()
+        if (!result.updated || !result.latestVersion) {
+          if (reason === 'startup') {
+            process.stderr.write(
+              `sootsim: runtime ${this.activeRuntimeVersion ?? '(none)'} is current\n`,
+            )
+          }
+          return
+        }
+        const active = this.setActiveRuntime(result.latestVersion)
+        process.stderr.write(`sootsim runtime updated to ${active.version} (${reason})\n`)
+      } catch (err) {
+        process.stderr.write(
+          `sootsim runtime update failed (${reason}): ${
+            err instanceof Error ? err.message : String(err)
+          }\n`,
+        )
+      } finally {
+        this.runtimeUpdateInFlight = null
+        // first-boot gate flips off once the startup pass finishes (success
+        // or fail) — clients can navigate even if the network update failed
+        // as long as some runtime is on disk. without this the splash would
+        // wait forever on a temporary network blip.
+        if (reason === 'startup' && this.bootstrapping) {
+          this.bootstrapping = false
+          if (this.shouldWriteLockfile && this.httpServer) {
+            try {
+              this.writeLockfileSnapshot()
+            } catch {}
+          }
+          process.stderr.write('sootsim: ready\n')
+        }
+      }
+    })()
+    return this.runtimeUpdateInFlight
+  }
+
+  /** update the active runtime on disk + in memory. the caller guarantees
+   *  the version directory exists. pushes a runtime:changed message to all
+   *  connected sims so electron (or any renderer) can reload. */
+  setActiveRuntime(version: string): { version: string; runtimeDir: string | null } {
+    writeActiveRuntime(version)
+    this.refreshActiveRuntime()
+    if (this.shouldWriteLockfile && this.httpServer) {
+      try {
+        this.writeLockfileSnapshot()
+      } catch {}
+    }
+    // broadcast to sims so electron can reload its webContents without
+    // a manual restart. CLI clients ignore this message.
+    const payload = JSON.stringify({
+      type: 'runtime:changed',
+      version,
+      runtimeDir: this.activeRuntimeDirPath,
+    })
+    for (const sim of this.sims.values()) {
+      if (sim.ws.readyState === WebSocket.OPEN) {
+        try {
+          sim.ws.send(payload)
+        } catch {}
+      }
+    }
+    return { version, runtimeDir: this.activeRuntimeDirPath }
+  }
+
+  getActiveRuntime(): { version: string | null; runtimeDir: string | null } {
+    return {
+      version: this.activeRuntimeVersion,
+      runtimeDir: this.activeRuntimeDirPath,
+    }
+  }
+
+  /** last-ditch lockfile cleanup. safe to call from a synchronous
+   *  `process.on('exit', ...)` handler since it only does a fs.unlinkSync. */
+  removeLockfile() {
+    if (!this.shouldWriteLockfile) return
+    try {
+      removeDaemonLockfile()
+    } catch {}
+  }
+
+  /** minimal HTTP request handler attached to the same node http server
+   *  that hosts the WS upgrade. handles:
+   *    GET /healthz        json status for supervisors / curl
+   *    GET / + everything  serves from the active runtime dist, SPA fallback
+   *  non-upgrade routes that don't match serve index.html (SPA behavior) so
+   *  electron's webContents can navigate freely inside the runtime. */
+  private handleHttpRequest(req: IncomingMessage, res: ServerResponse) {
+    // cross-origin isolation — without this, Electron / Chromium refuses
+    // `SharedArrayBuffer`, and the engine's render-worker crashes on boot
+    // ("render worker crashed during boot" / "app:one surface registration
+    // failed"). SAB powers the shell-scene fast channel and the worklet
+    // runtime's SharedValues. mirrors sootsim-shell/vite.config.ts (dev) and
+    // sootbean.com app/_middleware.ts (prod) so the cli daemon serves the
+    // same surface those two already enforce. set via setHeader so subsequent
+    // writeHead() calls preserve them (writeHead only overrides keys it
+    // explicitly passes). credentialless lets cross-origin sub-resources
+    // (metro bundles, font files) load without requiring CORP from every
+    // upstream — same trade-off prod already accepts.
+    res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+    res.setHeader('Cross-Origin-Embedder-Policy', 'credentialless')
+    res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin')
+    res.setHeader('Document-Policy', 'js-profiling')
+
+    // proxy + app-api routes need to accept POST/PUT/DELETE/PATCH/OPTIONS
+    // because they forward the request to a real upstream. handle them
+    // BEFORE the read-only method check below — otherwise tenant bundles
+    // fetching cross-origin APIs through the daemon (e.g. when the shell
+    // dev server isn't running) get a 405 instead of the proxied response,
+    // and downstream NetInfo-style reachability probes flip to "offline".
+    if (isFetchProxyRequestUrl(req.url)) {
+      void handleFetchProxyRequest(req, res)
+      return
+    }
+    if (isAppApiRequestUrl(req.url) && handleAppApiRequest(req, res)) {
+      return
+    }
+
+    // only accept read methods. anything else returns 405 — we never
+    // mutate via http; the WS channel owns all writes.
+    const method = (req.method || 'GET').toUpperCase()
+    if (method !== 'GET' && method !== 'HEAD') {
+      res.writeHead(405, { Allow: 'GET, HEAD' })
+      res.end('method not allowed')
+      return
+    }
+
+    const url = new URL(req.url || '/', 'http://localhost')
+
+    // /__bundle-proxy?url=<encoded> — runtime/worker fetches metro bundles +
+    // assets through here. needed because workers can't directly fetch a
+    // cross-origin URL without CORS headers, and metro doesn't set them.
+    // we proxy the request and stream the response back.
+    if (url.pathname === '/__bundle-proxy') {
+      const target = url.searchParams.get('url')
+      if (!target) {
+        res.writeHead(400, { 'Content-Type': 'text/plain' })
+        res.end('bundle-proxy: missing url query param')
+        return
+      }
+      let parsedTarget: URL
+      try {
+        parsedTarget = new URL(target)
+      } catch {
+        res.writeHead(400, { 'Content-Type': 'text/plain' })
+        res.end('bundle-proxy: invalid url')
+        return
+      }
+      // limit to local loopback targets — preventing the daemon from being
+      // turned into an open proxy for arbitrary internet fetches.
+      const host = parsedTarget.hostname
+      const isLoopback =
+        host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host.endsWith('.localhost')
+      if (!isLoopback) {
+        res.writeHead(403, { 'Content-Type': 'text/plain' })
+        res.end('bundle-proxy: only loopback targets allowed')
+        return
+      }
+      void (async () => {
+        try {
+          const upstream = await fetch(parsedTarget.toString(), {
+            redirect: 'follow',
+          })
+          const headers: Record<string, string> = {}
+          const ct = upstream.headers.get('content-type')
+          if (ct) headers['Content-Type'] = ct
+          headers['Cache-Control'] = 'no-store'
+          res.writeHead(upstream.status, headers)
+          if (!upstream.body) {
+            res.end()
+            return
+          }
+          const reader = upstream.body.getReader()
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            res.write(Buffer.from(value))
+          }
+          res.end()
+        } catch (err) {
+          res.writeHead(502, { 'Content-Type': 'text/plain' })
+          res.end(
+            `bundle-proxy: upstream fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+      })()
+      return
+    }
+
+    // /__server-scan — list local metro/expo/vxrn/one dev servers. tenant
+    // worker ConnectRN polls this every few seconds to populate the device
+    // picker. mirrors packages/sootsim-shell/src/dev-middleware.ts so both
+    // host environments (vite dev and the prod CLI daemon) return identical
+    // JSON. icon URLs are rewritten through /__bundle-proxy so the browser
+    // doesn't hit cross-origin loads against the discovered dev server.
+    if (url.pathname === '/__server-scan') {
+      this.handleServerScan(res)
+      return
+    }
+
+    if (url.pathname === '/healthz') {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+      })
+      res.end(
+        JSON.stringify({
+          ok: true,
+          pid: process.pid,
+          platform: process.platform,
+          bridgePort: this.effectivePort,
+          runtimePort: this.effectivePort,
+          activeRuntime: this.activeRuntimeVersion,
+          startedAt: this.startedAt,
+          uptimeMs: this.startedAt > 0 ? Date.now() - this.startedAt : 0,
+        }),
+      )
+      return
+    }
+
+    // /__sootsim/shared-config — bridge over ~/.sootsim/config.json for
+    // browser tabs that have no other path to disk (private windows,
+    // statically hosted runtime). GET returns the parsed config; POST
+    // merges a partial patch via writeSharedConfig (same shallow-merge
+    // semantics used by electron). matches the shell dev server's
+    // route at the same path so the engine's persistence layer can use
+    // one url regardless of host. cors-permissive because the runtime
+    // and the page may have different origins (electron loads from
+    // bridgePort; demo apps may iframe across origins).
+    if (url.pathname === '/__sootsim/shared-config') {
+      res.setHeader('Access-Control-Allow-Origin', '*')
+      res.setHeader('Cache-Control', 'no-store')
+      if (method === 'GET' || method === 'HEAD') {
+        let body = '{}'
+        try {
+          body = JSON.stringify(readSharedConfig())
+        } catch {}
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        if (method === 'HEAD') res.end()
+        else res.end(body)
+        return
+      }
+      res.writeHead(405, { Allow: 'GET, HEAD' })
+      res.end('method not allowed (use the bridge over WS for writes)')
+      return
+    }
+
+    // runtime may have been swapped on disk (sootsim runtime use via file
+    // write, or another cli process) — re-read per-request so we serve
+    // the current active version. cost is one readFileSync + one statSync.
+    this.refreshActiveRuntime()
+    const baseDir = this.activeRuntimeDirPath
+    if (!baseDir) {
+      res.writeHead(503, { 'Content-Type': 'text/plain; charset=utf-8' })
+      res.end(
+        'sootsim: no active runtime installed. run `sootsim runtime install` to fetch one.',
+      )
+      return
+    }
+
+    // strip optional runtime prefixes so the daemon can serve both the
+    // local entrypoint and the production-built /sootsim asset graph.
+    let rel = url.pathname
+    if (rel === '/runtime' || rel === '/runtime/') rel = '/'
+    else if (rel.startsWith('/runtime/')) rel = rel.slice('/runtime'.length)
+    else if (rel === '/sootsim' || rel === '/sootsim/') rel = '/'
+    else if (rel.startsWith('/sootsim/')) rel = rel.slice('/sootsim'.length)
+    if (rel === '' || rel === '/') rel = '/index.html'
+
+    // reject obviously-malicious paths up front:
+    //   NUL bytes (some fs APIs truncate, confusing downstream readers)
+    //   backslashes on non-Windows (treated literally in names, but
+    //     frequently used to sneak past string-level .. checks)
+    //   raw .. segments (path.resolve collapses them, but reject on sight
+    //     so traversal attempts surface as 400s in logs)
+    if (rel.includes('\0')) {
+      res.writeHead(400)
+      res.end('bad request')
+      return
+    }
+    if (process.platform !== 'win32' && rel.includes('\\')) {
+      res.writeHead(400)
+      res.end('bad request')
+      return
+    }
+    for (const segment of rel.split('/')) {
+      if (segment === '..') {
+        res.writeHead(403)
+        res.end('forbidden')
+        return
+      }
+    }
+
+    const resolved = path.resolve(baseDir, '.' + rel)
+    const baseWithSep = baseDir.endsWith(path.sep) ? baseDir : baseDir + path.sep
+    if (!resolved.startsWith(baseWithSep) && resolved !== baseDir) {
+      res.writeHead(403)
+      res.end('forbidden')
+      return
+    }
+
+    // realpath the resolved path before serving. this catches symlinks
+    // inside baseDir that point outside — without it, an attacker who can
+    // drop a symlink in the runtime dir gets arbitrary-read through the
+    // daemon. realpath also collapses any remaining normalizable segments.
+    fs.realpath(resolved, (realErr, realResolved) => {
+      const servePath = realErr ? resolved : realResolved
+      const servePathWithSep = servePath.endsWith(path.sep)
+        ? servePath
+        : servePath + path.sep
+      if (!realErr) {
+        const realBaseWithSep = (() => {
+          try {
+            const rb = fs.realpathSync(baseDir)
+            return rb.endsWith(path.sep) ? rb : rb + path.sep
+          } catch {
+            return baseWithSep
+          }
+        })()
+        if (
+          !servePathWithSep.startsWith(realBaseWithSep) &&
+          servePath + path.sep !== realBaseWithSep
+        ) {
+          res.writeHead(403)
+          res.end('forbidden')
+          return
+        }
+      }
+
+      fs.stat(servePath, (err, stats) => {
+        if (err || !stats?.isFile()) {
+          // SPA fallback — but only for extensionless paths. a 404 on
+          // /main.a1b2c3.js should 404, not return index.html as js,
+          // which the sim then chokes on.
+          const ext = path.extname(rel).toLowerCase()
+          if (ext && ext !== '.html') {
+            res.writeHead(404)
+            res.end('not found')
+            return
+          }
+          // never SPA-fallback internal endpoint namespaces — those are
+          // expected to return JSON (or a real 404) and the engine calls
+          // .json() on the response. without this, a tenant-worker fetch
+          // to an unimplemented /__foo or /api/foo gets a 200 + index.html
+          // and explodes with "Unexpected token '<', '<!doctype'... is not
+          // valid JSON". /__server-scan is the canonical case (see the
+          // handler above).
+          if (rel.startsWith('/__') || rel.startsWith('/api/') || rel === '/api') {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' })
+            res.end('not found')
+            return
+          }
+          const indexPath = path.join(baseDir, 'index.html')
+          fs.readFile(indexPath, (err2, data) => {
+            if (err2) {
+              res.writeHead(404)
+              res.end('not found')
+              return
+            }
+            res.writeHead(200, {
+              'Content-Type': 'text/html; charset=utf-8',
+              'Cache-Control': 'no-store',
+            })
+            if (method === 'HEAD') {
+              res.end()
+              return
+            }
+            res.end(
+              injectSharedConfigIntoHtml(data, this.effectivePort, this.sootbeanOrigin),
+            )
+          })
+          return
+        }
+        const ext = path.extname(servePath).toLowerCase()
+        const contentType = HTTP_MIME_TYPES[ext] || 'application/octet-stream'
+        // no-store across the board: the runtime is served from a versioned
+        // directory but the HTTP path doesn't include the version, so the
+        // same URL serves different content after a runtime swap. caching
+        // any asset means a stale-bundle reload after runtime:changed.
+        res.writeHead(200, {
+          'Content-Type': contentType,
+          'Cache-Control': 'no-store',
+        })
+        if (method === 'HEAD') {
+          res.end()
+          return
+        }
+        // html responses inline the daemon-injected `__sootsimSharedConfig`
+        // global so the engine's settingsStore initializes from disk on
+        // boot. for everything else stream the file straight through.
+        if (ext === '.html') {
+          fs.readFile(servePath, (readErr, data) => {
+            if (readErr) {
+              try {
+                res.end()
+              } catch {}
+              return
+            }
+            res.end(
+              injectSharedConfigIntoHtml(data, this.effectivePort, this.sootbeanOrigin),
+            )
+          })
+          return
+        }
+        const stream = fs.createReadStream(servePath)
+        stream.pipe(res)
+        stream.on('error', () => {
+          try {
+            res.end()
+          } catch {}
+        })
+      })
+    })
+  }
+
+  private sweepIdleCliClients() {
+    const now = Date.now()
+    let swept = false
+    for (const [ws, simId] of this.cliSimBySocket) {
+      const lastCommand = this.cliLastCommandAt.get(ws) ?? 0
+      if (now - lastCommand < SootSimBridgeHost.CLI_IDLE_TIMEOUT_MS) continue
+      this.cliSimBySocket.delete(ws)
+      this.cliLastCommandAt.delete(ws)
+      for (const [sentId, entry] of this.cliBySentId) {
+        if (entry.ws === ws) this.cliBySentId.delete(sentId)
+      }
+      try {
+        ws.close(1000, 'idle timeout')
+      } catch {}
+      swept = true
+    }
+    if (swept) {
+      this.broadcastSimClientStates()
+    }
+    this.sweepRestorableSims(now)
+    this.reapIdleSims(now)
+  }
+
+  // GC abandoned sims so `sootsim list` stays usable across long dev / QA /
+  // test sessions (F21-3). conservative on purpose: a sim is only reaped
+  // when every "someone cares about this" signal is absent.
+  //
+  // NOTE: `sim.userFocused` is deliberately NOT an exemption. focus is
+  // advisory in this design — see updateUserFocusLease: "focus alone never
+  // creates a blocking lease … use updateUserActivity() to lock on real
+  // interaction instead." real interaction (pointer/key/wheel/touch)
+  // refreshes a `user-active` lease, which the getActiveLease() guard below
+  // already honors. a headless playwright tab reports `focused:true` once
+  // and never `false` (nothing else competes for focus in headless), so a
+  // userFocused exemption permanently shielded exactly the abandoned-tab
+  // zombie class F21-3 / F19-2 target (QA F22-2). a sim a human is genuinely
+  // using is the primary and/or holds a fresh user-active lease; one that is
+  // none of those and idle past the TTL is abandoned regardless of a stale
+  // focus flag.
+  private reapIdleSims(now = Date.now()) {
+    const attachedSimIds = new Set(this.cliSimBySocket.values())
+    for (const sim of this.sims.values()) {
+      if (sim.id === this.primarySimId) continue
+      if (attachedSimIds.has(sim.id)) continue
+      if (this.getActiveLease(sim)) continue
+      // never-CLI-driven sims have lastActiveAt 0 — fall back to connectedAt
+      // so a freshly opened, not-yet-primary tab isn't reaped on the spot.
+      const lastTouched = Math.max(sim.lastActiveAt, sim.connectedAt)
+      if (now - lastTouched < this.simIdleReapTtlMs) continue
+      // terminal close → client closes the window, does not reconnect; the
+      // 'close' handler runs rememberDisconnectedSim → this.sims.delete.
+      this.closeSimSocketFromHost(sim.ws)
+    }
+  }
+
+  // ping every connected ws; if the previous round's ping went unanswered,
+  // terminate the socket so 'close' fires and the sim cleanup path
+  // runs. matches the recommended ws-library heartbeat pattern.
+  private sweepDeadWebSockets() {
+    if (!this.wss) return
+    for (const ws of this.wss.clients) {
+      if (ws.readyState !== WebSocket.OPEN) continue
+      const alive = this.wsIsAlive.get(ws)
+      if (alive === false) {
+        try {
+          ws.terminate()
+        } catch {}
+        continue
+      }
+      this.wsIsAlive.set(ws, false)
+      try {
+        ws.ping()
+      } catch {
+        try {
+          ws.terminate()
+        } catch {}
+      }
+    }
+  }
+
+  private closeSimSocketFromHost(ws: WebSocket) {
+    if (ws.readyState !== WebSocket.OPEN) return
+    try {
+      ws.close(SOOTSIM_BRIDGE_SIM_CLOSE_CODE, SOOTSIM_BRIDGE_SIM_CLOSE_REASON)
+    } catch {
+      try {
+        ws.terminate()
+      } catch {}
+      return
+    }
+    const terminateTimer = setTimeout(() => {
+      if (ws.readyState === WebSocket.CLOSED) return
+      try {
+        ws.terminate()
+      } catch {}
+    }, FORCE_CLOSE_TERMINATE_MS)
+    unrefTimer(terminateTimer)
+  }
+
+  listSims(): BridgeSimInfo[] {
+    return Array.from(this.sims.values())
+      .sort((a, b) => {
+        if (a.id === this.primarySimId) return -1
+        if (b.id === this.primarySimId) return 1
+        return a.connectedAt - b.connectedAt
+      })
+      .map((sim) => this.describeSim(sim))
+  }
+
+  async sendCommand(cmd: Omit<BridgeSimCommand, 'id'>): Promise<any> {
+    const sim = await this.waitForSim(cmd.simId)
+    const id = this.nextCommandId++
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingCommands.delete(id)
+        this.broadcastSimClientStates()
+        reject(new Error('command timed out after 30s'))
+      }, 30000)
+
+      this.pendingCommands.set(id, {
+        simId: sim.id,
+        resolve: (value) => {
+          clearTimeout(timeout)
+          this.pendingCommands.delete(id)
+          this.broadcastSimClientStates()
+          resolve(value)
+        },
+        reject: (error) => {
+          clearTimeout(timeout)
+          this.pendingCommands.delete(id)
+          this.broadcastSimClientStates()
+          reject(error)
+        },
+      })
+      this.broadcastSimClientStates()
+
+      const { simId: _simId, ...forwarded } = cmd
+      sim.ws.send(JSON.stringify({ ...forwarded, id }))
+    })
+  }
+
+  async evaluate(code: string, simId?: string): Promise<any> {
+    return this.sendCommand({ type: 'evaluate', code, simId })
+  }
+
+  async focusSim(simId?: string): Promise<any> {
+    return this.sendCommand({ type: 'focus', simId })
+  }
+
+  async closeSim(simId?: string): Promise<any> {
+    return this.sendCommand({ type: 'close', simId })
+  }
+
+  async openPathInEditor(
+    filePath: string,
+    line?: number,
+    column?: number,
+  ): Promise<void> {
+    const loc = line != null ? `:${line}${column != null ? `:${column}` : ''}` : ''
+    const target = `${filePath}${loc}`
+
+    const trySpawn = (cmd: string, args: string[]) =>
+      new Promise<boolean>((resolve) => {
+        try {
+          const child = spawn(cmd, args, { detached: true, stdio: 'ignore' })
+          let settled = false
+          child.on('error', () => {
+            if (settled) return
+            settled = true
+            resolve(false)
+          })
+          child.on('spawn', () => {
+            if (settled) return
+            settled = true
+            child.unref()
+            resolve(true)
+          })
+        } catch {
+          resolve(false)
+        }
+      })
+
+    // prefer the editor the user told us about, then common cli wrappers,
+    // then fall back to the plain `open` path.
+    const envEditor = process.env.REACT_EDITOR || process.env.EDITOR
+    if (envEditor) {
+      const parts = envEditor.split(' ').filter(Boolean)
+      if (parts.length && (await trySpawn(parts[0], [...parts.slice(1), '-g', target])))
+        return
+    }
+    if (await trySpawn('cursor', ['-g', target])) return
+    if (await trySpawn('code', ['-g', target])) return
+    await this.openUrl(filePath)
+  }
+
+  async openUrl(url: string, options: OpenUrlOptions = {}): Promise<void> {
+    if (this.openUrlHandler) {
+      await this.openUrlHandler(url, options)
+      return
+    }
+    await openUrlInBrowser(url, options)
+  }
+
+  async close() {
+    if (this.cliIdleTimer) {
+      clearInterval(this.cliIdleTimer)
+      this.cliIdleTimer = null
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+    if (this.wsHeartbeatTimer) {
+      clearInterval(this.wsHeartbeatTimer)
+      this.wsHeartbeatTimer = null
+    }
+    if (this.runtimeUpdateTimer) {
+      clearInterval(this.runtimeUpdateTimer)
+      this.runtimeUpdateTimer = null
+    }
+    if (this.shouldWriteLockfile) {
+      try {
+        removeDaemonLockfile()
+      } catch {}
+    }
+    this.effectivePort = 0
+    this.startedAt = 0
+    this.agentHost.close()
+    for (const [id, pending] of this.pendingCommands) {
+      pending.reject(new Error('server closing'))
+      this.pendingCommands.delete(id)
+    }
+    for (const sim of this.sims.values()) {
+      sim.ws.close()
+    }
+    this.sims.clear()
+    this.primarySimId = null
+    const wss = this.wss
+    const httpServer = this.httpServer
+    this.wss = null
+    this.httpServer = null
+    if (wss) {
+      try {
+        wss.close()
+      } catch {}
+    }
+    if (httpServer) {
+      try {
+        httpServer.close()
+      } catch {}
+    }
+  }
+
+  private describeSim(sim: BridgeSimConnection): BridgeSimInfo {
+    let readyState: BridgeSimConnection['ws']['readyState']
+    try {
+      readyState = sim.ws.readyState
+    } catch {
+      readyState = WebSocket.CLOSED
+    }
+    const lease = this.getActiveLease(sim)
+    return {
+      id: sim.id,
+      origin: sim.origin,
+      url: sim.url,
+      title: sim.title,
+      userAgent: sim.userAgent,
+      connectedAt: sim.connectedAt,
+      lastSeenAt: sim.lastSeenAt,
+      lastActiveAt: sim.lastActiveAt || undefined,
+      isPrimary: sim.id === this.primarySimId,
+      readyState:
+        readyState === WebSocket.OPEN
+          ? 'open'
+          : readyState === WebSocket.CLOSING
+            ? 'closing'
+            : 'closed',
+      attachedCliCount: this.getAttachedCliCount(sim.id),
+      lockedBy: lease ? lease.cliLabel || lease.cliIdentityKey : undefined,
+      lockedByKind: lease ? lease.kind : undefined,
+      lockExpiresAt: lease ? lease.expiresAt : undefined,
+      userFocused: sim.userFocused || undefined,
+      userVisible: sim.userVisible,
+      visibilityState: sim.visibilityState,
+      documentFocused: sim.documentFocused,
+      kind: sim.kind,
+      meta: sim.meta,
+    }
+  }
+
+  private getActiveLease(sim: BridgeSimConnection): BridgeCliLease | null {
+    const lease = sim.cliLease
+    if (!lease) return null
+    if (Date.now() >= lease.expiresAt) {
+      sim.cliLease = undefined
+      return null
+    }
+    return lease
+  }
+
+  private tryAcquireLease(
+    ws: WebSocket,
+    sim: BridgeSimConnection,
+    opts: { force?: boolean } = {},
+  ): {
+    granted: boolean
+    lease: BridgeCliLease
+    lock?: BridgeLockInfo
+    bootedCount: number
+  } {
+    const cliIdentityKey =
+      this.cliIdentityKeyBySocket.get(ws) ??
+      (() => {
+        const fallback = `ws-${this.nextCliFallbackId++}`
+        this.cliIdentityKeyBySocket.set(ws, fallback)
+        return fallback
+      })()
+    const cliLabel = this.cliLabelBySocket.get(ws)
+    const now = Date.now()
+    const existing = this.getActiveLease(sim)
+    const ownerMatches = existing && existing.cliIdentityKey === cliIdentityKey
+    let bootedCount = 0
+
+    if (existing && !ownerMatches && !opts.force) {
+      return {
+        granted: false,
+        lease: existing,
+        lock: {
+          by: existing.cliLabel || existing.cliIdentityKey,
+          expiresInMs: Math.max(0, existing.expiresAt - now),
+        },
+        bootedCount: 0,
+      }
+    }
+
+    if (existing && !ownerMatches && opts.force) {
+      // boot other CLI sockets attached to this sim that don't share the lease key
+      for (const [cliWs, attachedSimId] of this.cliSimBySocket) {
+        if (attachedSimId !== sim.id) continue
+        const otherKey = this.cliIdentityKeyBySocket.get(cliWs)
+        if (otherKey && otherKey !== cliIdentityKey) {
+          this.cliSimBySocket.delete(cliWs)
+          try {
+            cliWs.close(1000, 'lease claimed by another cli')
+          } catch {}
+          bootedCount++
+        }
+      }
+    }
+
+    const lease: BridgeCliLease = {
+      kind: 'cli',
+      cliIdentityKey,
+      cliLabel,
+      expiresAt: now + SootSimBridgeHost.CLI_LEASE_TTL_MS,
+    }
+    sim.cliLease = lease
+    return { granted: true, lease, bootedCount }
+  }
+
+  // user focus is advisory: we track it on the sim record so list/UI can
+  // show "focused" alongside any cli lease, but focus alone never creates a
+  // blocking lease. the old 15s user-focus lease meant clicking on the sim
+  // locked out agent inspect calls for 15s — the opposite of what you want
+  // when debugging something the user is actively looking at. use
+  // updateUserActivity() to lock on real interaction instead.
+  private updateUserFocusLease(
+    sim: BridgeSimConnection,
+    focusState: BridgeSimUserFocusStateMessage,
+  ) {
+    const nextFocused = focusState.focused === true
+    const nextVisible =
+      typeof focusState.visible === 'boolean' ? focusState.visible : undefined
+    const nextVisibilityState =
+      typeof focusState.visibilityState === 'string'
+        ? focusState.visibilityState
+        : undefined
+    const nextDocumentFocused =
+      typeof focusState.documentFocused === 'boolean'
+        ? focusState.documentFocused
+        : undefined
+    if (
+      sim.userFocused === nextFocused &&
+      sim.userVisible === nextVisible &&
+      sim.visibilityState === nextVisibilityState &&
+      sim.documentFocused === nextDocumentFocused
+    ) {
+      return
+    }
+    sim.userFocused = nextFocused
+    sim.userVisible = nextVisible
+    sim.visibilityState = nextVisibilityState
+    sim.documentFocused = nextDocumentFocused
+    this.broadcastSimClientStates()
+  }
+
+  // called when the sim reports a real user interaction (pointerdown,
+  // keydown, wheel, touch). creates or refreshes a short `user-active` lease
+  // that keeps agent writes from trampling a user who is driving the sim.
+  // reads still pass through — shouldAcquireLease only blocks on writes.
+  private updateUserActivity(sim: BridgeSimConnection) {
+    const existing = this.getActiveLease(sim)
+    if (existing && existing.kind === 'cli') {
+      // a real cli lease wins — don't shadow an agent that's actively
+      // driving the sim with a user-active lease.
+      return
+    }
+    const now = Date.now()
+    const refreshed = now + SootSimBridgeHost.USER_ACTIVE_LEASE_TTL_MS
+    // if a longer user-active hold is already in effect (e.g. from an explicit
+    // boot), keep it — passive canvas interaction must not shorten it.
+    const expiresAt =
+      existing && existing.kind === 'user-active'
+        ? Math.max(existing.expiresAt, refreshed)
+        : refreshed
+    sim.cliLease = {
+      kind: 'user-active',
+      cliIdentityKey: '__user-active__',
+      cliLabel: 'active user',
+      expiresAt,
+    }
+    this.broadcastSimClientStates()
+  }
+
+  private ensureCliIdentityKey(ws: WebSocket): string {
+    const existing = this.cliIdentityKeyBySocket.get(ws)
+    if (existing) return existing
+    const fallback = `ws-${this.nextCliFallbackId++}`
+    this.cliIdentityKeyBySocket.set(ws, fallback)
+    return fallback
+  }
+
+  private getOpenSim(simId?: string): BridgeSimConnection | null {
+    if (simId) {
+      const sim = this.sims.get(simId)
+      if (sim?.ws.readyState === WebSocket.OPEN) return sim
+      return null
+    }
+    const primary = this.primarySimId != null ? this.sims.get(this.primarySimId) : null
+    if (primary?.ws.readyState === WebSocket.OPEN && primary.url) return primary
+    // prefer a sim that has actually reported a page over a bare-connected
+    // zombie — falling back to a url-less socket hands every default-target
+    // command to something that can't render or be driven (QA F19-2).
+    let pagelessFallback: BridgeSimConnection | null = null
+    for (const sim of this.sims.values()) {
+      if (sim.ws.readyState !== WebSocket.OPEN) continue
+      if (sim.url) return sim
+      pagelessFallback ??= sim
+    }
+    // a live primary with no url still beats nothing, and so does any other
+    // page-less open socket — only as the last resort.
+    if (primary?.ws.readyState === WebSocket.OPEN) return primary
+    return pagelessFallback
+  }
+
+  private async waitForSim(
+    simId?: string,
+    options: { attempts?: number; intervalMs?: number } = {},
+  ): Promise<BridgeSimConnection> {
+    const attempts = options.attempts ?? 10
+    const intervalMs = options.intervalMs ?? 200
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      const sim = this.getOpenSim(simId)
+      if (sim) return sim
+      await new Promise((resolve) => setTimeout(resolve, intervalMs))
+    }
+    throw new Error(simId ? `no sim connected with id ${simId}` : 'no sim connected')
+  }
+
+  private shouldPromoteSim(sim: BridgeSimConnection): boolean {
+    const current = this.primarySimId ? this.sims.get(this.primarySimId) : null
+    // a sim that has not yet reported a page (no `url`) is a bare WS
+    // connection — it can't render or be driven. promoting one makes it the
+    // default target and poisons every un-`--sim` command (QA F19-2): a
+    // zombie that connected from the dev shell but never sent
+    // `bridge:register` used to grab primary at connect-time and keep it
+    // for hours. only let a page-less sim be primary as a last resort when
+    // there is no current primary at all (transient — replaced as soon as a
+    // real page registers, via the re-election in `bridge:register`).
+    if (!sim.url) return !current
+    const currentAlive = current?.ws.readyState === WebSocket.OPEN
+    // a registered (url-bearing) sim always supersedes a dead or page-less
+    // primary; among live page-bearing sims the dev-shell (:5173) origin
+    // wins, matching the previous primary-candidate intent.
+    if (!current || !currentAlive || !current.url) return true
+    const isPrimaryCandidate = sim.origin?.includes(':5173')
+    const currentIsPrimary = current.origin?.includes(':5173')
+    return !!isPrimaryCandidate || !currentIsPrimary
+  }
+
+  private broadcastSimAssignments() {
+    for (const sim of this.sims.values()) {
+      if (sim.ws.readyState !== WebSocket.OPEN) continue
+      sim.ws.send(
+        JSON.stringify({
+          type: 'bridge:welcome',
+          simId: sim.id,
+          isPrimary: sim.id === this.primarySimId,
+        }),
+      )
+    }
+  }
+
+  private broadcastSimClientStates() {
+    for (const sim of this.sims.values()) {
+      if (sim.ws.readyState !== WebSocket.OPEN) continue
+      const lease = this.getActiveLease(sim)
+      const message: BridgeSimClientStateMessage = {
+        type: 'bridge:client-state',
+        attachedCliCount: this.getAttachedCliCount(sim.id),
+        activeAgentCommandCount: this.getActiveAgentCommandCount(sim.id),
+        recentActions: sim.recentActions,
+        lockedBy: lease ? lease.cliLabel || lease.cliIdentityKey : undefined,
+        lockedByKind: lease ? lease.kind : undefined,
+        lockExpiresAt: lease ? lease.expiresAt : undefined,
+        userFocused: sim.userFocused || undefined,
+        userVisible: sim.userVisible,
+        visibilityState: sim.visibilityState,
+        documentFocused: sim.documentFocused,
+      }
+      sim.ws.send(JSON.stringify(message))
+    }
+  }
+
+  private setCliSimTarget(ws: WebSocket, simId: string) {
+    const prevSimId = this.cliSimBySocket.get(ws)
+    if (prevSimId === simId) return
+    this.cliSimBySocket.set(ws, simId)
+    this.recordSimAction(simId, prevSimId ? 'cli switched sims' : 'cli connected', false)
+    this.broadcastSimClientStates()
+  }
+
+  private recordSimAction(
+    simId: string,
+    label: string | null | undefined,
+    broadcast = true,
+  ) {
+    const normalized = label?.trim()
+    if (!normalized) return
+    const sim = this.sims.get(simId)
+    if (!sim) return
+    const now = Date.now()
+    sim.lastActiveAt = now
+    sim.recentActions = [
+      { label: normalized, at: now },
+      ...sim.recentActions.filter((entry) => entry.label !== normalized),
+    ].slice(0, 4)
+    if (broadcast) this.broadcastSimClientStates()
+  }
+
+  private describeForwardedCommand(msg: any): string | null {
+    switch (msg?.type) {
+      case 'evaluate':
+        return 'evaluated page state'
+      case 'screenshot':
+        return 'captured screenshot'
+      case 'tap':
+        return 'sent tap event'
+      case 'keyboard':
+        return msg?.action === 'type' ? 'typed text' : 'used keyboard'
+      case 'tree':
+        return 'dumped tree'
+      case 'focus':
+        return 'focused sim'
+      case 'close':
+        return 'requested close'
+      default:
+        return typeof msg?.type === 'string' ? msg.type : null
+    }
+  }
+
+  // count distinct cli identity keys attached to a sim, not raw sockets.
+  // a single agent firing sequential cli commands opens a new ws per call —
+  // counting sockets would report phantom peers until idle cleanup catches up.
+  private getAttachedCliCount(simId: string): number {
+    const keys = new Set<string>()
+    for (const [ws, attachedSimId] of this.cliSimBySocket) {
+      if (attachedSimId !== simId) continue
+      if (ws.readyState !== WebSocket.OPEN) continue
+      const key = this.cliIdentityKeyBySocket.get(ws)
+      keys.add(key ?? `ws-unknown-${keys.size}`)
+    }
+    return keys.size
+  }
+
+  // count distinct identity keys attached to this sim other than `selfWs`.
+  // used to warn a cli that other agents/identities are also targeting the sim.
+  private getOtherCliIdentityCount(selfWs: WebSocket, simId: string): number {
+    const selfKey = this.cliIdentityKeyBySocket.get(selfWs)
+    const keys = new Set<string>()
+    for (const [ws, attachedSimId] of this.cliSimBySocket) {
+      if (attachedSimId !== simId) continue
+      if (ws.readyState !== WebSocket.OPEN) continue
+      const key = this.cliIdentityKeyBySocket.get(ws)
+      if (key && key === selfKey) continue
+      keys.add(key ?? `ws-unknown-${keys.size}`)
+    }
+    return keys.size
+  }
+
+  private getActiveAgentCommandCount(simId: string): number {
+    let count = 0
+    for (const pending of this.pendingCommands.values()) {
+      if (pending.simId === simId) count++
+    }
+    return count
+  }
+
+  private allocateSimId(): string {
+    for (;;) {
+      const id = this.nextSimNumber.toString(16)
+      this.nextSimNumber++
+      if (!this.sims.has(id) && !this.restorableSims.has(id)) return id
+    }
+  }
+
+  private tryRestoreSimId(
+    sim: BridgeSimConnection,
+    requestedId: string | undefined,
+  ): boolean {
+    const nextId = requestedId?.trim()
+    if (!nextId || nextId === sim.id) return false
+    const existing = this.sims.get(nextId)
+    if (existing && existing !== sim && existing.ws.readyState === WebSocket.OPEN) {
+      return false
+    }
+    const restorable = this.getRestorableSimState(nextId)
+
+    const prevId = sim.id
+    this.sims.delete(prevId)
+    sim.id = nextId
+    if (restorable) {
+      sim.recentActions = restorable.recentActions.map((entry) => ({ ...entry }))
+      sim.lastActiveAt = restorable.lastActiveAt
+      sim.cliLease = restorable.cliLease ? { ...restorable.cliLease } : undefined
+      this.restorableSims.delete(nextId)
+    }
+    this.sims.set(sim.id, sim)
+    if (this.primarySimId === prevId) {
+      this.primarySimId = sim.id
+    }
+    for (const [ws, attachedSimId] of this.cliSimBySocket) {
+      if (attachedSimId === prevId) {
+        this.cliSimBySocket.set(ws, sim.id)
+      }
+    }
+    return true
+  }
+
+  private rememberDisconnectedSim(sim: BridgeSimConnection) {
+    const lease = this.getActiveLease(sim)
+    this.restorableSims.set(sim.id, {
+      recentActions: sim.recentActions.map((entry) => ({ ...entry })),
+      lastActiveAt: sim.lastActiveAt,
+      cliLease: lease && lease.kind === 'cli' ? { ...lease } : undefined,
+      expiresAt: Date.now() + SootSimBridgeHost.SIM_RECONNECT_TTL_MS,
+    })
+    this.sims.delete(sim.id)
+  }
+
+  private getRestorableSimState(simId: string): BridgeRestorableSimState | null {
+    const snapshot = this.restorableSims.get(simId)
+    if (!snapshot) return null
+    if (snapshot.expiresAt <= Date.now()) {
+      this.restorableSims.delete(simId)
+      return null
+    }
+    if (snapshot.cliLease && snapshot.cliLease.expiresAt <= Date.now()) {
+      snapshot.cliLease = undefined
+    }
+    return snapshot
+  }
+
+  private sweepRestorableSims(now = Date.now()) {
+    for (const [simId, snapshot] of this.restorableSims) {
+      if (snapshot.expiresAt > now) continue
+      this.restorableSims.delete(simId)
+      for (const [cliWs, attachedSimId] of this.cliSimBySocket) {
+        if (attachedSimId === simId) {
+          this.cliSimBySocket.delete(cliWs)
+        }
+      }
+    }
+  }
+
+  private resetServerState() {
+    if (this.cliIdleTimer) {
+      clearInterval(this.cliIdleTimer)
+      this.cliIdleTimer = null
+    }
+    if (this.wsHeartbeatTimer) {
+      clearInterval(this.wsHeartbeatTimer)
+      this.wsHeartbeatTimer = null
+    }
+    if (this.runtimeUpdateTimer) {
+      clearInterval(this.runtimeUpdateTimer)
+      this.runtimeUpdateTimer = null
+    }
+    const wss = this.wss
+    const httpServer = this.httpServer
+    this.wss = null
+    this.httpServer = null
+    if (wss) {
+      try {
+        wss.close()
+      } catch {}
+    }
+    if (httpServer) {
+      try {
+        httpServer.close()
+      } catch {}
+    }
+  }
+}