Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

43.8 KB
Raw Blame
/**
 * Backend hub — web client terminating endpoint (`/api/web-ws`).
 *
 * Two auth modes share the path (the subprotocol carries the credential — browsers can't set WS headers):
 *
 *  - PER-USER (current): the subprotocol is the user's SSO access token → ONE socket per user.
 *    The socket starts UNATTACHED; the client scopes it with `machine_select {machineId}` (ownership-checked
 *    against `agentBinding.userId`, or shared with this account: lib/machineAccess.ts), which detaches the previous hub client and attaches a fresh one
 *    (new connId — keeps the (agent, connId) invariant that E2EE and reply-targeting rely on). While
 *    attached, frames flow exactly like the legacy mode (sendDown / up:{machineId} fan-out). The socket
 *    also live-watches ALL the user's agents and pushes `machines_status` frames (node_status transitions
 *    tagged with machineId) so the Machines list stays live without REST polling.
 *
 *  - LEGACY (fallback): the subprotocol is an agent apiKey → the socket is bound to that ONE agent for
 *    its whole life. Kept for stale tabs running the old bundle during a rolling deploy. Collision-safe:
 *    a 64-hex apiKey is recognized before any SSO profile request, so agent keys are never sent to
 *    the external identity service.
 */
import type { IncomingMessage } from 'http'
import { frameKind, markCpuKind } from './selfProfile.js'
import type { Duplex } from 'stream'
import { WebSocket, type RawData } from 'ws'
import { createWss, WS_LIMITS } from './wsServer.js'
import { extractKey } from '../utils/crypto.js'
import { machineIdFromKey } from '../utils/crypto.js'
import { prisma, machineAlive } from './prisma.js'
import { touchDeviceKey } from './deviceKeyLog.js'
import { getAgentPresence, getAgentPresenceMany, subscribeStatus, getDevicePresence, subscribeDeviceStatus, subscribeDeviceMachineListChanged, subscribeDeviceE2eePair, subscribeMachineShareChanged, type DeviceStatusMsg } from './bus.js'
import { sharedMachineAccess } from './machineAccess.js'
import { relayWebDocumentPushes } from './webAccountPushes.js'
import { DAEMONS } from '../config/env.js'
import { attachHubClient, trackSocketLiveness, type HubClient } from './hub.js'
import { authenticateAccessToken, SsoAuthError, type AuthUser } from './ssoAuth.js'
import type { Frame } from './tunnel.js'
import { machineOnline } from './providerLink.js'
import { logger } from '../utils/logger.js'
import { fireAndForget } from '../utils/async.js'
import { guardedSendJson } from './wsSend.js'
import { createOrderedInbox } from './orderedInbox.js'
import { ensureMachineReady, getMachineLifecycleStatus, type MachineLifecycleStatus } from './machineLifecycle.js'
import type { Machine } from '@prisma/client'
import { machineBillingAllowsDataPlane } from './billingState.js'
import { parseAutonomousEnvironment, storedAutonomousEnvironment } from './autonomousEnvironment.js'
import {
  isEncryptedTerminalFrame,
  TERMINAL_DOWN_TYPES,
  TERMINAL_ENVELOPE_MAX_BYTES,
  terminalFrameBytes,
  terminalFrameNeedsWake,
  TerminalRateGuard,
} from './terminalRelay.js'
import { parseTerminalClientFrame, TerminalBinaryKind, TERMINAL_BINARY_CLIENT_UP_KINDS } from './terminalBinary.js'
import {
  isEncryptedP2pFrame,
  P2P_DOWN_TYPES,
  P2P_SIGNAL_MAX_BYTES,
  p2pFrameBytes,
  P2pSignalRateGuard,
  terminalP2pPolicy,
} from './p2pSignaling.js'
import { presenceTracker, recordRemoteUsage, touchClientOnlineDay, type ClientBuild } from './dailyTracking.js'
import { declaredKind, trackSocket } from './wsAttribution.js'
import { isBackendOnlyDownType } from './backendOnlyFrames.js'

// How often an open mobile/web socket refreshes its person's `user_daily_client_presence` row.
const WEB_CLIENT_PRESENCE_WRITE_MS = 5 * 60_000

/** Down-frames only the backend may send — see lib/backendOnlyFrames.ts. Re-exported for existing callers. */
export { BACKEND_ONLY_DOWN_TYPES } from './backendOnlyFrames.js'

const wss = createWss(WS_LIMITS.web, { echoFirstProtocol: true })

/** Frame types the CPU self-profile may log by name; any other type a client sends is logged as `other`. */
const WEB_FRAME_TYPES: ReadonlySet<string> = new Set([...TERMINAL_DOWN_TYPES, ...P2P_DOWN_TYPES,
  'p2p_result', 'e2e_hello', 'machine_select', 'machine_deselect', 'machines_watch', 'devices_watch', 'message'])

// Device-status re-seed: covers the silent-offline case (worker crash → presence TTL 45s ages out
// with no transition published) — the watcher re-reads presence keys on this cadence.
const DEVICE_RESEED_MS = 30_000
/** How old the socket's own copy of the account's device bindings may get before a re-seed reads them again. A pair or a
 *  revoke is pushed and re-reads at once; this only bounds how long a push lost on the way leaves the copy wrong. Every
 *  socket used to read them every DEVICE_RESEED_MS (DB optimization roadmap, Phase 2 item 7). */
