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.

34.5 KB
Raw Blame
/**
 * The gateway in its own process, as the core sees it (docs/design/2026-10-06-core-boundary-next.md, step
 * 10, R2; the process's side is gateway/gatewayProcess.ts). The relay, the E2EE sessions and every key
 * live there; the core keeps what it must read in line, as the gateway last said it, and sends what it has
 * for remote clients in the clear, over the service link only the master's token opens.
 *
 *   - What the core reads synchronously is kept here from the gateway's notices: whether the backend link
 *     is up, and the remote clients it holds a session with (the socket keeps their roles and labels).
 *   - What the core has for a remote client goes to the gateway as it is, never held: a frame the gateway
 *     is not there to seal is a frame no remote client could have got. While the gateway reads nothing
 *     (hung), what would pile up on the socket to it is dropped at GATEWAY_BUFFER_LIMIT and said once a
 *     minute; the master kills a hung gateway soon after.
 *   - The gateway gone (crashed, killed, restarting) is the relay gone: every remote client with it, the
 *     link down, no device watching. A window working on another machine through it is closed, and opens
 *     again on its own. The windows on this computer and the agents never notice.
 *   - Each time the gateway connects it is told everything it starts from (`start`): it builds its relay
 *     afresh, as a core's restart did when the relay ran in the core.
 */
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
import { answerAccountQuery } from './accountQueries.js'
import { guestMachineList, withStaleMarker } from '../lib/machineListReply.js'
import type { GatewayMachines } from './api.js'
import { LANE_OFF } from './api.js'
import type {
  BackendNotice, GatewayEvents, LocalWindows, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer, LaneSeal,
  RemoteClient, RemoteRole, RemoteTransport, TabFrame, TabKey, TabRelay, WindowRelay, WindowRelaySession, WindowRelaySink,
} from './api.js'
import { askTabKey } from '../lib/tabKeyWire.js'
import { askTabRelay, tabFrameOf } from '../lib/tabRelayWire.js'
import { ON_DEMAND_START_MS, type ServiceFrame } from './serviceLinks.js'

export interface GatewayLinkDeps {
  /** The core's side of what the gateway tells it (BackendSocket's `fromGateway`). */
  events: GatewayEvents
  /** The service link to the gateway (core/serviceLinks.ts, for `gateway`). */
  notify(frame: ServiceFrame): boolean
  notifyBinary(bytes: Uint8Array): boolean
  buffered(): number
  call(type: string, payload: Record<string, unknown>, waitMs?: number): Promise<Record<string, unknown>>
  /** What the gateway starts from each time it connects: this machine's ids, whether it is signed in. */
  start(): Record<string, unknown>
  /** The account's tokens (`core.account`): the gateway asks for one each time it dials, and holds none. */
  tokens: { accessToken(opts?: { force?: boolean; failedToken?: string }): Promise<string> }
  /** A read of the backend's REST API under the account's session (the core's proxy). */
  backend(method: 'GET', path: string): Promise<HttpAnswer>
  /** The last machine list reported by the gateway, for the models service's presence labels. */
  machines?(state: GatewayMachines): void
  /** Ask the master for the gateway's process (harnessd/coreLink.ts `want`): it runs on demand (core/gatewayWake.ts). */
  want?(): void
  /** How long what waits for the gateway's first start waits (core/serviceLinks.ts `ON_DEMAND_START_MS`). */
  startWaitMs?: number
  newId?: () => string
  now?: () => number
  log?: (line: string) => void
}

/** Bytes waiting on the socket to the gateway past which a frame for remote clients is dropped. A hung
 *  gateway reads nothing for up to its heartbeat deadline (30 s); every event and terminal byte for
 *  remote clients would wait in the core's memory meanwhile. */
export const GATEWAY_BUFFER_LIMIT = 16 * 1024 * 1024

/** Optional counters yield long before relay traffic does. Never queue measurements for a restart. */
export const GATEWAY_USAGE_BUFFER_LIMIT = 64 * 1024

/** How long a pairing may take: the code is typed on one screen and checked over the relay, round by round. */
export const PAIR_WAIT_MS = 120_000

/** The close a window on another machine gets when the gateway it went through is gone: try again shortly. */
export const WINDOW_GATEWAY_GONE = 1013

