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.

41.6 KB
Raw Blame
/**
 * Backend hub — remote-machine adapter endpoint (`/api/adapter-ws`).
 *
 * A "remote" machine has no manager/agent-node: the user's own COMPUTER runs the machine-adapter CLI,
 * which dials in here and occupies the NODE side of the machineId — the same role a manager socket
 * plays for a docker node:
 *   - down:{machineId} (client chat/RPC)  → forwarded to the adapter socket
 *   - adapter `up` frames (normalized claude events + `<x>_result` RPC replies) → publishUp(machineId)
 *   - presence key machine:{machineId}:mgr = 'remote' while connected → drives web node_status
 *
 * Auth: the first WebSocket subprotocol is the user's SSO access token. The stable `computer` query
 * parameter selects (or creates) that user's Remote machine; a managed machine never gains a second
 * writer for its down:{machineId} channel.
 *
 * A team session (lib/teamSession.ts), a Mac's team account, connects only as its own computer's machine
 * and only while that row is a team machine. Its socket hears only the device-key pushes, never the
 * account's grid name, raises no pairing notice on the person's apps, and may take only its own key off
 * the device key log. A connect records which kind of sign-in serves the machine (`sessionKind`) when that changed.
 */
import type { Machine } from '@prisma/client'
import type { IncomingMessage } from 'http'
import type { Duplex } from 'stream'
import { WebSocket, type RawData } from 'ws'
import { createWss, upgradeStatusText, WS_LIMITS } from './wsServer.js'
import { prisma } from './prisma.js'
import {
  publishUp, claimMachineOwner, releaseMachineOwner, publishDeviceE2eePair,
  subscribeTerminalDown,
  setMachineAppState, clearMachineAppState, noteTuiPresence,
} from './bus.js'
import { deliverUpLocal, trackSocketLiveness } from './hub.js'
import { PROCESS_ID } from './registry.js'
import { guardedSend, guardedSendJson } from './wsSend.js'
import { trackSocket } from './wsAttribution.js'
import { attachNodeRole, PRESENCE_TTL_SEC } from './nodeRole.js'
import { machineConnectChanges, presenceStateFromRow, presenceTracker, presenceWriteDue, recordTurnStarted, touchClientOnlineDay, touchMachineOnlineDay, touchUserOnlineDay, TUI_SURFACES, type ClientSurface, type MachineConnectChanges, type PresenceWriteState } from './dailyTracking.js'
import { countryCodeFromHeaders } from './clientGeo.js'
import { recordCreatedAgent, recordDeletedAgent } from './agentTracker.js'
import type { Frame, UpBusMsg } from './tunnel.js'
import { logger } from '../utils/logger.js'
import { utcDayKey } from '../types/analytics.js'
import { machineBillingAllowsDataPlane } from './billingState.js'
import { normalizeComputerId } from './deviceAuth.js'
import { authenticateAccessToken, SsoAuthError } from './ssoAuth.js'
import { relayAccountPushes } from './adapterAccountPushes.js'
import { relaySwarmDeliveries } from './swarmDeliveryPushes.js'
import { relaySwarmHostChanges } from './swarmHostPushes.js'
import { DAEMONS } from '../config/env.js'
import { parseAutonomousEnvironment } from './autonomousEnvironment.js'
import { machineService } from '../services/MachineService.js'
import { appendDeviceKey } from './deviceKeyLog.js'
import { TEAM_CONVERTED_FRAME } from './teamSession.js'
import { AppError } from '../errors/index.js'
import {
  isEncryptedTerminalFrame,
  TERMINAL_ENVELOPE_MAX_BYTES,
  TERMINAL_UP_TYPES,
  terminalFrameBytes,
  TerminalRateGuard,
} from './terminalRelay.js'
import { decodeTerminalHop, TerminalBinaryKind, TerminalHopDirection } from './terminalBinary.js'
import {
  isEncryptedP2pFrame,
  P2P_SIGNAL_MAX_BYTES,
  P2P_UP_TYPES,
  p2pFrameBytes,
  P2pSignalRateGuard,
  terminalP2pPolicy,
} from './p2pSignaling.js'
import { ShortTurnGuard } from './shortTurnGuard.js'
import { markCpuKind } from './selfProfile.js'
import { createConnectionRoutes } from './terminalRoute.js'
import { recordRelay } from './relayStats.js'
import { computerSignedIn } from '../superTabs/computerMoves.js'

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

// machineId → the current adapter socket. One writer per machineId: down:{machineId} must have exactly
// one consumer, so a reconnecting adapter supersedes its predecessor (same as attachNode does).
const owners = new Map<string, WebSocket>()

/** Frames the adapter sends us. `up.frame` is opaque (ServerEvents / `<x>_result` replies /
 *  commander_event device cards). Eligibility is per-frame: web defaults true, commander defaults
 *  false — the adapter opts device frames in (mirrors the node's managerSocket.emitUp channels). */
type AdapterFrame =
  | { t: 'up'; frame: Frame; webEligible?: boolean; commanderEligible?: boolean; targetConnId?: string; userEligible?: boolean }
  | { t: 'ping' }