export const DEVICE_BINDINGS_REREAD_MS = 10 * 60_000
// Trailing debounce for list re-derivations poked by machines_watch (see scheduleWatchAgents).
const WATCH_DEBOUNCE_MS = 250
/** How long a relay refused for an offline machine waits before it selects that machine again: a daemon's relay
 *  re-dialled offline machines every few seconds, 68% of 1,884 selects in 10 minutes (prod, 2026-10-27, #314). The
 *  Desktop's own longest reconnect backoff, so a machine coming back is seen no later than it was. */
export const OFFLINE_RETRY_AFTER_MS = 30_000
/** Sockets that never read the account's feeds unless they ask: a daemon's relay, `harness
 *  link`'s one-shot socket and the apps' trust-group sync (`?client=`). Prod, 2026-10-29: about 121 connects a minute
 *  living a median 0.4 s, nearly all relays, each reading the account's machines and devices and subscribing five
 *  channels it never read (WebSocket roadmap Phase 1 item 4). A socket that declares nothing may be an older app. */
const ON_DEMAND_FEED_CLIENTS: ReadonlySet<string> = new Set(['relay', 'link', 'group-sync'])

/** Who is on the other end of a per-user socket, as the client declares it: the surface (`?client=`), and
 *  for the phone the release (`?release=`, the public x.y.z) and whether the build is a debug or simulator
 *  one (`?debug=1`). An app that predates the last two sends neither: no release, not a debug build. */
export function declaredClient(query: URLSearchParams): { surface: 'mobile' | 'web' | null; build: ClientBuild } {
  const declared = query.get('client')
  const surface = declared === 'mobile' || declared === 'web' ? declared : null
  return { surface, build: surface === 'mobile' ? { release: query.get('release'), debug: query.get('debug') === '1' } : {} }
}

/** Sends `frame` down once `wake` has made sure its machine runs, to the client still selected then. A deselect, another
 *  machine's select or the socket's close during the wait leaves no client for it, and the frame is dropped: it was meant
 *  for that machine (2026-10-28 prod: "Cannot read properties of null (reading 'sendDown')"). A failed wake sends nothing. */
export async function sendWhenAwake(selected: () => HubClient | null, wake: () => Promise<void>, frame: Frame): Promise<void> {
  const target = selected()
  if (!target) return
  await wake()
  if (selected() === target) target.sendDown(frame)
}

/** HTTP upgrade hook for `/api/web-ws`. Subprotocol = SSO access token or legacy agent apiKey. */
export function handleWebUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
  const cred = extractKey(req)
  if (!cred) { socket.destroy(); return }

  // LEGACY per-agent mode: classify the fixed 64-hex key first so it is never sent to SSO.
  if (/^[a-f0-9]{64}$/i.test(cred)) {
    const machineId = machineIdFromKey(cred)
    void (async () => {
      const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
      if (!binding || binding.deletedAt || !machineBillingAllowsDataPlane(binding)) { socket.destroy(); return }
      wss.handleUpgrade(req, socket, head, (ws) => attachWebClient(ws, machineId, declaredKind(new URL(req.url ?? '/', 'http://x').searchParams)))
    })().catch((err) => { logger.warn('web-ws legacy upgrade failed', { error: String(err) }); socket.destroy() })
    return
  }

  // PER-USER mode: profile validation is async, so authenticate before completing the upgrade.
  void (async () => {
    const query = new URL(req.url ?? '/api/web-ws', 'http://backend.local').searchParams
    try {
      const requestedEnvironment = parseAutonomousEnvironment(query.get('autonomousEnv'))
      // Who is on the other end, as the client declares it: the mobile app and the web viewer say so;
      // the daemon's relay (and any older client) says nothing and is never counted as a person.
      const { surface, build } = declaredClient(query)
      const declared = declaredKind(query)
      const user = await authenticateAccessToken(cred, requestedEnvironment)
      if (socket.destroyed) return
      wss.handleUpgrade(req, socket, head, (ws) => attachUserClient(ws, user, surface, build, declared))
    } catch (err) {
      if (socket.destroyed) return
      const invalid = err instanceof SsoAuthError && err.code === 'INVALID_TOKEN'
      const mismatch = err instanceof SsoAuthError &&
        (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')
      // A Mac's team account (lib/teamSession.ts) never selects or attaches to a machine here: refused for good,
      // not an expired sign-in to refresh and retry.
      const team = err instanceof SsoAuthError && err.code === 'TEAM_SESSION_LIMITED'
      if (invalid && query.get('auth') === 'http') {
        try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
        socket.destroy()
        return
      }
      const code = invalid ? 4401 : mismatch || team ? 4403 : 1013
      const reason = invalid
        ? 'auth expired'
        : mismatch
          ? `env:${err.requiredEnv ?? 'prod'}`
          : team ? 'team sign-in' : 'auth service unavailable'
      wss.handleUpgrade(req, socket, head, (ws) => { try { ws.close(code, reason) } catch { /* ignore */ } })
    }
  })().catch((err) => { logger.warn('web-ws upgrade failed', { error: String(err) }); socket.destroy() })
}