/** The most a window's E2EE requests and sessions to open wait for the gateway's first start; the oldest go. */
export const OWED_MAX = 256

/** How long the fleet's lane waits on the gateway to seal or open a frame. The frames behind it wait too,
 *  in order; a gateway that has not answered in this long is hung, and the master ends it soon after. */
export const LANE_WAIT_MS = 5_000

/** How long a shared tab's relay call waits on the gateway: a send there answers within 8 s of being asked
 *  (gateway/tabRelay.ts `TAB_RELAY_SEND_DEADLINE_MS`: the relay admitting its socket, then its turn within the rate),
 *  so the gateway's answer is the one the core gives, and a frame answered false here is never sent there. */
export const TAB_RELAY_WAIT_MS = 10_000

const UNAVAILABLE: HttpAnswer = { status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } }

interface Window {
  sink: WindowRelaySink
  onClosed: (code: number, reason: string) => void
  opening: { resolve: (session: WindowRelaySession) => void; reject: (error: Error) => void } | null
}

const text = (value: unknown): string => (typeof value === 'string' ? value : '')
const record = (value: unknown): Record<string, unknown> =>
  (value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {})

export function createGatewayLink(deps: GatewayLinkDeps) {
  const { events } = deps
  const log = deps.log ?? ((line: string) => console.warn(line))
  const now = deps.now ?? Date.now
  let counter = 0
  const newId = deps.newId ?? (() => `window-${++counter}`)
  /** The gateway's process is connected to this core. */
  let up = false
  /** It has connected in this core's life. Before that it runs on demand: what needs it asks for it, once, and
   *  what a window asked of it meanwhile (an E2EE request, a session to another machine) waits for it, in order,
   *  to be told after its `start`. Gone again later it is the master's to restart, and nothing waits. */
  let seen = false
  let asked = false
  const owed: Array<Record<string, unknown>> = []
  let owedTimer: ReturnType<typeof setTimeout> | null = null
  /** The backend link, as the gateway last said. */
  let linkUp = false
  // What the gateway is told again whenever it connects.
  let requestsOpen = true
  let dial: 'connect' | 'local' | null = null
  let localClients: LocalWindows = { desktop: 0, tui: 0 }
  let wifiService = false
  let reachable: string[] | null = null
  let machines: GatewayMachines | null = null
  /** The remote clients the gateway registered, to forget each when it goes. */
  const clients = new Set<string>()
  const windows = new Map<string, Window>()
  const localRequests = new Map<string, { fail(): void; finish(): void }>()
  let droppedSaidAt = -Infinity
  let droppedUnsaid = 0

  const send = (kind: string, payload: Record<string, unknown> = {}): boolean =>
    up && deps.notify({ type: 'service_event', payload: { ...payload, kind } })
  /** A frame for remote clients: dropped rather than held while the gateway reads nothing. */
  const fits = (): boolean => {
    if (deps.buffered() <= GATEWAY_BUFFER_LIMIT) return true
    const at = now()
    if (at - droppedSaidAt < 60_000) droppedUnsaid++
    else {
      log(`[gateway] it is not reading: frames for remote clients dropped${droppedUnsaid ? ` · ${droppedUnsaid} more since` : ''}`)
      droppedSaidAt = at
      droppedUnsaid = 0
    }
    return false
  }
  const bulk = (kind: string, payload: Record<string, unknown>): boolean => up && fits() && send(kind, payload)
  const reachableClient = (connId: string): boolean => up && clients.has(connId)
  const need = (): void => {
    if (up || seen || asked) return
    asked = true
    deps.want?.()
  }
  const localKey = (connId: string, type: unknown, requestId: unknown): string | null =>
    requestId === undefined ? null : JSON.stringify([connId, type, requestId])
  const refuseLocal = (connId: string, frame: Record<string, unknown>): void => {
    const requestId = record(frame.payload).requestId
    if (requestId !== undefined) events.toLocal(connId, {
      type: `${frame.type}_result`, payload: { requestId, error: 'SERVICE_UNAVAILABLE', service: 'gateway', retryable: true },
    })
  }
  /** Chaos testing killed the gateway between a local request and its reply. The core must answer for a
   *  lost link, including in-flight requests; the window's longer deadline is not a service fallback.
   *  Bound both the wait and the number held, and never replay a pairing or revocation after a restart. */
  const forwardLocal = (connId: string, frame: Record<string, unknown>): void => {
    const key = localKey(connId, `${frame.type}_result`, record(frame.payload).requestId)
    if (key !== null) {
      if (localRequests.has(key)) return
      if (localRequests.size >= OWED_MAX) { refuseLocal(connId, frame); return }
      const finish = (): void => { clearTimeout(timer); localRequests.delete(key) }
      const fail = (): void => { finish(); refuseLocal(connId, frame) }
      const timer = setTimeout(fail, frame.type === 'phone_pair' || frame.type === 'device_e2ee_pair' ? PAIR_WAIT_MS : LANE_WAIT_MS)
      timer.unref?.()
      localRequests.set(key, { fail, finish })
    }
    if (!send('localFrame', { connId, frame }) && key !== null) localRequests.get(key)!.fail()
  }
  /** What waits for the first start gives up explicitly: no late pairing or window open after refusal. */
  const giveUp = (item: Record<string, unknown>): void => {
    if (item.kind === 'windowOpen') closeWindow(text(item.id), WINDOW_GATEWAY_GONE, 'the relay did not start')
    else refuseLocal(text(item.connId), record(item.frame))
  }
  const owe = (kind: string, payload: Record<string, unknown>): void => {
    owed.push({ ...payload, kind })
    if (owed.length > OWED_MAX) giveUp(owed.shift()!)
    need()
    owedTimer ??= setTimeout(() => { owedTimer = null; for (const item of owed.splice(0)) giveUp(item) }, deps.startWaitMs ?? ON_DEMAND_START_MS)
    owedTimer.unref?.()
  }

  const port: GatewayPort = {
    usageLaunch: (signal) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) send('usageLaunch', { signal }) },
    usageCounter: (metric) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) send('usageCounter', { metric }) },
    connect: () => { dial = 'connect'; need(); send('connect') },
    serveThisComputerOnly: () => { dial = 'local'; send('thisComputerOnly') },
    holdRequests: () => { requestsOpen = false; send('hold') },
    openRequests: () => { requestsOpen = true; send('open') },
    connected: () => up && linkUp,
    broadcast: (frame, guest) => { bulk('broadcast', guest ? { frame, guest } : { frame }) },
    commander: (frame) => { bulk('commander', { frame }) },
    user: (frame) => { send('user', { frame }) },
    reply: (connId, type, requestId, payload) => { send('reply', { connId, type, requestId, payload }) },
    target: (connId, type, payload) => up && linkUp && clients.has(connId) && bulk('target', { connId, type, payload }),
    terminal: (connId, type, payload) => reachableClient(connId) && bulk('terminal', { connId, type, payload }),
    terminalBinary: (connId, clear) => {
      if (!reachableClient(connId) || !fits()) return false
      const local = encodeTerminalLocal(clear)
      const bytes = local && encodeGatewayBinary(GatewayBinary.remote, connId, local)
      return !!bytes && deps.notifyBinary(bytes)
    },
    observer: (connId, type, payload) => up && linkUp && send('observer', { connId, type, payload }),
    windowOpened: (surface) => { send('windowOpened', { surface }) },
    localClients: (windows) => { localClients = windows; send('localClients', { windows }) },
    local: async (connId, frame) => { if (up || seen) forwardLocal(connId, frame); else owe('localFrame', { connId, frame }) },
    device: (connId, type, payload) => reachableClient(connId) && send('device', { connId, type, payload }),
    deviceClient: (connId, identity) => { send('deviceClient', { connId, identity }) },
    stop: async () => { send('stop') },
  }

  const http = async (type: string, payload: Record<string, unknown> = {}, waitMs?: number): Promise<HttpAnswer> => {
    const answer = await deps.call(type, payload, waitMs)
    if (typeof answer.status !== 'number') return UNAVAILABLE
    // A busy answer's Retry-After (gateway/accountHttp.ts), which the daemon passes on to the Desktop's reports.
    const retry = answer.retryAfterMs
    return { status: answer.status, body: record(answer.body),
      ...(typeof retry === 'number' && Number.isFinite(retry) && retry >= 0 ? { retryAfterMs: retry } : {}) }
  }

  /**
   * The fleet's lane's sessions, in the gateway (gateway/lane.ts). Every one of them is a call, the lane's
   * drop too, so the gateway takes them in the order the lane made them. A gateway that is not there
   * starts no session and seals nothing: the lane hears `lost`, never its frame back as it was.
   */
  const lane = (op: string, payload: Record<string, unknown> = {}) => deps.call(GATEWAY_CALLS.lane, { ...payload, op }, LANE_WAIT_MS)
  const laneOps: LaneSeal = {
    hello: async (machineId, peerPub) => {
      const answer = await lane('hello', { machineId, peerPub })
      if (answer.frame && typeof answer.frame === 'object') return record(answer.frame)
      throw new Error('the gateway could not start an E2EE session: it is not running')
    },
    welcome: async (machineId, payload) => (await lane('welcome', { machineId, payload })).ok === true,
    rekey: async (machineId, payload) => { await lane('rekey', { machineId, payload }) },
    seal: async (machineId, frame) => {
      const answer = await lane('seal', { machineId, frame })
      return answer.frame && typeof answer.frame === 'object' ? { frame: record(answer.frame) } : { lost: true }
    },
    open: async (machineId, frame) => {
      const answer = await lane('open', { machineId, frame })
      if (answer.frame && typeof answer.frame === 'object') return { frame: record(answer.frame) }
      if (answer.unknownEpoch === true) return { unknownEpoch: true }
      return answer.unreadable === true ? { unreadable: true } : { lost: true }
    },
    drop: (machineId) => { void lane('drop', { machineId }) },
  }

  /** Share's owner's key, held by the gateway (gateway/observerKey.ts): each a call; none while it is away. */
  const ownerKey = async (payload: Record<string, unknown>): Promise<string> => {
    const answer = await deps.call(GATEWAY_CALLS.observerKey, payload, LANE_WAIT_MS)
    if (typeof answer.key === 'string') return answer.key
    // Its process down, or its gateway not started yet: no key to sign with.
    throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway holds no key just now: it is not running')
  }

  /** Shared tabs' keys, held by the gateway (gateway/tabKey.ts): one call a method, the drop too, so the gateway takes
   *  them in the order Agent Messages made them. While it is away: no signature, no session, nothing sealed. */
  const tabKeyOps: TabKey = askTabKey((payload) => deps.call(GATEWAY_CALLS.tabKey, payload, LANE_WAIT_MS))
  /** Shared tabs' relay, whose sockets the gateway holds (gateway/tabRelay.ts): one call a method. While it is away,
   *  nothing is opened or sent; what the sockets hear comes back as `tabFrame` notices. */
  const tabRelayOps: TabRelay = askTabRelay((payload) => deps.call(GATEWAY_CALLS.tabRelay, payload, TAB_RELAY_WAIT_MS))

  const ops: GatewayOps = {
    backend: (method, path, body) => http(GATEWAY_CALLS.backend, { method, path, ...(body === undefined ? {} : { body }) }, 25_000),
    machines: async (fallback = false) => {
      const state = deps.start()
      const requestedOwner = text(record(state.account).machineId)
      if (!requestedOwner) {
        const body = guestMachineList(text(state.computerId), text(state.machineName), text(state.hostname))
        deps.machines?.({ owner: null, body, fetchedAt: now() })
        return { status: 200, body }
      }
      const answer = await http(GATEWAY_CALLS.machines, { fallback }, 25_000)
      const currentOwner = text(record(deps.start().account).machineId)
      if (requestedOwner !== currentOwner) return { status: 409, body: { success: false, error: { code: 'ACCOUNT_CHANGED', message: 'The account changed. Refresh and try again.' } } }
      if (answer.status === 401 || answer.status === 403) machines = null
      const owner = currentOwner
      // A crashed gateway costs the network, not the app's last known roster. Never cross accounts or
      // hide a real sign-out with rows cached for an earlier session.
      if (fallback && answer.status >= 500 && owner && machines?.owner === owner && machines.body) {
        return { status: 200, body: withStaleMarker(machines.body, machines.fetchedAt) }
      }
      return answer
    },
    mintGridName: async () => {
      const answer = await deps.call(GATEWAY_CALLS.mintGridName, {}, 15_000)
      if (typeof answer.error === 'string') throw new Error(answer.error)
      return typeof answer.name === 'string' ? answer.name : null
    },
    status: async (): Promise<GatewayStatus> => {
      // Never started, it has no pairing under way and nothing to say; `/api/status` is asked far too often to
      // start it for.
      if (!up && !seen) return { fingerprint: null, pairs: [], pending: null }
      const answer = await deps.call(GATEWAY_CALLS.status, {}, 2_000)
      return {
        fingerprint: typeof answer.fingerprint === 'string' ? answer.fingerprint : null,
        pairs: Array.isArray(answer.pairs) ? answer.pairs as Array<Record<string, unknown>> : [],
        pending: answer.pending && typeof answer.pending === 'object' ? answer.pending as Record<string, unknown> : null,
      }
    },
    pair: (code) => http(GATEWAY_CALLS.pair, { code }, PAIR_WAIT_MS),
    listPairs: () => http(GATEWAY_CALLS.listPairs),
    revoke: (id) => http(GATEWAY_CALLS.revoke, { id }),
    revokeAll: () => http(GATEWAY_CALLS.revokeAll),
    setRemotePassword: (password) => http(GATEWAY_CALLS.setRemotePassword, { password }),
    clearRemotePassword: () => http(GATEWAY_CALLS.clearRemotePassword),
    remotePasswordStatus: () => http(GATEWAY_CALLS.remotePasswordStatus),
    trustLinkedPeer: (peer) => http(GATEWAY_CALLS.trustLinkedPeer, { peer }),
    groupList: () => http(GATEWAY_CALLS.groupList),
    groupSync: () => http(GATEWAY_CALLS.groupSync),
    groupRemove: (selector) => http(GATEWAY_CALLS.groupRemove, { selector }),
    devicesList: () => http(GATEWAY_CALLS.devicesList),
    devicesRemove: (pub) => http(GATEWAY_CALLS.devicesRemove, { pub }),
    devicesHistory: () => http(GATEWAY_CALLS.devicesHistory),
    devicesDismiss: (body) => http(GATEWAY_CALLS.devicesDismiss, { body }),
    devicesRebaseline: (confirm, head) => http(GATEWAY_CALLS.devicesRebaseline, { confirm, ...(head ? { head } : {}) }),
    wifi: async (request) => {
      const answer = await deps.call(GATEWAY_CALLS.wifi, request, request.op === 'pair' ? PAIR_WAIT_MS : undefined)
      if (answer.result && typeof answer.result === 'object') return { result: answer.result as Record<string, unknown> }
      const refused = record(answer.refused)
      const why: GatewayRefusal = typeof refused.code === 'string'
        ? { code: refused.code, message: text(refused.message) }
        : { code: 'UNAVAILABLE', message: 'The Wi-Fi device link is not reachable on this computer right now. Try again.' }
      return { refused: why }
    },
    wifiService: (on) => { wifiService = on; if (on) need(); send('wifiService', { on }) },
    revokeIdentity: (identity) => { send('revokeIdentity', { identity }) },
    account: (next) => {
      if (machines && machines.owner !== next.machineId) {
        machines = null
        deps.machines?.({ owner: next.machineId, body: null, fetchedAt: now() })
      }
      send('account', { account: next })
    },
    reachable: (machineIds) => { reachable = machineIds; send('reachable', { machineIds }) },
    lane: laneOps,
    observerKey: {
      publicKey: () => ownerKey({ op: 'public' }),
      signWelcome: (machineId, shareId, peer, ephemeral) => ownerKey({ op: 'sign', machineId, shareId, peer, ephemeral }),
    },
    tabKey: tabKeyOps,
    tabRelay: tabRelayOps,
    // The account's connected services, sealed and opened by the gateway (lib/e2ee/connectorVault.ts).
    connectorVault: {
      seal: async (plaintext) => {
        const answer = await deps.call(GATEWAY_CALLS.connectorVault, { op: 'seal', plaintext }, LANE_WAIT_MS)
        if (answer.envelope && typeof answer.envelope === 'object') return record(answer.envelope)
        throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway holds no key just now: it is not running')
      },
      open: async (envelope) => {
        const answer = await deps.call(GATEWAY_CALLS.connectorVault, { op: 'open', envelope }, LANE_WAIT_MS)
        return typeof answer.plaintext === 'string' ? { plaintext: answer.plaintext, complete: answer.complete === true } : null
      },
    },
    // Machines shared across accounts, pinned and trusted by the gateway (gateway/sharedTrust.ts).
    sharedTrust: async (desired) => {
      const answer = await deps.call(GATEWAY_CALLS.sharedTrust, { ...desired }, LANE_WAIT_MS)
      if (typeof answer.pins === 'number' && typeof answer.keys === 'number') return { pins: answer.pins, keys: answer.keys }
      throw new Error(typeof answer.error === 'string' && !answer.error.startsWith('SERVICE_') ? answer.error : 'the gateway is not running')
    },
  }

  /** A window's session through the gateway: to another of the owner's machines, or to a harness shared
   *  with this account (`share`). */
  const openWindow = (open: Record<string, unknown>, sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
    new Promise((resolve, reject) => {
      if (!up && seen) { reject(new RelayConnectError('the relay is restarting', WINDOW_GATEWAY_GONE)); return }
      const id = newId()
      windows.set(id, { sink, onClosed, opening: { resolve, reject } })
      if (up) send('windowOpen', { ...open, id })
      else owe('windowOpen', { ...open, id })
    })
  const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
    sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
    openWindow({ machineId, autonomousEnv, frame: selectFrame, isolated }, sink, onClosed)
  const sessionOf = (id: string): WindowRelaySession => ({
    send: async (frame) => { send('windowSend', { id, frame }) },
    sendBinary: async (clear) => {
      const local = encodeTerminalLocal(clear)
      const bytes = local && encodeGatewayBinary(GatewayBinary.window, id, local)
      if (bytes && up) deps.notifyBinary(bytes)
    },
    detach: () => { if (windows.delete(id)) send('windowDetach', { id }) },
  })
  const windowRelay: WindowRelay = {
    acquire: open(false),
    acquireIsolated: open(true),
    invalidate: (machineId) => { send('windowInvalidate', { machineId, isolated: false }) },
    invalidateIsolated: (machineId) => { send('windowInvalidate', { machineId, isolated: true }) },
    acquireShare: (machineId, shareId, sink, onClosed) => openWindow({ machineId, share: shareId }, sink, onClosed),
  }

  /** A window's connection ended, from the gateway's side or because the gateway went. */
  const closeWindow = (id: string, code: number, reason: string): void => {
    const window = windows.get(id)
    if (!window) return
    windows.delete(id)
    if (window.opening) window.opening.reject(new RelayConnectError(reason, code))
    else window.onClosed(code, reason)
  }

  /** What the gateway tells the core (`service_notice`): trusted as the gateway's, the master's token
   *  having opened the link, but read as data, never thrown on. */
  const notice = (payload: Record<string, unknown>): void => {
    const connId = text(payload.connId)
    switch (payload.kind) {
      case 'frame':
        void events.frame(connId, record(payload.frame), payload.transport === 'p2p' ? 'p2p' : 'relay' as RemoteTransport,
          payload.role === 'web' ? 'web' : 'device' as RemoteRole)
        return
      case 'client': {
        const client = payload.client ? record(payload.client) as unknown as RemoteClient : null
        if (client) clients.add(connId)
        else clients.delete(connId)
        events.client(connId, client)
        return
      }
      case 'disconnected':
        clients.delete(connId)
        void events.disconnected(connId)
        return
      case 'observer':
        void events.observer(connId, text(payload.type), record(payload.payload))
        return
      case 'toLocal': {
        const frame = record(payload.frame)
        const key = localKey(connId, frame.type, record(frame.payload).requestId)
        if (key !== null) localRequests.get(key)?.finish()
        events.toLocal(connId, frame)
        return
      }
      case 'status':
        linkUp = payload.connected === true
        events.status(linkUp)
        return
      case 'linkDown':
        events.linkDown()
        return
      case 'commanders':
        events.commanders(Number(payload.count) || 0, typeof payload.active === 'number' ? payload.active : null, payload.recheck === true)
        return
      case 'commanderJoined':
        events.commanderJoined()
        return
      case 'meta':
        events.meta(record(payload.meta) as { name?: string | null; gridName?: string | null })
        return
      case 'notice':
        events.notice(record(payload.notice) as unknown as BackendNotice)
        return
      case 'machines': {
        const owner = text(payload.owner) || null
        if (owner !== (text(record(deps.start().account).machineId) || null)) return
        const body = payload.body && typeof payload.body === 'object' && !Array.isArray(payload.body) ? record(payload.body) : null
        machines = { owner, body,
          fetchedAt: typeof payload.fetchedAt === 'number' && Number.isFinite(payload.fetchedAt) && Math.abs(payload.fetchedAt) <= 8.64e15 ? payload.fetchedAt : now() }
        deps.machines?.(machines)
        return
      }
      case 'revoked':
        events.revoked()
        return
      case 'busy':
        events.busy()
        return
      case 'device':
        void events.device(connId, record(payload.frame), payload.opened ? record(payload.opened) : null)
        return
      case 'deviceRevoked':
        events.deviceRevoked(text(payload.identity))
        return
      case 'toWindows':
        events.toWindows(record(payload.frame))
        return
      case 'tabFrame': {
        const event = tabFrameOf(payload.event)
        if (event) events.tabFrame(event)
        return
      }
      case 'windowOpened': {
        const window = windows.get(text(payload.id))
        if (!window?.opening) return
        const { resolve } = window.opening
        window.opening = null
        resolve(sessionOf(text(payload.id)))
        return
      }
      case 'windowFailed':
      case 'windowClosed':
        closeWindow(text(payload.id), typeof payload.code === 'number' ? payload.code : 1011, text(payload.reason) || 'relay failed')
        return
      case 'windowFrame':
        windows.get(text(payload.id))?.sink.sendFrame(record(payload.frame))
        return
      default:
        log(`[gateway] an unknown notice from the gateway was ignored: ${JSON.stringify(String(payload.kind)).slice(0, 80)}`)
    }
  }

  const binary = (raw: Uint8Array): void => {
    const decoded = decodeGatewayBinary(raw)
    if (!decoded) return
    if (decoded.kind === GatewayBinary.window) { windows.get(decoded.id)?.sink.sendBinary(decoded.bytes); return }
    const clear = decodeTerminalLocal(decoded.bytes)
    if (clear) void events.binary(decoded.id, clear)
  }

  /**
   * What the gateway asks the core (`service_query`): a token to dial with, the device key log's reads of
   * the backend, and the harnesses shared with this account (the Share relay finds a share among them
   * before it dials). Nothing else: the gateway is the relay, and the core's own REST reads are not its to
   * make. A refused token comes back as the session's own error, so the gateway can tell a session that
   * is over (stop for good) from one that could not be refreshed just now (try again).
   */
  const answer = async (query: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
    // The gateway is the lane's seal, never a lane of its own: it is answered tokens, and no lane step.
    if (query === 'access_token') return (await answerAccountQuery({ accessToken: (options) => deps.tokens.accessToken(options), lane: LANE_OFF }, query, payload))!
    if (query === 'backend' && payload.method === 'GET' && (text(payload.path).startsWith('/api/device-keys') || payload.path === '/api/harness-shares')) {
      return { ...await deps.backend('GET', text(payload.path)) }
    }
    return { error: 'UNKNOWN_QUERY' }
  }

  return {
    port,
    ops,
    windowRelay,
    notice,
    binary,
    answer,
    /** The core is stopping: the gateway closes its link to the backend (its process is the master's to end). */
    stop: (): Promise<void> => port.stop(),
    /** The gateway's process connected: it starts from everything it is told here, each time. */
    connected(): void {
      // A gateway that connects again without the core having seen it go (its link replaced) started afresh
      // all the same: what the core kept of the last one goes first.
      if (up) this.disconnected()
      up = true
      seen = true
      // The account as the core reads it now (`start`), which is never older than the last one it said.
      send('start', { requestsOpen, dial, localClients, wifiService, reachable, ...deps.start() })
      // Then what waited for its first start, in the order it came.
      if (owedTimer) clearTimeout(owedTimer)
      owedTimer = null
      for (const { kind, ...payload } of owed.splice(0)) {
        if (kind === 'localFrame') forwardLocal(text(payload.connId), record(payload.frame))
        else send(text(kind), payload)
      }
    },
    /** The gateway's process went: the relay with it, as far as everything in the core is concerned. */
    disconnected(): void {
      up = false
      for (const request of localRequests.values()) request.fail()
      for (const id of [...windows.keys()]) closeWindow(id, WINDOW_GATEWAY_GONE, 'the relay restarted')
      // Each remote client's connection ended with it: what it had open here goes (its terminals, its
      // viewers, the Wi-Fi device service's hold on it).
      for (const connId of [...clients]) { clients.delete(connId); void events.disconnected(connId) }
      events.linkDown()
      events.commanders(0, null)
      if (linkUp) { linkUp = false; events.status(false) }
    },
  }
}