// Which desktop app a remote computer drives, and whether it is running. Sent as an `up` frame with
// BOTH eligibility flags false, so it reaches the per-machine subscribeUp watchers (deviceWs) without
// ever being fanned out to an attached client — no existing firmware can see an unknown frame type.
const APP_ENGINES = new Set(['cursor'])
const APP_STATES = new Set(['open', 'closed', 'missing'])

// `?v=` is self-declared by the client, so it is never persisted raw: anything outside a plain
// semver-ish token (or longer than 64 chars) is dropped rather than stored.
const CLIENT_VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/

// How often an OPEN adapter socket refreshes `machines.lastSeenAt`. Rides the node role's existing 15s
// heartbeat (plus every app ping) rather than a timer of its own — this is just the floor between two
// Mongo writes, so a machine that is up all day costs ~300 updates, not ~6000. The floor starts from the row's own
// stamp, so a connect stamps only when that is due too (#2676); a close at most once a minute (MACHINE_CLOSE_FLOOR_MS).
const MACHINE_PRESENCE_WRITE_MS = 5 * 60_000
// A close stamps the exact "offline since", unless the row was stamped less than this ago: a looping adapter reconnects every
// few seconds, and each close rewrote the row (task #3119, Ken's prod scan of 11-05: `Machine.update` by adapter-ws slow 31
// times at peak). Offline since is then at most this early.
const MACHINE_CLOSE_FLOOR_MS = 60_000

// Daily presence of the PERSON (`user_daily_presence`): the daemon reports its own loopback clients —
// `open` the moment a desktop window attaches, `ping` on its 15s app-ping tick while one stays, at
// most once a minute (cli backendSocket sendAppPresence) — and this is the floor between two Mongo
// writes for the `ping` kind. `open` always writes — it is what `connections` counts. The web-ws upgrade
// used to be the source, but the desktop app never dials web-ws directly (only the daemon does, and
// only to relay a foreign machine), so a single-machine user was invisible there.
const USER_PRESENCE_WRITE_MS = 5 * 60_000
// `open` is not floored by the interval above (each one IS a session), but it is floored on its own:
// the window reconnects its local socket a few times a minute at worst during a daemon restart, and
// an adapter sending more than that is looping or lying — either way not a session per frame, and
// not a Mongo upsert per frame.
const USER_PRESENCE_OPEN_MS = 10_000
const APP_PRESENCE_KINDS = new Set(['open', 'ping'])

// `turn_started` tap (agent/machine daily presence). `agentId` is a plain token the CLI derives from
// its registry (a UUID, or the engine's own session id as fallback), so it is bounded and
// character-restricted before it becomes a Mongo index key — an oversized or exotic value would
// otherwise either fail the unique index (>1024-byte key) or let a misbehaving adapter mint an
// unbounded number of `agent_daily_presence` rows. The per-minute cap is the same idea for volume:
// a real turn is human-paced (a handful a minute across every agent on one machine), so anything
// past this is a bug or abuse and is dropped, never written.
const TURN_AGENT_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/
const TURN_WRITES_PER_MINUTE = 120

function sanitizeClientVersion(raw: string | null): string | undefined {
  const v = raw?.trim()
  return v && CLIENT_VERSION_RE.test(v) ? v : undefined
}

/** Adapter authentication is SSO-only: accept precisely the first WS subprotocol, never x-api-key. */
function accessTokenFromProtocol(req: IncomingMessage): string | undefined {
  const raw = req.headers['sec-websocket-protocol']
  const first = (Array.isArray(raw) ? raw[0] : raw)?.split(',')[0]?.trim()
  return first || undefined
}