/** PER-USER socket: starts unattached; `machine_select` scopes it to one owned machine at a time. */
function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'web' | null, build: ClientBuild,
  declared: ReturnType<typeof declaredKind> = { client: 'unknown', version: null }): void {
  let client: HubClient | null = null
  let currentAgentId: string | null = null
  let currentBinding: Machine | null = null
  let closed = false
  // Monotonic guards: async lookups from two rapid selects (or watch refreshes) must not finish
  // out of order and leave the socket bound to the older target.
  let selectGen = 0
  let watchGen = 0
  const terminalRate = new TerminalRateGuard()
  const p2pSignalRate = new P2pSignalRateGuard()

  const send = (obj: unknown): boolean => guardedSendJson(ws, obj, 'must', { userId: user.sub })
  // Its connect and disconnect lines (lib/wsAttribution.ts): prod, 2026-10-28, 2,304 of 2,308 opens in 15 minutes
  // declared no client and lived a median 0.4 s, and these lines named only the user.
  const track = trackSocket('web', 'web user', ws, { ...declared, userId: user.sub })
  const refuse = (payload: { machineId: string; error: string; retryAfterMs?: number; reason?: 'deleted' }): void => {
    track.selected(payload.error)
    send({ type: 'machine_select_error', payload })
  }
  send({ type: 'connected', payload: { userId: user.sub } })

  // The desktop app never dials this socket — the local daemon does, one per FOREIGN machine it relays —
  // so it writes no `user_daily_presence` (that is the app's `app_presence` through adapter-ws,
  // lib/adapterWs.ts). The mobile app and the web viewer DO dial it themselves and declare it
  // (`?client=`): their person is counted in `user_daily_client_presence`, a session per socket, then
  // `lastSeenAt` every WEB_CLIENT_PRESENCE_WRITE_MS while it stays open (so it lags by at most that).
  let presenceTimer: ReturnType<typeof setInterval> | null = null
  if (surface) {
    const touchPresence = presenceTracker(
      (now, isNewConnection) => touchClientOnlineDay(user.sub, surface, now, { isNewConnection, build }),
      (kind, err) => logger.warn('client presence tracking failed', { userId: user.sub, surface, kind, error: String(err) }),
      { pingFloorMs: WEB_CLIENT_PRESENCE_WRITE_MS, openFloorMs: 0 },
    )
    touchPresence('open')
    presenceTimer = setInterval(() => touchPresence('ping'), WEB_CLIENT_PRESENCE_WRITE_MS)
  }

  // An unattached socket (user parked on the Machines page, no agent selected) holds no hub client, so a
  // registry-driven sweep can't see it — it would be killed by LB idle timeouts, or never reaped when
  // dead. This used to be a second heartbeat loop here, carefully disabled while attached so the two
  // sweeps couldn't race; the hub now tracks the socket itself, which is one sweep for both states.
  const releaseLiveness = trackSocketLiveness(ws, 'web')
  // A relay, a link or a group sync starts the feeds below only when it asks (ON_DEMAND_FEED_CLIENTS).
  const feedsOnDemand = ON_DEMAND_FEED_CLIENTS.has(declared.client)

  // ── Live Machines-list feed ──────────────────────────────────────────────────────────────────
  // Subscribe node_status for EVERY agent the user owns and forward it tagged with the machineId (the
  // raw node_status frame doesn't carry one). Re-armed via `machines_watch` (sent after create/delete).
  // The agent set is ALWAYS re-derived from the DB — the client never supplies it.
  const statusSubs = new Map<string, () => void>()
  const sendStatuses = (statuses: Array<{ machineId: string; online: boolean; status?: MachineLifecycleStatus; reason?: string }>): void => {
    if (ws.readyState !== WebSocket.OPEN || statuses.length === 0) return
    send({ type: 'machines_status', payload: { statuses } })
  }
  const watchAgents = async (): Promise<void> => {
    const gen = ++watchGen
    const bindings = await prisma.machine.findMany({
      where: { userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive },
      select: { machineId: true, billingStatus: true },
    })
    if (gen !== watchGen || closed) return // superseded / socket gone
    const wanted = new Set(bindings.filter(machineBillingAllowsDataPlane).map((b) => b.machineId))
    for (const [id, unsub] of statusSubs) {
      if (!wanted.has(id)) { unsub(); statusSubs.delete(id) } // agent deleted
    }
    for (const id of wanted) {
      if (statusSubs.has(id)) continue
      // `status:{machineId}` carries only node_status / machine_app_status transitions — not the
      // machine's whole turn stream, which is what subscribing `up:` here used to pull in for every
      // machine the user owns, whether or not anyone was looking at it.
      const unsub = await subscribeStatus(id, (frame) => {
        const f = frame as { type?: string; payload?: { online?: boolean; status?: MachineLifecycleStatus; reason?: string } }
        if (f?.type === 'node_status') {
          sendStatuses([{ machineId: id, online: f.payload?.online === true, ...(f.payload?.status ? { status: f.payload.status } : {}), ...(f.payload?.reason ? { reason: f.payload.reason } : {}) }])
        }
      })
      if (closed || gen !== watchGen) { unsub(); return } // raced a close / newer watch reconciles
      statusSubs.set(id, unsub)
    }
    // Seed the full current picture (presence keys = source of truth) so the list is right immediately.
    // One MGET for every presence key, not one GET per machine.
    const ids = [...wanted]
    const presence = await getAgentPresenceMany(ids)
    const statuses = await Promise.all(
      ids.map(async (id) => {
        // Same assertion as the per-agent seeds: a provider machine has no presence key and is always
        // online, so reading presence alone would list it as offline on the machine cards too.
        const online = await machineOnline(id, !!presence.get(id))
        const lifecycle = online ? 'running' : await getMachineLifecycleStatus(id)
        return { machineId: id, online, status: lifecycle === 'unknown' ? 'offline' as const : lifecycle }
      }),
    )
    if (gen === watchGen && !closed) sendStatuses(statuses)
  }
  // A machine create/rename/delete pokes every open tab of the user at once (`machines_changed` +
  // the client's `machines_watch` reply); several in a row (a bulk rename) must not re-derive the
  // list each time. Trailing debounce: the last poke wins, ≤250ms later.
  let watchAgentsTimer: NodeJS.Timeout | null = null
  const scheduleWatchAgents = (): void => {
    if (watchAgentsTimer) clearTimeout(watchAgentsTimer)
    watchAgentsTimer = setTimeout(() => {
      watchAgentsTimer = null
      if (closed) return
      void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))
    }, WATCH_DEBOUNCE_MS)
  }
  if (!feedsOnDemand) void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))

  // ── Live device-status feed (mirror of watchAgents; per-DEVICE statuses over one per-user sub) ──
  // Transitions ride the user-scoped `devstatus:{userId}` channel (deviceWs publishes on connect/
  // disconnect, deviceRevoke on a revoke). The socket keeps its own copy of the account's device bindings:
  // a revoke drops a device from it, and a report from a device it does not know (one paired after the copy
  // was read) reads the bindings again. The 30s re-seed covers the silent case — a worker holding a device
  // socket crashes, nobody publishes offline, the presence key just ages out (TTL 45s) — and reads only
  // presence; the bindings themselves are read again only after DEVICE_BINDINGS_REREAD_MS.
  const sendDeviceStatuses = (statuses: Array<{ deviceId: string; online: boolean; lastSeenAt?: string | null }>): void => {
    if (ws.readyState !== WebSocket.OPEN || statuses.length === 0) return
    send({ type: 'devices_status', payload: { statuses } })
  }
  let deviceStatusUnsub: (() => void) | null = null
  let deviceSeedTimer: NodeJS.Timeout | null = null
  // deviceId → its last seen time; null until the bindings were first read.
  let knownDevices: Map<string, string | null> | null = null
  let knownDevicesReadAt = 0
  let deviceBindingsRead: Promise<void> | null = null
  // Set by a change that lands while a read is in flight: that read may predate it, so another follows.
  let deviceBindingsStale = false
  const readDeviceBindings = (): Promise<void> => {
    deviceBindingsStale = true
    if (deviceBindingsRead) return deviceBindingsRead
    deviceBindingsRead = (async () => {
      try {
        while (deviceBindingsStale && !closed) {
          deviceBindingsStale = false
          const rows = await prisma.deviceBinding.findMany({ where: { userId: user.sub }, select: { deviceId: true, lastSeenAt: true } })
          if (deviceBindingsStale) continue
          knownDevices = new Map(rows.map((d) => [d.deviceId, d.lastSeenAt?.toISOString() ?? null]))
          knownDevicesReadAt = Date.now()
        }
      } finally {
        deviceBindingsRead = null
      }
    })()
    return deviceBindingsRead
  }
  const seedDeviceStatuses = async (): Promise<void> => {
    if (!knownDevices || Date.now() - knownDevicesReadAt >= DEVICE_BINDINGS_REREAD_MS) await readDeviceBindings()
    if (closed || !knownDevices) return
    const statuses = await Promise.all(
      [...knownDevices].map(async ([deviceId, lastSeenAt]) => ({ deviceId, online: await getDevicePresence(deviceId), lastSeenAt })),
    )
    if (!closed) sendDeviceStatuses(statuses)
  }
  const onDeviceStatus = (msg: DeviceStatusMsg): void => {
    if (msg.removed) {
      knownDevices?.delete(msg.deviceId)
      if (deviceBindingsRead) deviceBindingsStale = true
      return
    }
    if (knownDevices?.has(msg.deviceId)) {
      if (msg.lastSeenAt) knownDevices.set(msg.deviceId, msg.lastSeenAt)
    } else if (knownDevices || deviceBindingsRead) {
      // A device the copy does not hold, or a read under way that may predate it: read the bindings (again).
      void readDeviceBindings().catch((err) => logger.warn('web-ws device bindings read failed', { userId: user.sub, error: String(err) }))
    }
    sendDeviceStatuses([{ deviceId: msg.deviceId, online: msg.online === true, ...(msg.lastSeenAt ? { lastSeenAt: msg.lastSeenAt } : {}) }])
  }
  const watchDevices = async (): Promise<void> => {
    if (!deviceStatusUnsub) {
      deviceStatusUnsub = await subscribeDeviceStatus(user.sub, onDeviceStatus)
      if (closed) { deviceStatusUnsub(); deviceStatusUnsub = null; return }
    }
    if (!deviceSeedTimer) {
      deviceSeedTimer = setInterval(() => {
        void seedDeviceStatuses().catch(() => { /* ignore */ })
      }, DEVICE_RESEED_MS)
    }
    // Asked to watch (the first time, or again after the client paired or revoked one): read the bindings now.
    await readDeviceBindings()
    await seedDeviceStatuses()
  }
  if (!feedsOnDemand) void watchDevices().catch((err) => logger.warn('web-ws watchDevices failed', { userId: user.sub, error: String(err) }))

  // ── Live machine-LIST invalidation ─────────────────────────────────────────────────────────────
  // The `devmachines:{userId}` channel (despite the device-era name) is the per-user "machine list
  // changed" bus: create/delete/rename publish here from whatever worker served the REST call.
  // Forward it as `machines_changed` so every open tab re-fetches the list (names stay in sync
  // across tabs without F5). It also ends the socket when the account moves to another environment, so a socket whose
  // feeds wait to be asked for still hears it from the moment it holds a machine (bindAgent).
  let machineListUnsub: (() => void) | null = null
  let machineListWatched = false
  const watchMachineList = (): void => {
    if (machineListWatched) return
    machineListWatched = true
    void (async () => {
      machineListUnsub = await subscribeDeviceMachineListChanged(user.sub, (msg) => {
        if (ws.readyState !== WebSocket.OPEN) return
        if (msg.reason === 'environment_changed' && msg.autonomousEnv && msg.autonomousEnv !== user.autonomousEnv) {
          try { ws.close(4403, `env:${msg.autonomousEnv}`) } catch { /* ignore */ }
          return
        }
        send({ type: 'machines_changed', payload: { reason: msg.reason } })
      })
      if (closed) { machineListUnsub(); machineListUnsub = null }
    })().catch((err) => logger.warn('web-ws machine-list watch failed', { userId: user.sub, error: String(err) }))
  }
  if (!feedsOnDemand) watchMachineList()

  // ── The account's desk and zoo: changed somewhere ────────────────────────────────────────────
  // The same `desk:{userId}` and `zoo:{userId}` invalidations every adapter socket hears
  // (lib/adapterAccountPushes.ts), forwarded to the clients that have no daemon to relay them — the
  // phone. One frame carrying the revision each; see lib/webAccountPushes.ts.
  let documentsUnsub: (() => void) | null = null
  if (!feedsOnDemand) void (async () => {
    documentsUnsub = await relayWebDocumentPushes(user.sub, (frame) => {
      if (ws.readyState !== WebSocket.OPEN) return
      send(frame)
    }, { zoo: DAEMONS.on })
    if (closed) { documentsUnsub(); documentsUnsub = null }
  })().catch((err) => logger.warn('web-ws desk/zoo watch failed', { userId: user.sub, error: String(err) }))

  // ── User-level E2EE device-pair requests ─────────────────────────────────────────────────────
  // Not tied to current machine selection: any logged-in page can receive the notice, then the frontend
  // checks whether this browser already trusts the target machine before showing the global popup.
  let deviceE2eePairUnsub: (() => void) | null = null
  if (!feedsOnDemand) void (async () => {
    deviceE2eePairUnsub = await subscribeDeviceE2eePair(user.sub, (msg) => {
      if (ws.readyState !== WebSocket.OPEN) return
      const { kind, ...payload } = msg
      const type = kind === 'cleared' ? 'device_e2ee_pair_cleared' : 'device_e2ee_pair_pending'
      send({ type, payload })
    })
    if (closed) { deviceE2eePairUnsub(); deviceE2eePairUnsub = null }
  })().catch((err) => logger.warn('web-ws device-e2ee-pair watch failed', { userId: user.sub, error: String(err) }))

  // ── Agent selection ──────────────────────────────────────────────────────────────────────────
  const ack = (machineId: string): void => {
    track.selected('accepted')
    send({
      type: 'connected',
      payload: { machineId: machineId, p2p: terminalP2pPolicy(user.sub, machineId) },
    })
    // Authoritative node-liveness for the newly-scoped agent (same seed the legacy mode sends).
    fireAndForget((async () => {
      const mgr = await getAgentPresence(machineId)
      if (ws.readyState !== WebSocket.OPEN || currentAgentId !== machineId) return
      const online = await machineOnline(machineId, !!mgr)
      // An online machine is `running` whatever machine_nodes says: read only for one that is not.
      const lifecycle = online ? 'running' : await getMachineLifecycleStatus(machineId)
      if (ws.readyState !== WebSocket.OPEN || currentAgentId !== machineId) return
      send({ type: 'node_status', payload: { online, status: lifecycle === 'unknown' ? 'offline' : lifecycle } })
    })(), 'web-ws seed node_status', { userId: user.sub, machineId })
  }
  const bindAgent = async (machineIdRaw: unknown, refuseOffline: boolean): Promise<void> => {
    if (typeof machineIdRaw !== 'string' || !machineIdRaw) return
    const machineId = machineIdRaw
    const gen = ++selectGen
    const binding = await prisma.machine.findUnique({ where: { machineId: machineId } })
    if (closed || gen !== selectGen) return // superseded by a newer select
    // Another account's machine is selected only while it is shared with this one (lib/machineAccess.ts),
    // with the same rights as the owner's own; its daemon decides again whether to trust this account.
    let shareCheckFailed = false
    const shared = binding && !binding.deletedAt && binding.userId !== user.sub
      ? await sharedMachineAccess(user, binding).catch(() => { shareCheckFailed = true; return null }) : null
    if (closed || gen !== selectGen) return
    if (!binding || binding.deletedAt || (binding.userId !== user.sub && !shared)) {
      // About 45 an hour in prod said nothing more (2026-10-28): a machine removed since, or one no longer shared, is the
      // client's stale list; a failed share check is ours.
      const reason = !binding ? 'unknown' : binding.deletedAt ? 'deleted' : shareCheckFailed ? 'share_check_failed' : 'not_shared'
      logger.warn('machine_select rejected', { userId: user.sub, machineId, reason })
      // Only the person's own machine says it was deleted (a daemon then stops dialling it); anyone else's says nothing more.
      refuse({ machineId: machineId, error: 'NOT_YOUR_MACHINE', ...(binding?.deletedAt && binding.userId === user.sub ? { reason: 'deleted' as const } : {}) })
      return
    }
    if (storedAutonomousEnvironment(binding.autonomousEnv) !== user.autonomousEnv) {
      logger.warn('machine_select environment rejected', { userId: user.sub, machineId, autonomousEnv: user.autonomousEnv })
      refuse({ machineId: machineId, error: 'MACHINE_ENV_MISMATCH' })
      return
    }
    if (binding.billingStatus === 'pending') {
      refuse({ machineId: machineId, error: 'MACHINE_PAYMENT_PENDING' })
      return
    }
    if (binding.billingStatus === 'suspended') {
      refuse({ machineId: machineId, error: 'MACHINE_SUBSCRIPTION_REQUIRED' })
      return
    }
    try {
      await ensureMachineReady(binding)
    } catch (err) {
      if (!closed && gen === selectGen) {
        const code = err instanceof Error && 'code' in err ? String((err as { code?: unknown }).code) : 'MACHINE_START_FAILED'
        refuse({ machineId: machineId, error: code })
      }
      return
    }
    if (closed || gen !== selectGen) return
    // Idempotent same-agent re-select keeps the connId, but still passed through ensureMachineReady so
    // selecting a deliberately stopped machine wakes it before the readiness ack.
    if (client && machineId === currentAgentId) { currentBinding = binding; ack(machineId); return }
    // A daemon's relay (a socket that declares no phone or web client) cannot use an offline machine: it hung up on the
    // ack half a second later and dialled again, every daemon already out there included. Refused here instead, before
    // a hub client and an ack, in the machine_select_error every daemon already turns into a failed dial. A phone or
    // the web viewer waits attached for the machine to come back, as before.
    if ((refuseOffline || !surface) && !await machineOnline(machineId, !!await getAgentPresence(machineId))) {
      if (!closed && gen === selectGen) {
        refuse({ machineId, error: 'MACHINE_OFFLINE', retryAfterMs: OFFLINE_RETRY_AFTER_MS })
      }
      return
    }
    if (closed || gen !== selectGen) return
    client?.detach()
    // A guest never hears the machine's broadcasts, only what the machine addresses to it (lib/hub.ts).
    client = attachHubClient(ws, machineId, 'web', { guest: !!shared })
    currentAgentId = machineId
    currentBinding = binding
    watchShare(shared ? machineId : null)
    watchMachineList()
    logger.info('web user selected agent', { userId: user.sub, machineId, connId: client.connId, ...(shared ? { shared } : {}) })
    ack(machineId)
  }

  // A machine shared with this account stays selected while its sharing still lets it: the owner taking
  // the address off, turning the domain off or stopping, or this account removing it from its list, ends
  // the session at once on whichever instance holds it (bus `machine-share:<id>`).
  let shareUnsub: (() => void) | null = null
  let shareGen = 0
  const watchShare = (machineId: string | null): void => {
    const gen = ++shareGen
    shareUnsub?.()
    shareUnsub = null
    if (!machineId) return
    const recheck = async (): Promise<void> => {
      const binding = await prisma.machine.findUnique({ where: { machineId } })
      const still = binding && !binding.deletedAt ? await sharedMachineAccess(user, binding) : null
      if (still || closed || gen !== shareGen || currentAgentId !== machineId) return
      logger.info('shared machine session ended: sharing changed', { userId: user.sub, machineId })
      selectGen++
      client?.detach()
      client = null
      currentAgentId = null
      currentBinding = null
      refuse({ machineId, error: 'NOT_YOUR_MACHINE' })
      ws.close(4403, 'Sharing ended')
    }
    void subscribeMachineShareChanged(machineId, () => { void recheck().catch(() => { /* the next change asks again */ }) })
      .then((unsub) => { if (gen === shareGen && !closed) shareUnsub = unsub; else unsub() })
      .catch((err) => logger.warn('web-ws machine share watch failed', { userId: user.sub, machineId, error: String(err) }))
  }

  // Presence, remembered briefly. Every non-terminal frame used to cost one Redis GET on the hot path;
  // the key itself has a 30s TTL, so a 2s memory of "it was there" is well inside its own staleness.
  // Only a POSITIVE answer is cached — an absent key must keep triggering the wake path.
  const PRESENCE_MEMORY_MS = 2_000
  let presenceSeen: { machineId: string; at: number } | null = null
  const presentRecently = async (machineId: string): Promise<boolean> => {
    const now = Date.now()
    if (presenceSeen && presenceSeen.machineId === machineId && now - presenceSeen.at < PRESENCE_MEMORY_MS) return true
    const present = !!(await getAgentPresence(machineId))
    presenceSeen = present ? { machineId, at: now } : null
    return present
  }

  const handleFrame = async (frame: Frame): Promise<void> => {
    const type = frame.type as string | undefined
    // The backend's own control frames — `__`-prefixed, plus the named ones in lib/backendOnlyFrames.ts —
    // are never a web client's to send. Refused here, on the legacy key path and on device-ws alike; the
    // adapter also takes them only on the backend's own `connId: ''`, so each check stands on its own.
    if (isBackendOnlyDownType(type)) return
    // The key opening this E2EE session was seen now (lib/deviceKeyLog.ts, a hint for the Devices list).
    if (type === 'e2e_hello') touchDeviceKey(user.sub, (frame.payload as { identityPub?: unknown } | undefined)?.identityPub)
    const isTerminal = typeof type === 'string' && TERMINAL_DOWN_TYPES.has(type)
    const terminalNamespace = typeof type === 'string' && type.startsWith('terminal_')
    if (terminalNamespace && !isTerminal) {
      send({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_TYPE_REJECTED' } })
      return
    }
    if (isTerminal) {
      const bytes = terminalFrameBytes(frame)
      if (bytes > TERMINAL_ENVELOPE_MAX_BYTES || !isEncryptedTerminalFrame(frame) || !terminalRate.allow(type!, bytes)) {
        send({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_FRAME_REJECTED' } })
        return
      }
    }
    const p2pNamespace = typeof type === 'string' && type.startsWith('p2p_')
    const isP2pSignal = typeof type === 'string' && P2P_DOWN_TYPES.has(type)
    if (type === 'p2p_result') {
      const payload = (frame.payload ?? {}) as Record<string, unknown>
      const outcome = typeof payload.outcome === 'string' ? payload.outcome : ''
      const allowed = new Set(['direct', 'timeout', 'failed', 'dropped', 'relay'])
      if (client && currentBinding && allowed.has(outcome)) {
        const setupMs = Number(payload.setupMs)
        logger.info('terminal p2p result', {
          userId: user.sub,
          machineId: currentBinding.machineId,
          outcome,
          ...(Number.isFinite(setupMs) && setupMs >= 0 && setupMs <= 60_000 ? { setupMs: Math.round(setupMs) } : {}),
          ...(typeof payload.reason === 'string' ? { reason: payload.reason.slice(0, 64) } : {}),
        })
      }
      return
    }
    if (p2pNamespace && !isP2pSignal) {
      send({ type: 'p2p_transport_error', payload: { code: 'P2P_TYPE_REJECTED' } })
      return
    }
    if (isP2pSignal) {
      const bytes = p2pFrameBytes(frame)
      const policyEnabled = currentBinding
        ? terminalP2pPolicy(user.sub, currentBinding.machineId).enabled
        : false
      if (!policyEnabled || bytes > P2P_SIGNAL_MAX_BYTES
        || !isEncryptedP2pFrame(frame) || !p2pSignalRate.allow(bytes)) {
        send({ type: 'p2p_transport_error', payload: { code: 'P2P_SIGNAL_REJECTED' } })
        return
      }
      // Remote-usage signal: a p2p_offer actually starts a new p2p session (vs. the ICE/abort
      // frames that follow one), so it's the one point that means "used remote to stream terminal".
      if (type === 'p2p_offer' && currentBinding) {
        recordRemoteUsage(user.sub, currentBinding.machineId, new Date())
          .catch((err) => logger.warn('remote usage tracking failed', { userId: user.sub, machineId: currentBinding?.machineId, error: String(err) }))
      }
    }
    if (type === 'machine_select') {
      const payload = frame.payload as { machineId?: unknown; offline?: unknown } | undefined
      await bindAgent(payload?.machineId, payload?.offline === 'refuse')
      return
    }
    if (type === 'machine_deselect') {
      selectGen++ // cancel any in-flight bindAgent
      watchShare(null)
      client?.detach()
      client = null
      currentAgentId = null
      currentBinding = null
      return
    }
    if (type === 'machines_watch') {
      scheduleWatchAgents()
      return
    }
    if (type === 'devices_watch') {
      void watchDevices().catch(() => { /* logged above */ })
      return
    }
    if (client && currentBinding) {
      const binding = currentBinding
      // A selected machine can idle-stop while the tab remains open. Turn-producing messages always
      // refresh the wake lease; other frames wake only when presence says the node is down.
      try {
        await sendWhenAwake(() => client, async () => {
          if ((isTerminal && terminalFrameNeedsWake(type!)) || (!isTerminal && (type === 'message' || !(await presentRecently(binding.machineId))))) {
            await ensureMachineReady(binding)
          }
        }, frame)
      } catch (err) {
        const message = err instanceof Error ? err.message : 'Machine could not be started'
        send({ type: 'error', payload: { message } })
      }
      return
    }
    // No agent selected: fast-fail RPCs (echo the requestId) so wsClient.request doesn't burn its
    // 20s timeout; drop fire-and-forget frames.
    const requestId = (frame.payload as { requestId?: unknown } | undefined)?.requestId
    if (typeof requestId === 'string' && typeof type === 'string') {
      send({ type: `${type}_result`, payload: { requestId, error: 'NO_MACHINE_SELECTED' } })
    }
  }

  // STRICT in-order frame processing. `bindAgent` awaits a DB lookup; without this chain a frame
  // arriving in that gap (the web sends `agent_select` then its RPCs back-to-back) would be routed
  // by the PREVIOUS selection's client — an agent-switch could leak the old agent's projects/replies
  // into the new view, or lose the RPC entirely. The chain makes every frame wait for the frames
  // (incl. selects) before it, restoring the single-socket ordering guarantee end-to-end.
  // Bounded (see orderedInbox.ts): past the ceiling a frame is refused and answered right away.
  let lastOverflowLogAt = 0
  const inbox = createOrderedInbox<Frame>(
    handleFrame,
    (err, frame) => logger.warn('web-ws frame failed', { userId: user.sub, type: frame.type, error: String(err) }),
    (frame, inflight) => {
      const type = frame.type as string | undefined
      const requestId = (frame.payload as { requestId?: unknown } | undefined)?.requestId
      if (typeof requestId === 'string' && typeof type === 'string') {
        send({ type: `${type}_result`, payload: { requestId, error: 'INBOUND_OVERFLOW' } })
      } else {
        send({ type: 'error', payload: { code: 'INBOUND_OVERFLOW', message: 'too many frames in flight' } })
      }
      const now = Date.now()
      if (now - lastOverflowLogAt > 10_000) {
        lastOverflowLogAt = now
        logger.warn('web-ws inbound overflow — refusing frames', { userId: user.sub, machineId: currentAgentId ?? undefined, inflight, type })
      }
    },
  )
  ws.on('message', (raw: RawData, isBinary: boolean) => {
    if (isBinary) {
      const parsed = parseTerminalClientFrame(new Uint8Array(raw as Buffer))
      // A web/relay client only ever originates input, or a paste/imagePaste/pasteFile chunk —
      // output/keyframe/sync flow the other way. This gate is `parseTerminalClientFrame`'s own kind
      // check (which just validates wire shape and accepts every kind) plus that directionality —
      // paste/imagePaste/pasteFile were missing here even after being added to the kind enum and to
      // that parser, so every such frame was rejected as TERMINAL_BINARY_REJECTED, freezing the pane.
      const rateKey = parsed?.kind === TerminalBinaryKind.input ? 'terminal_input' : 'terminal_paste'
      if (!client || !currentBinding || !parsed || !TERMINAL_BINARY_CLIENT_UP_KINDS.has(parsed.kind)
        || !terminalRate.allow(rateKey, parsed.bytes.length)) {
        send({ type: 'terminal_transport_error', payload: { code: 'TERMINAL_BINARY_REJECTED' } })
        return
      }
      client.sendTerminalDown(parsed.bytes)
      return
    }
    let frame: Frame
    try { frame = JSON.parse(raw.toString()) as Frame } catch { return }
    markCpuKind(frameKind('web-ws', frame.type, WEB_FRAME_TYPES))
    inbox.enqueue(frame)
  })

  const cleanup = (): void => {
    if (closed) return
    closed = true
    releaseLiveness()
    if (presenceTimer) { clearInterval(presenceTimer); presenceTimer = null }
    client?.detach()
    client = null
    currentBinding = null
    watchShare(null)
    for (const [, unsub] of statusSubs) unsub()
    statusSubs.clear()
    if (watchAgentsTimer) { clearTimeout(watchAgentsTimer); watchAgentsTimer = null }
    if (deviceSeedTimer) { clearInterval(deviceSeedTimer); deviceSeedTimer = null }
    if (deviceStatusUnsub) { deviceStatusUnsub(); deviceStatusUnsub = null }
    if (machineListUnsub) { machineListUnsub(); machineListUnsub = null }
    if (deviceE2eePairUnsub) { deviceE2eePairUnsub(); deviceE2eePairUnsub = null }
    if (documentsUnsub) { documentsUnsub(); documentsUnsub = null }
  }
  // The line takes its code from the close: `ws` emits an error first on a broken socket, which has none (review of #2029).
  ws.on('close', (code: number, reason: Buffer) => { cleanup(); track.closed(code, reason?.toString(), { machineId: currentAgentId ?? undefined }) })
  ws.on('error', () => cleanup())
}

/** LEGACY per-agent socket (old bundle during rolling deploys): bound to one agent for life. */
function attachWebClient(ws: WebSocket, machineId: string, declared: ReturnType<typeof declaredKind>): void {
  const client = attachHubClient(ws, machineId, 'web')
  const terminalRate = new TerminalRateGuard()
  const send = (obj: unknown): boolean => guardedSendJson(ws, obj, 'must', { machineId, connId: client.connId })
  // Tracked like the per-user socket (lib/wsAttribution.ts); untracked, each one counted as refused (review of #2029).
  const track = trackSocket('web', 'web client (legacy)', ws, { ...declared, machineId, hubConnId: client.connId })
  ws.once('close', (code: number, reason?: Buffer) => track.closed(code, reason?.toString()))

  send({ type: 'connected', payload: { machineId: machineId } })

  // Authoritative node-liveness signal on connect (presence key = source of truth, set on register +
  // refreshed by the manager ping). Explicit BOTH ways so a client that connects while the node is
  // already up gets `online:true` immediately, not just inferred from the absence of an offline event.
  fireAndForget((async () => {
    const mgr = await getAgentPresence(machineId)
    const online = await machineOnline(machineId, !!mgr)
    if (ws.readyState === WebSocket.OPEN) {
      send({ type: 'node_status', payload: { online } })
    }
  })(), 'web-ws seed node_status (legacy)', { machineId })

  ws.on('message', (raw: RawData, isBinary: boolean) => {
    if (isBinary) {
      const parsed = parseTerminalClientFrame(new Uint8Array(raw as Buffer))
      // Same client-originated kinds as the current per-user handler above — see its comment.
      const rateKey = parsed?.kind === TerminalBinaryKind.input ? 'terminal_input' : 'terminal_paste'
      if (parsed && TERMINAL_BINARY_CLIENT_UP_KINDS.has(parsed.kind) && terminalRate.allow(rateKey, parsed.bytes.length)) {
        client.sendTerminalDown(parsed.bytes)
      }
      return
    }
    let frame: Frame
    try { frame = JSON.parse(raw.toString()) as Frame } catch { return }
    const type = frame.type as string | undefined
    markCpuKind(frameKind('web-ws', type, WEB_FRAME_TYPES))
    // The same backend-only refusal as the per-user path: a key holder is a client, not the backend.
    if (isBackendOnlyDownType(type)) return
    if (typeof type === 'string' && type.startsWith('terminal_') && !TERMINAL_DOWN_TYPES.has(type)) return
    if (typeof type === 'string' && TERMINAL_DOWN_TYPES.has(type)) {
      const bytes = terminalFrameBytes(frame)
      if (bytes > TERMINAL_ENVELOPE_MAX_BYTES || !isEncryptedTerminalFrame(frame) || !terminalRate.allow(type, bytes)) return
    }
    client.sendDown(frame)
  })

  let closed = false
  const cleanup = (): void => {
    if (closed) return // 'error' is followed by 'close': detach (and its __client_disconnected) only once
    closed = true
    client.detach()
  }
  ws.on('close', cleanup)
  ws.on('error', cleanup)
}