export type GatewayLink = ReturnType<typeof createGatewayLink>

/** The lane's sessions as the core hands them to its services (`core.account.lane`): read from the gateway
 *  each time, because the core's API is built before the gateway is started. */
export function laneOf(gateway: () => LaneSeal): LaneSeal {
  return {
    hello: (machineId, peerPub) => gateway().hello(machineId, peerPub),
    welcome: (machineId, payload) => gateway().welcome(machineId, payload),
    rekey: (machineId, payload) => gateway().rekey(machineId, payload),
    seal: (machineId, frame) => gateway().seal(machineId, frame),
    open: (machineId, frame) => gateway().open(machineId, frame),
    drop: (machineId) => gateway().drop(machineId),
  }
}

/**
 * Shared tabs' relay as the core hands it to its services (`core.account.tabRelay`): read from the gateway each time, as
 * the lane is (`laneOf`). The core keeps which tabs were opened and not closed since (`opened`), because the sockets
 * and the service that wants them can each go without the other noticing:
 *   - The gateway alone restarting drops every socket without a word to Agent Messages, which would hear nothing more
 *     from its tabs until its next refresh: as the gateway connects again, every tab opened is opened again
 *     (`connected`). Its first connection opens nothing: every open went to it then.
 *   - A tab the relay closed for good (`closed`: 4403, 4409) is the service's to open again or not (messages/sharedTabs.ts).
 *   - Agent Messages out of the core's process going leaves the gateway holding sockets nobody listens to: they are
 *     closed (`closeOpened`), and the process opens them again as it starts.
 */