/** Fastify/http upgrade hook for `/api/adapter-ws`. Auth = user SSO access token. */
export function handleAdapterUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
  // Reject with an explicit HTTP 401 (not a silent destroy) so the adapter's ws client surfaces
  // "Unexpected server response: 401" — which it treats as a FATAL deauthorization (deleted/unknown
  // machine) and clears its saved token, instead of an ambiguous close-1006 it would retry forever.
  const deny = (): void => {
    try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
    socket.destroy()
  }
  // One computer per machine: when a DIFFERENT computer already holds this machine, reject with an
  // explicit HTTP 409 (not 401 — the adapter treats 401/403 as deauth and would WIPE its valid token).
  // The adapter surfaces 409 as an info message ("already connected from another computer") and stops.
  const denyBusy = (): void => {
    try { socket.write('HTTP/1.1 409 Conflict\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
    socket.destroy()
  }
  // Billing suspension is retryable: unlike 401/403, the adapter must retain its token so it can
  // reconnect automatically after the owner renews or re-subscribes.
  const denyPayment = (): void => {
    try { socket.write('HTTP/1.1 402 Payment Required\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
    socket.destroy()
  }
  const accessToken = accessTokenFromProtocol(req)
  if (!accessToken) { deny(); return }
  // The adapter sends its computer's hostname as `?label=`, a stable `?computer=` id, its version,
  // and the selected Autonomous environment. `computer` is required: without it the backend has no
  // safe way to choose between a user's Remote machines.
  let label: string | undefined
  let computerId: string | undefined
  let clientVersion: string | undefined
  let claimedMachineId: string | undefined
  let autonomousEnv: 'prod' | 'stag' = 'prod'
  try {
    const params = new URL(req.url ?? '', 'http://x').searchParams
    label = params.get('label') || undefined
    computerId = normalizeComputerId(params.get('computer') ?? '') ?? undefined
    // The machine id this daemon still believes it is. Optional: a freshly logged-in CLI has none
    // yet. When present it lets `resolveOrCreateForComputer` tell a REVOKED daemon apart from a
    // first-time pairing, instead of silently minting it a replacement machine.
    claimedMachineId = params.get('machine') || undefined
    clientVersion = sanitizeClientVersion(params.get('v'))
    autonomousEnv = parseAutonomousEnvironment(params.get('autonomousEnv'))
  } catch { deny(); return }
  if (!computerId) { deny(); return }
  // Where this computer is, per Cloudflare (absent off-Cloudflare). Read once here, at the only point
  // that still has the upgrade request, and carried into the machine row + its daily presence.
  const countryCode = countryCodeFromHeaders(req.headers)
  const forbid = (): void => {
    try { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
    socket.destroy()
  }
  void (async () => {
    let user
    // A team session is taken here only as the machine of the computer it is bound to (below).
    try { user = await authenticateAccessToken(accessToken, autonomousEnv, { allowHarnessSession: 'computer', allowTeamSession: true }) } catch (err) {
      if (err instanceof SsoAuthError && (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
        forbid()
        return
      }
      deny()
      return
    }
    const team = user.harnessSessionKind === 'team'
    // Never another machine of the account: a team session names its own computer, or nothing is looked up at all.
    if (team && computerId !== user.harnessComputerId) { forbid(); return }
    let machine
    if (team) {
      machine = (await machineService.resolveForTeamComputer(user, computerId, label ?? 'computer', claimedMachineId)).machine
    } else {
      machine = (await machineService.resolveOrCreateForComputer(user.sub, user.autonomousEnv, computerId, label ?? 'computer', claimedMachineId, 'computer')).machine
      // Before it attaches: a former team machine now served by a normal sign-in must not be read as a team machine. Any
      // other row is stamped by the connect's own update below; until then it is not a team machine either.
      if (machine.sessionKind === 'team') {
        await prisma.machine.update({ where: { machineId: machine.machineId }, data: { sessionKind: 'computer' } })
        machine = { ...machine, sessionKind: 'computer' }
      }
    }
    const machineId = machine.machineId
    if (!machineBillingAllowsDataPlane(machine)) { denyPayment(); return }
    // Single-computer claim BEFORE upgrade/attach, so a rejected second computer never supersedes the first.
    if (!(await claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC))) { denyBusy(); return }
    const row = machine
    wss.handleUpgrade(req, socket, head, (ws) => void attachAdapter(ws, row, label, computerId, clientVersion, countryCode, user.harnessSessionId, team))
    // A computer is signed in as one account at a time: Swarm entries of the account signed in here before move to this one
    // (superTabs/computerMoves.ts, #3122). Never awaited: the connect does not wait on Swarms.
    if (!team) {
      void computerSignedIn({ machineId, ownerId: user.sub, computerId, autonomousEnv: user.autonomousEnv })
        .catch(error => logger.warn('[swarm] computer move failed', { machineId, error: String(error) }))
    }
  })().catch((err) => {
    if (err instanceof AppError) {
      // 403 is the revoked-machine answer from `resolveOrCreateForComputer`, 429 its new-id rate limit
      // (the CLI retries it with backoff and keeps its token); the CLI keys off the numeric status, but
      // sending it under the wrong reason phrase would mislead anyone reading a capture or a proxy log.
      try { socket.write(`HTTP/1.1 ${err.statusCode} ${upgradeStatusText(err.statusCode)}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`) } catch { /* ignore */ }
      socket.destroy()
      return
    }
    logger.warn('adapter-ws upgrade failed', { error: String(err) })
    socket.destroy()
  })
}

/** The machine row as the upgrade read it: a connect writes only the facts that differ from it, and stamps only when its
 *  `lastSeenAt` is due. */
type AttachedMachine = Pick<Machine, 'machineId' | 'userId' | 'name' | 'hostname' | 'clientVersion' | 'computerId' | 'countryCode' | 'sessionKind' | 'lastSeenAt'>

async function attachAdapter(ws: WebSocket, machine: AttachedMachine, label?: string, computerId?: string, clientVersion?: string, countryCode?: string, harnessSessionId?: string, team = false): Promise<void> {
  const { machineId, userId, name: currentName } = machine
  // A different computer was already rejected at the upgrade (denyBusy), so this only closes our OWN
  // stale local socket on a same-computer reconnect landing on this worker.
  owners.get(machineId)?.close(4000, 'superseded')
  owners.set(machineId, ws)
  const send = (obj: unknown): boolean => guardedSendJson(ws, obj, 'must', { machineId, kind: 'adapter' })
  // Its connect and disconnect lines (lib/wsAttribution.ts): 227 adapter reconnects in 45 minutes in prod (2026-10-28)
  // could not be explained without the close codes.
  const track = trackSocket('adapter', 'adapter', ws, { client: 'daemon', version: clientVersion ?? null, machineId, computer: label })
  ws.once('close', (code: number, reason?: Buffer) => track.closed(code, reason?.toString()))
  send({ t: 'connected', machineId })
  // What changed for the ACCOUNT on some worker (its tabs, its machine list): this computer's app
  // re-reads through its daemon rather than polling for it. See adapterAccountPushes.ts.
  // A team machine reads none of the account's desk, zoo, machines or connections: it hears only the device-key pushes.
  const accountPushesUnsub = await relayAccountPushes(userId, send, { zoo: DAEMONS.on, team })
  // Work waiting for this machine's Swarm agents, team machine or not: its host reads it at once (swarmDeliveryPushes.ts).
  const swarmPushesUnsub = await relaySwarmDeliveries(machineId, send)
  // A commit that changed what this machine's host reads: it reads its Swarm changes at once (swarmHostPushes.ts, WS Phase 2a).
  const swarmHostUnsub = await relaySwarmHostChanges(machineId, send)

  // Last desktop-app state THIS socket asserted. Socket-scoped on purpose: a new adapter connection
  // starts with no claim and must re-assert, so a fresh value can never renew a stale one.
  let appState: { engine: string; state: string } | undefined
  const terminalRate = new TerminalRateGuard()
  // Fixed one-minute window for the `turn_started` tap — two integers, no timer, no allocation.
  let turnWindowStart = 0
  let turnWindowCount = 0
  const allowTurnWrite = (nowMs: number): boolean => {
    if (nowMs - turnWindowStart >= 60_000) { turnWindowStart = nowMs; turnWindowCount = 0 }
    return ++turnWindowCount <= TURN_WRITES_PER_MINUTE
  }
  const shortTurns = new ShortTurnGuard()
  const p2pSignalRate = new P2pSignalRateGuard()
  // A machine appends its own key once per sign-in, a removal when someone asks for one: a few a minute
  // is generous, and it keeps a looping daemon from rebuilding the log on every frame.
  const devlogRate = { windowStart: 0, count: 0, allow(): boolean {
    const now = Date.now()
    if (now - this.windowStart >= 60_000) { this.windowStart = now; this.count = 0 }
    return ++this.count <= 10
  } }

  // Buffer messages from RIGHT NOW, because the real handler cannot be installed until after the
  // `await attachNodeRole(...)` below — and `ws` drops any message emitted with no listener attached.
  // An adapter that (reasonably) sends as soon as its socket opens therefore lost its FIRST frame,
  // every time. That was invisible for a long while because the CLI's first frame is a resend-on-tick,
  // so it just looked like a one-tick delay; an adapter whose first frame is one-shot state lost it
  // outright. Buffer, then replay in order once the handler exists.
  const preHandlerQueue: Array<[RawData, boolean]> = []
  let onMessage: ((raw: RawData, isBinary: boolean) => void) | null = null
  ws.on('message', (raw: RawData, isBinary: boolean) => {
    markCpuKind(isBinary ? 'adapter-ws binary' : 'adapter-ws text')
    if (onMessage) onMessage(raw, isBinary)
    else if (preHandlerQueue.length < 64) preHandlerQueue.push([raw, isBinary])
  })

  // Two separate fields, deliberately: `hostname` tracks whichever computer connected LAST, while
  // `name` is the user-editable display name and is only ever SEEDED here — a connect must never
  // clobber a name the owner set. Best-effort; never blocks the connection.
  const seededName = !currentName?.trim() && label ? label.slice(0, 120) : null
  // Normalized on the way to Mongo so this column matches what the device-auth grant stamps — the
  // reuse lookup is an equality match on it. The RAW `computerId` keeps driving the Redis owner claim
  // (see the upgrade handler): that key is a self-consistent liveness token nothing joins against, and
  // re-keying it would 409 every already-connected adapter until its old claim aged out.
  const boundComputer = computerId ? normalizeComputerId(computerId) : null
  // Each overwrite-every-connect fact (`hostname`, `clientVersion`, `computerId`, `countryCode`: absent from an old client
  // or off Cloudflare leaves the last value), the seeded name, and which kind of sign-in serves the machine now
  // (lib/teamSession.ts; a team row was checked, and a former team row flipped, before the socket attached). Only the ones
  // that differ from the row are written, in the connect's one update with its stamp (touchMachinePresence below): a
  // reconnect used to rewrite them all and stamp separately, two updates of one row at once (#2676).
  const connectChanges = machineConnectChanges(machine, {
    hostname: label?.slice(0, 120), name: seededName ?? undefined, clientVersion, computerId: boundComputer ?? undefined, countryCode,
    sessionKind: team ? 'team' : 'computer',
  })
  // Tell the adapter its machine's display name (it mirrors it locally for `harness status`); null when
  // unnamed so a stale mirror clears. Renames while connected arrive the same way (machine_meta).
  // The account's private harness grid, carried on the frame the adapter already gets on connect.
  // Minted and remembered by `routes/grid.ts`; read-only here. A user who has never signed in since
  // the route shipped simply has none yet, and the daemon treats that as "no grid" rather than an
  // error — the next `harness login` mints it.
  // Never on a team machine (lib/teamSession.ts): the grid is the person's inference endpoint, not teammates'.
  const gridName = team ? null : (await prisma.user.findUnique({ where: { id: userId }, select: { gridName: true } })
    .catch(() => null))?.gridName ?? null
  send({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: currentName?.trim() || seededName, gridName } } })

  // The machine's last-seen stamp (plus the fleet's connect total), mirroring the user/device variants in
  // webWs/deviceWs. The guard only advances on a SUCCESSFUL write, so a transient DB failure is retried on the next
  // heartbeat instead of being silently skipped until the interval elapses again. Heartbeats also
  // skip while a write is still in flight: `onHeartbeat` fires from two 15s sources (node role
  // interval + app ping), and before the connect write lands `presenceWriteDue` would say "due" —
  // without this a slow Mongo gets a second concurrent upsert precisely when it is already slow.
  // The floor starts from the row's own stamp, not from this socket: a reconnect a minute after the last stamp neither
  // stamps on connect nor on its first heartbeat (#2676). A close stamps the "offline since" unless the row was stamped less
  // than MACHINE_CLOSE_FLOOR_MS ago.
  const lastMachinePresence: PresenceWriteState = presenceStateFromRow(machine.lastSeenAt)
  let machinePresenceInFlight = false
  // The connect's changed facts until a write carries them: a failed connect write is retried by the next heartbeat.
  let pendingChanges: MachineConnectChanges = {}
  const touchMachinePresence = (kind: 'connect' | 'heartbeat' | 'close', changes?: MachineConnectChanges): void => {
    const now = new Date()
    if (changes) pendingChanges = changes
    const carried = pendingChanges
    const due = kind === 'close' ? presenceWriteDue(lastMachinePresence, now, MACHINE_CLOSE_FLOOR_MS)
      : presenceWriteDue(lastMachinePresence, now, MACHINE_PRESENCE_WRITE_MS)
    if (kind === 'heartbeat' && machinePresenceInFlight) return
    if (kind !== 'connect' && !due && !Object.keys(carried).length) return
    const stamp = due
    machinePresenceInFlight = true
    touchMachineOnlineDay(userId, machineId, now, { isNewConnection: kind === 'connect', countryCode, changes: carried, stamp })
      .then(() => {
        if (pendingChanges === carried) pendingChanges = {}
        if (stamp) { lastMachinePresence.dayKey = utcDayKey(now); lastMachinePresence.wroteAt = now.getTime() }
      })
      .catch((err) => logger.warn('machine presence tracking failed', { machineId, kind, error: String(err) }))
      .finally(() => { machinePresenceInFlight = false })
  }
  // Same shape for the person behind the app: `open` bypasses the interval the way `connect` does
  // above, `ping` is rate-floored. `userId` is the machine's owner — the only person a desktop app
  // on this computer can be signed in as. The row is keyed by THIS machine too, so the same person
  // on a second computer lands in a second row rather than in this one.
  const userPresenceFloors = { pingFloorMs: USER_PRESENCE_WRITE_MS, openFloorMs: USER_PRESENCE_OPEN_MS }
  const touchUserPresence = presenceTracker(
    (now, isNewConnection) => touchUserOnlineDay(userId, machineId, now, { isNewConnection }),
    (kind, err) => logger.warn('user presence tracking failed', { machineId, userId, kind, error: String(err) }),
    userPresenceFloors,
  )
  // `harness tui` on this computer: the daemon reports it like a window but names the surface, and it
  // is kept out of the desktop app's table (`user_daily_client_presence`, schema.prisma).
  // One tracker per surface it reports (TUI_SURFACES): each is its own row and its own write floor.
  const tuiTrackers = new Map<ClientSurface, ReturnType<typeof presenceTracker>>()
  const touchTuiPresence = (surface: ClientSurface, kind: 'open' | 'ping') => {
    let track = tuiTrackers.get(surface)
    if (!track) {
      track = presenceTracker(
        (now, isNewConnection) => touchClientOnlineDay(userId, surface, now, { isNewConnection }),
        (k, err) => logger.warn('tui presence tracking failed', { machineId, userId, surface, kind: k, error: String(err) }),
        userPresenceFloors,
      )
      tuiTrackers.set(surface, track)
    }
    track(kind)
  }

  // The node role — down subscription, presence, `__clients` resync, node_status — is shared with
  // every other backer of a machine and lives in nodeRole.ts. Only the delivery and teardown are
  // adapter-specific, so only those are passed in.
  const role = await attachNodeRole({
    machineId,
    owner: 'remote',
    offlineReason: 'remote computer offline',
    deliver: (msg) => {
      if (ws.readyState !== WebSocket.OPEN) return
      // Its computer just turned itself into a team machine (lib/harnessSession.ts): a socket still connected under the
      // old sign-in must not keep serving a machine marked `team`. Backend-only (`__`), never forwarded.
      if ((msg.frame as { type?: string } | undefined)?.type === TEAM_CONVERTED_FRAME) {
        if (!team) { try { ws.close(4009, 'now a team machine') } catch { /* ignore */ } }
        return
      }
      send({ t: 'down', connId: msg.connId, frame: msg.frame })
      // `machine_revoked` used to be pushed and nothing more, leaving the socket open and the machine
      // still serving if the client ignored it — an old CLI, a dropped frame. Close it ourselves right
      // after the send so revocation does not depend on the client cooperating. Same shape as
      // onBillingSuspended below; the close must happen HERE rather than in MachineService because the
      // socket may live on another backend instance, reachable only through the Redis fan-out.
      if ((msg.frame as { type?: string } | undefined)?.type === 'machine_revoked') {
        try { ws.close(4004, 'machine revoked') } catch { /* ignore */ }
      }
    },
    onBillingSuspended: () => {
      // Close the live machine session WITHOUT revoking its saved token: the adapter's normal retry
      // loop then receives HTTP 402 until billing is restored, and reconnects by itself afterwards.
      try { ws.close(4003, 'subscription required') } catch { /* ignore */ }
    },
    onHeartbeat: () => {
      if (computerId) void claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC) // renew the one-computer claim
      // Same tick renews the app-state key, so it shares presence's TTL and can never outlive it.
      if (appState) void setMachineAppState(machineId, appState.engine, appState.state, PRESENCE_TTL_SEC)
      touchMachinePresence('heartbeat') // throttled inside — see MACHINE_PRESENCE_WRITE_MS
    },
  })
  touchMachinePresence('connect', connectChanges)
  const terminalDownUnsub = await subscribeTerminalDown(machineId, (packet) => {
    // Terminal input toward the adapter is 'must': dropping keystrokes is not recoverable client-side.
    guardedSend(ws, packet, 'must', { machineId, kind: 'adapter' })
  })

  // Liveness. The previous implementation pinged every 25 s and terminated on a single missed PONG —
  // and counted pongs only, so an adapter that was actively sending application traffic could still
  // be killed if one pong went missing. `trackSocketLiveness` counts message/ping/pong against a time
  // deadline instead, which is the same fix already applied to the hub's own sockets.
  const releaseLiveness = trackSocketLiveness(ws, 'adapter')

  // Frames for one viewer go straight to it when it is on this process, else to the process holding it
  // (lib/terminalRoute.ts); a connection keeps the route its first frame took for this socket's life.
  const routes = createConnectionRoutes(machineId)
  // A frame for one connection takes its route; a target that is not a plausible connection id (the daemon sets it) is
  // published as before, never used as a route or Redis key.
  const sendTargeted = (msg: UpBusMsg & { targetConnId: unknown }): void => {
    const target = msg.targetConnId
    if (typeof target === 'string' && target.length > 0 && target.length <= 128) routes.targeted({ ...msg, targetConnId: target })
    else void publishUp(machineId, msg as UpBusMsg)
  }

  onMessage = (raw: RawData, isBinary: boolean): void => {
    if (isBinary) {
      const hop = decodeTerminalHop(new Uint8Array(raw as Buffer))
      if (!hop || hop.direction !== TerminalHopDirection.up
        || (hop.kind !== TerminalBinaryKind.output && hop.kind !== TerminalBinaryKind.keyframe
          && hop.kind !== TerminalBinaryKind.sync)
        || !terminalRate.allow(
          hop.kind === TerminalBinaryKind.output
            ? 'terminal_output'
            : hop.kind === TerminalBinaryKind.keyframe ? 'terminal_keyframe' : 'terminal_sync',
          hop.clientFrame.length,
        )) return
      routes.hop(Buffer.from(raw as Buffer), hop.connId)
      return
    }
    let env: AdapterFrame
    try { env = JSON.parse(raw.toString()) as AdapterFrame } catch { return }
    if (env.t === 'ping') {
      role.touch() // refreshes presence and renews the machine claim
      return
    }
    if (env.t === 'up' && env.frame) {
      const terminalType = env.frame.type as string | undefined
      if (typeof terminalType === 'string' && terminalType.startsWith('terminal_')) {
        if (!TERMINAL_UP_TYPES.has(terminalType)) return
        const bytes = terminalFrameBytes(env.frame)
        if (!env.targetConnId || bytes > TERMINAL_ENVELOPE_MAX_BYTES
          || !isEncryptedTerminalFrame(env.frame) || !terminalRate.allow(terminalType, bytes)) return
        sendTargeted({
          webEligible: true,
          commanderEligible: false,
          targetConnId: env.targetConnId,
          targetKind: 'web',
          frame: env.frame,
        })
        return
      }
      if (typeof terminalType === 'string' && terminalType.startsWith('p2p_')) {
        const bytes = p2pFrameBytes(env.frame)
        if (!P2P_UP_TYPES.has(terminalType) || !env.targetConnId
          || !terminalP2pPolicy(userId, machineId).enabled
          || bytes > P2P_SIGNAL_MAX_BYTES || !isEncryptedP2pFrame(env.frame)
          || !p2pSignalRate.allow(bytes)) return
        sendTargeted({
          webEligible: true,
          commanderEligible: false,
          targetConnId: env.targetConnId,
          targetKind: 'web',
          frame: env.frame,
        })
        return
      }
      // Desktop-app presence. Handled in full here and NEVER falls through to the generic publish:
      // the eligibility flags are forced false locally rather than trusted from the frame, so no
      // adapter can fan an unknown frame type out to web clients or devices. Validated against a
      // closed vocabulary so an arbitrary string can never reach the enum the firmware parses.
      // Unchanged values are suppressed (the heartbeat keeps the TTL alive), which caps a chatty
      // adapter at the heartbeat rate.
      const app = env.frame as { type?: string; payload?: { engine?: unknown; state?: unknown } }
      if (app.type === 'machine_app_status') {
        const engine = typeof app.payload?.engine === 'string' ? app.payload.engine : ''
        const state = typeof app.payload?.state === 'string' ? app.payload.state : ''
        if (!APP_ENGINES.has(engine) || !APP_STATES.has(state)) return
        if (appState?.engine === engine && appState.state === state) return
        appState = { engine, state }
        void setMachineAppState(machineId, engine, state, PRESENCE_TTL_SEC)
        void publishUp(machineId, {
          webEligible: false,
          commanderEligible: false,
          frame: { type: 'machine_app_status', payload: { engine, state } } as unknown as Frame,
        })
        return
      }
      // The daemon saying a desktop window is attached to it (cli backendSocket sendAppPresence).
      // Bookkeeping only — absorbed here, never published: no client has any use for it and an
      // unknown frame type must not reach the firmware.
      if (app.type === 'app_presence') {
        const { kind, surface } = (app.payload ?? {}) as { kind?: unknown; surface?: unknown }
        if (typeof kind !== 'string' || !APP_PRESENCE_KINDS.has(kind)) return
        // No surface = the desktop app (every daemon before this field, and the desktop window now). A
        // TUI says where it runs (TUI_SURFACES); a name this backend does not know counts as nothing,
        // never as the desktop app.
        if (surface === undefined) touchUserPresence(kind as 'open' | 'ping')
        else if (typeof surface === 'string' && TUI_SURFACES.has(surface)) {
          touchTuiPresence(surface as ClientSurface, kind as 'open' | 'ping')
          // Its account's daemons relay the events only a terminal app reads while one is open (bus.ts noteTuiPresence).
          void noteTuiPresence(userId, kind as 'open' | 'ping')
        }
        return
      }
      // The machine appending to its account's device key log (lib/deviceKeyLog.ts): its own key, or a
      // removal it signs. Over THIS socket so the entry is tied to the machine that sent it — a
      // machine can only register a key under its own id. Answered to the machine alone, never published.
      if (app.type === 'devlog_append') {
        const p = (app.payload ?? {}) as { requestId?: unknown; entry?: unknown }
        const requestId = typeof p.requestId === 'string' ? p.requestId.slice(0, 64) : ''
        if (!devlogRate.allow()) {
          send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: { requestId, error: 'RATE_LIMITED' } } })
          return
        }
        void appendDeviceKey(userId, p.entry, { kind: 'machine', machineId, ...(harnessSessionId ? { harnessSessionId } : {}), ...(team ? { team } : {}) })
          .then((r) => send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: r.ok
            ? { requestId, head: r.head }
            : { requestId, error: r.code, ...('head' in r ? { head: r.head } : {}) } } }))
          .catch((err) => {
            logger.warn('devlog append failed', { machineId, error: String(err) })
            send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: { requestId, error: 'UNAVAILABLE' } } })
          })
        return
      }
      // Hub tap (mirrors managerWs): keep `machine_agents` in sync from the adapter's agent
      // lifecycle frames. Needed so the device voice path's agent-ownership check
      // (deviceWs: `machineAgent.findFirst`) recognizes remote tmux sessions.
      const f = env.frame as { type?: string; agentId?: unknown; replay?: unknown; payload?: { agent?: unknown; agentId?: unknown; machineId?: unknown } }
      if (f.type === 'agent_synced') {
        void recordCreatedAgent(machineId, f.payload?.agent as { id?: unknown; name?: unknown } | undefined)
      } else if (f.type === 'agent_deleted' && typeof f.payload?.agentId === 'string') {
        // Every producer sends `agentId` (machine-adapter cli.ts, machine-node websocket.ts/agents.ts).
        // Reading `machineId` here meant no deletion was EVER recorded, so machine_agents grew a row per
        // agent forever — and that table is what the plan cap counts.
        void recordDeletedAgent(machineId, f.payload.agentId)
      } else if (f.type === 'turn_started' && f.replay !== true) {
        // Usage signal for machine_daily_presence / agent_daily_presence. Only the plaintext `type`,
        // top-level `agentId` and `replay` (set by the CLI's correlateAgentEvent / emitSessionEvents)
        // are read — the payload is E2EE ciphertext (cli e2ee/core.ts ENCRYPTED_UP_TYPES) and stays
        // opaque here. The CLI already dedupes engines that re-announce one turn (cursor/agy/copilot,
        // cli.ts), so one frame == one turn. `replay: true` is the CLI saying this one did NOT start
        // now — a turn resumed at attach, or a prompt re-read from a transcript already on disk
        // (measured 2026-09-17: 42 such frames in one second credited to one agent). It still relays,
        // it is just not a turn today. A frame with no (or a malformed) agentId has nothing to
        // attribute the turn to and is not counted.
        // A machine starting turns in a loop (lib/shortTurnGuard.ts): past the cap its turn starts are neither counted
        // nor relayed for a while. Everything else it sends still is.
        const verdict = shortTurns.admit()
        if (verdict !== 'relay') {
          if (verdict === 'pause_started') logger.warn('machine is starting turns in a loop; holding its turn starts for 60 s', { machineId, userId })
          return
        }
        const now = new Date()
        const agentId = typeof f.agentId === 'string' && TURN_AGENT_ID_RE.test(f.agentId) ? f.agentId : undefined
        if (agentId && allowTurnWrite(now.getTime())) {
          void recordTurnStarted(userId, machineId, agentId, now, team)
            .catch((err) => logger.warn('turn tracking failed', { machineId, agentId, error: String(err) }))
        }
      }
      if (env.userEligible) {
        // A team machine raises no notice on the person's apps: pairing a device with a machine is the person's to start.
        if (!team) {
          void publishUserDeviceE2eePair(userId, machineId, env.frame).catch((err) => {
            logger.warn('adapter user-level e2ee pair publish failed', { machineId, userId, error: String(err) })
          })
        }
        if (env.webEligible === false && env.commanderEligible !== true && !env.targetConnId) return
      }
      const up = {
        webEligible: env.webEligible !== false, // default true (plain event/RPC frames)
        commanderEligible: env.commanderEligible === true, // devices get only opted-in frames
        frame: env.frame,
      }
      // An E2EE per-client push (pairing, welcome, an RPC reply) takes its connection's route, so it keeps its order with
      // that connection's terminal frames.
      if (env.targetConnId) { sendTargeted({ ...up, targetConnId: env.targetConnId }); return }
      // Every client of the machine: this process's own first, then the rest through Redis, whose copy this process
      // skips (originPid), as manager-ws does. A local viewer's targeted frames are delivered here at once, so its
      // untargeted ones must be too, or an RPC reply would overtake the event the daemon sent before it (review 2026-10-31).
      deliverUpLocal(machineId, up)
      void publishUp(machineId, { ...up, originPid: PROCESS_ID }).then(n => recordRelay('up broadcast', 'published', n))
    }
  }
  // Drain whatever arrived while the role was being attached, in the order it was sent.
  for (const [raw, isBinary] of preHandlerQueue) onMessage(raw, isBinary)
  preHandlerQueue.length = 0

  const cleanup = (): void => {
    releaseLiveness()
    routes.close()
    terminalDownUnsub()
    accountPushesUnsub()
    swarmPushesUnsub()
    swarmHostUnsub()
    // Only the CURRENT owner tears the role down — a superseded socket must not mark the fresh
    // connection offline. A superseded socket still releases its own liveness tracking above.
    if (owners.get(machineId) === ws) {
      owners.delete(machineId)
      void role.detach()
      if (computerId) void releaseMachineOwner(machineId, computerId) // free the claim (compare-and-delete)
      // Drop the app claim with the socket. role.detach() already publishes node_status{online:false},
      // and every row builder omits the app keys when offline, so the device converges on that frame;
      // this delete is what stops a reconnect from briefly re-reading the dead value.
      void clearMachineAppState(machineId)
      touchMachinePresence('close') // lastSeenAt at disconnect, floored (MACHINE_CLOSE_FLOOR_MS); a superseded socket must not stamp it
    }
  }
  ws.on('close', cleanup)
  ws.on('error', cleanup)
}

async function publishUserDeviceE2eePair(userId: string, machineId: string, frame: Frame): Promise<void> {
  const type = frame.type as string | undefined
  if (type !== 'device_e2ee_pair_pending' && type !== 'device_e2ee_pair_cleared') return
  const p = (frame.payload ?? {}) as Record<string, unknown>
  const pairId = typeof p.pairId === 'string' ? p.pairId : ''
  if (!pairId) return

  const machine = await prisma.machine.findUnique({
    where: { machineId },
    select: { name: true },
  })
  const base = {
    machineId,
    machineName: machine?.name ?? null,
    pairId,
    computerFingerprint: typeof p.computerFingerprint === 'string' ? p.computerFingerprint : null,
  }

  if (type === 'device_e2ee_pair_pending') {
    await publishDeviceE2eePair(userId, {
      kind: 'pending',
      ...base,
      label: typeof p.label === 'string' ? p.label : 'Device',
      expiresAt: typeof p.expiresAt === 'number' ? p.expiresAt : Date.now() + 60_000,
    })
    return
  }

  const result = p.result === 'paired' || p.result === 'failed' || p.result === 'cancelled' ? p.result : 'failed'
  await publishDeviceE2eePair(userId, { kind: 'cleared', ...base, result })
}