export function tabRelayOf(gateway: () => TabRelay): TabRelay & { heard(event: TabFrame): void; connected(): void; closeOpened(): void } {
  const opened = new Set<string>()
  let connectedBefore = false
  return {
    open: (sharedTabId) => { opened.add(sharedTabId); return gateway().open(sharedTabId) },
    send: (sharedTabId, to, payload) => gateway().send(sharedTabId, to, payload),
    close: (sharedTabId) => { opened.delete(sharedTabId); gateway().close(sharedTabId) },
    /** What a tab's relay said (`GatewayEvents.tabFrame`): a close is the tab no longer open. */
    heard: (event) => { if (event.closed) opened.delete(event.sharedTabId) },
    /** The gateway's process connected: after its first time, it holds none of the sockets it had. */
    connected: () => {
      if (connectedBefore) for (const sharedTabId of opened) void gateway().open(sharedTabId)
      connectedBefore = true
    },
    /** Agent Messages out of the core's process went: no one listens to its tabs' sockets until it is back. */
    closeOpened: () => {
      for (const sharedTabId of [...opened]) { opened.delete(sharedTabId); gateway().close(sharedTabId) }
    },
  }
}

/** Shared tabs' keys as the core hands them to its services (`core.account.tabKey`): read from the gateway each
 *  time, as the lane is (`laneOf`). */
export function tabKeyOf(gateway: () => TabKey): TabKey {
  return {
    publicKey: () => gateway().publicKey(),
    signRoster: (sharedTabId, version, body) => gateway().signRoster(sharedTabId, version, body),
    signKeyChange: (sharedTabId, nextPub) => gateway().signKeyChange(sharedTabId, nextPub),
    hello: (link) => gateway().hello(link),
    welcome: (link, payload) => gateway().welcome(link, payload),
    accept: (link, hello) => gateway().accept(link, hello),
    seal: (link, frame) => gateway().seal(link, frame),
    open: (link, frame) => gateway().open(link, frame),
    drop: (link) => gateway().drop(link),
  }
}