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.

67.0 KB
Raw Blame
/**
 * The gateway: everything between this machine and a remote client (docs/design/2026-10-06-core-boundary-next.md,
 * "Relay and E2EE — its own process", step 10). It holds the backend link (gateway/upstream.ts), the E2EE
 * manager with its sessions and keys, the terminals' P2P channels, and the Wi-Fi device's direct links,
 * which ride the same sessions. The core never sees a key: a remote client's frame reaches it opened, with
 * the role its session proved, and the core's frames for remote clients leave through here, sealed.
 *
 * Moved out of `BackendSocket` as it was (step 10, R1), still in the core's process; R2 runs it in a process
 * of its own, behind the same two interfaces (`GatewayPort`, what the core asks of it, and `GatewayEvents`,
 * what it tells the core, in core/api.ts). The rules it enforces are the ones the socket enforced, in the
 * same order and with the same words in the log: which frames only the backend may send, that a client's
 * frame is acted on only if it opens under that connection's session (default-deny), that a reply goes to
 * the requester alone and sealed, and that a content-bearing reply that cannot be sealed is a bare
 * E2EE_REQUIRED. backendSocket.spec.ts and gateway/gateway.spec.ts hold each of them.
 */
import { env } from '../config/env.js'
import type { GatewayEvents, GatewayPort, RemoteRole, RemoteTransport } from '../core/api.js'
import { launchErrorCode, type ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'
import type { LaunchErrorCode, ProductUsageMetric } from '../lib/productUsageContract.js'
import { WINDOW_SURFACES, type LocalWindows, type WindowSurface } from '../lib/windowSurfaces.js'
import { deviceDump } from '../lib/autonomous-device/dump.js'
import type { AuthSessionManager } from '../lib/authSession.js'
import { shouldReplayCommander } from '../lib/commanderReplay.js'
import { DEVICE_RECENT_SAFE_FRAME_BYTES, fitRecentReplyPayloadForDevice } from '../lib/deviceRecentTrim.js'
import { encryptRpcResult, rpcResultType } from '../lib/e2ee/applicationFrames.js'
import { b64d, fingerprint, isWrapped, type WrappedPayload } from '../lib/e2ee/core.js'
import { E2eeManager, type LinkedPeer, type PairResult } from '../lib/e2ee/manager.js'
import { MachinePeerStore } from '../lib/e2ee/machinePeers.js'
import { logFrame, sid } from '../lib/log.js'
import { BACKEND_ONLY_DOWN_TYPES, GATEWAY_REQUEST_TYPES, isLocalClientId, logSafeType } from '../lib/relayFrames.js'
import { encodeTerminalHop, TerminalBinaryKind, TerminalHopDirection, type TerminalBinaryClear } from '../lib/terminalBinary.js'
import {
  TerminalP2pResponderPool,
  TERMINAL_P2P_DOWN_TYPES,
  TERMINAL_P2P_SIGNAL_TYPES,
  type TerminalP2pData,
  type TerminalP2pSignal,
} from '../lib/terminalP2p.js'
import { UpstreamLink } from './upstream.js'

type Frame = Record<string, unknown>

export interface RelayGatewayOptions {
  /** Backend-resolved machine id, persisted by the SSO login preflight; in isolated unit tests, the token. */
  machineId: string
  auth?: Pick<AuthSessionManager, 'accessToken'>
  computerId?: string
  autonomousEnv?: string
  /** The core, as the gateway tells it what happened. */
  core: GatewayEvents
}

/** Transcript events only the terminal app (`harness tui`, Harness OS) reads in full. Desktop, the web and the phone take
 *  them only as "the model is working" or to clear a preview line, which the next text, tool or turn end does too; so while
 *  the account has no terminal app open they stay off the relay (one Desktop's day, 2026-10-30: about 12,700 of its
 *  170,666 frames). Thinking stays: Desktop's "Starting up…" chip for a resting grid model ends on it. */
export const TUI_ONLY_EVENTS: ReadonlySet<string> = new Set(['tool_end', 'subagent_finished', 'done', 'context_compact'])
/** The longest the backend's word that a terminal app is open is taken for (backend bus.ts TUI_OPEN_FOR_MS). */
export const TUI_OPEN_MAX_MS = 180_000
/** A machine's live events: what an app viewing it shows as it happens, and none of it read by the backend. While the
 *  backend counts no app on the machine they stay off the relay, a publish that reached no one
 *  (docs/superpowers/specs/2026-11-02-swarm-cache-delta-design.md, Part 4). `turn_started`, `agent_synced` and
 *  `agent_deleted` are not here: the backend counts turns and keeps the machine's agents from them. An app that connects
 *  lists the sessions itself, so what was held leaves nothing missing. */
export const UI_GATED_EVENTS: ReadonlySet<string> = new Set([
  'text_delta', 'tool_start', 'tool_end', 'user_message', 'thinking_delta', 'thinking_title', 'turn_heartbeat',
  'agent_activity', 'turn_ended', 'turn_summary', 'subagent_finished', 'done', 'context_compact',
])
/** How long a frame from a remote app keeps live events flowing without the backend's count: an app's first frame, its
 *  E2EE hello, comes before the `__clients` that counts it. */
export const UI_QUIET_MS = 60_000
/** How long the backend's "no app views this machine" is believed without being said again. It repeats `__clients` every
 *  15 s (backend nodeRole PRESENCE_REFRESH_MS); a word six repeats old may come from a backend that stopped counting. */
export const UI_SNAPSHOT_MAX_MS = 90_000

export class RelayGateway implements GatewayPort {
  /** Optional scalar-only measurement hooks. Never hand a frame or user payload to the collector. */
  productUsage?: {
    launch?(signal: ProductUsageLaunchSignal): void
    counter?(metric: ProductUsageMetric): void
    presence(active: boolean): void
    opened(surface: WindowSurface): void
    observe(type: 'turn_started' | 'turn_ended' | 'text_delta' | 'error', agent: string, replay: boolean, interrupted?: boolean): void
    /** An agent's launch state as its `agent_synced` frame says it, the failure's code a listed name only. */
    launchState?(agent: string, state: 'starting' | 'ready' | 'failed' | 'held' | 'other', code?: LaunchErrorCode): void
  }
  /** Web↔adapter E2EE: group-encrypts user events, runs the CPace pairing, holds per-conn sessions. */
  readonly e2ee: E2eeManager
  readonly machineId: string
  private readonly link: UpstreamLink
  private readonly core: GatewayEvents
  private readonly terminalP2p: TerminalP2pResponderPool
  /** The `terminal_open`s a client sent over its P2P channel, by request id, each with the E2EE counter it was
   *  sealed under: the stream its `terminal_ready` names starts on P2P, decided at that counter. */
  private readonly p2pPendingOpens = new Map<string, Map<string, number>>()
  private readonly p2pStreams = new Map<string, Set<string>>()
  /**
   * Per client and stream, the E2EE counter of the frame that last decided which wire the stream's output
   * rides. A client seals its frames in the order it decides, whichever wire carries them (one counter
   * domain for both, lib/e2ee/replayWindow.ts), but the two wires deliver at different speeds: a relay
   * `terminal_ack` the phone sealed just BEFORE its P2P resync arrived ~100–250ms after it, took the
   * stream back off P2P, and the phone, seeing output on the relay again, dropped its whole channel and
   * typed over the relay for ~4s while it dialled again (2026-10-15, `demoted · reason=relay_binary_received`
   * 0.3–3s after `migrate · done`). A frame sealed before the decision in force is not a decision.
   */
  private readonly routeCounters = new Map<string, Map<string, number>>()
  /** Streams whose stale relay frame has been logged since their last move onto P2P: once is enough. */
  private readonly staleRouteLogged = new Set<string>()
  /**
   * The terminal streams each remote client has open, as the core's frames to it say: `terminal_ready`
   * opens one, `terminal_closed` ends it. A stream a client moves onto its P2P channel must be one it
   * has (the core's own `hasStream` answered this when the gateway ran inside the socket); a stream that
   * closed meanwhile is closed again by the `terminal_closed` that follows it, which takes it off P2P.
   */
  private readonly liveStreams = new Map<string, Set<string>>()
  /** Cross-instance commander (device) client count, from backend `__clients` frames. */
  private commanderCount = 0
  /** Until when a terminal app of the account counts as open, from the backend's `__tui_open`; null until it has said
   *  (an older backend, a team account, the link not yet back), when every event is relayed as before. */
  private tuiUntil: number | null = null
  /** The backend's count of apps viewing this machine, from `__clients`, kept only when the backend says live events may be
   *  held on it (`uiGate`). null until it has said so (an older backend, or its RELAY_UI_GATE off) and while the link is
   *  down, when every event is relayed as before. */
  private uiGate: { ui: number; at: number } | null = null
  /** When a remote app (not a device, not the backend, not a Share viewer) last sent a frame. */
  private lastRemoteFrameAt = 0
  /** Subset of commanderCount whose device is ACTIVELY rendering this machine (multi-attach). null = the
   *  backend doesn't send the signal (old build). */
  private commanderActive: number | null = null
  private replayedCommanderGeneration: number | undefined
  private replayCommanderOnNextSnapshot = true
  /** Appends to the device key log waiting for the backend's answer, by requestId. */
  private readonly devlogAppends = new Map<string, (payload: Record<string, unknown> | null) => void>()
  private readonly downChains = new Map<string, Promise<void>>()
  /** P2P signalling, per connection, apart from `downChains` — see `enqueueDown`. */
  private readonly signalChains = new Map<string, Promise<void>>()
  /**
   * Remote clients' frames wait here until the core is ready (`openRequests`), each in its connection's own
   * order: the port answers long before start-up has wired every handler, and a request answered in
   * between met a handler that was not there yet.
   */
  private requestsOpen = true
  private openRequestGate: () => void = () => {}
  private requestGate: Promise<void> = Promise.resolve()
  private localWindows: LocalWindows = { desktop: 0, tui: 0 }
  private readonly directDeviceSinks = new Map<string, (frame: Frame) => void>()
  private readonly directDevicePins = new Map<string, string>()
  /** The Wi-Fi device sessions whose app said hello to the device service (in the core), by connection:
   *  the ones told, sealed, that they were unpaired (`onIdentityRevoked`). */
  private readonly deviceClients = new Map<string, string>()

  /** Answers the trust group's roster exchange (`group_sync`); null until the daemon wires it. */
  groupSync: { handle: (peerPub: string, payload: Record<string, unknown>) => Record<string, unknown> } | null = null
  /** The account's device key log grew (lib/e2ee/deviceLogSyncer.ts): re-read it from this machine's head. */
  onDeviceKeysChanged: (() => void) | null = null
  /** This machine's key was taken out of the account's device key log (`machine_revoked` says so). */
  onDeviceRemoved: ((pub: string) => void) | null = null
  /** Whether [pub] is this machine's own device key. Set, a `machine_revoked` naming another key (an earlier
   *  install under the same machine id) does not sign this one out. Null: every removal signs out. */
  isOwnDeviceKey: ((pub: string) => boolean) | null = null
  /** The link to the backend just came up (each reconnect too). */
  onLinkUp: (() => void) | null = null
  onDirectDeviceRevoked?: (fingerprint: string) => void
  /** A peer linked here over the remote password (after it is trusted and, for a machine, pinned back). */
  onPeerLinked?: (peer: LinkedPeer) => void
  /** A person unpaired this identity here (not the trust group removing it). */
  onUnpaired?: (identityPub: string) => void
  /** A hello signed by a key not paired here: the account's device key log may name it (manager.ts
   *  `onUnknownHello`). The hello waits for this, a few seconds at most. */
  onUnknownHello: ((identityPub: string) => Promise<void>) | null = null

  constructor({ machineId, auth, computerId = '', autonomousEnv = 'prod', core }: RelayGatewayOptions) {
    this.machineId = machineId
    this.core = core
    this.link = new UpstreamLink({
      machineId, auth, computerId, autonomousEnv,
      events: {
        down: (frame, connId) => this.enqueueDown(frame, connId, 'relay'),
        binary: (connId, clientFrame) => this.enqueueTerminalBinary(connId, clientFrame, 'relay'),
        up: () => this.onLinkUp?.(),
        gone: () => this.linkGone(),
        status: (connected) => this.core.status(connected),
        revoked: () => this.core.revoked(),
        busy: () => this.core.busy(),
        localClients: () => this.localWindows,
      },
    })
    this.e2ee = new E2eeManager({
      machineId: this.machineId,
      sendTo: (connId, frame) => this.sendTo(connId, frame),
      sendUser: (frame) => this.user(frame),
      isConnected: () => this.connected(),
      isConnectionAvailable: connId => this.directDeviceSinks.has(connId) || this.connected(),
      onIdentityPaired: (connId, pub) => { if (this.directDeviceSinks.has(connId)) this.directDevicePins.set(connId, pub) },
      onIdentityRevoked: identity => { this.deviceUnpaired(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },
      onSessionOpened: (connId, role, identity) => {
        // A new session counts from the start again: a counter kept from the last one would pin its streams.
        this.forgetRoutes(connId)
        const peer = this.e2ee.pairedPeers().find(p => p.identityPub === identity)
        this.core.client(connId, {
          role, label: this.e2ee.sessionLabel(connId), identity, direct: this.directDeviceSinks.has(connId),
          accountOwner: role === 'web' && !!peer && !peer.shared,
          ...(peer?.kind === 'machine' && peer.machineId && !peer.shared ? { machineId: peer.machineId } : {}),
          // Trusted only because this machine is shared: that account's guest, never the owner.
          ...(peer?.shared ? { guest: peer.sharedWith ?? '' } : {}),
        })
      },
      onSessionDropped: (connId) => {
        this.forgetRoutes(connId)
        this.core.client(connId, null)
      },
      onPeerLinked: (peer) => {
        // The mutual half of a password link: a machine that proved this one's password is pinned back,
        // so this machine can dial it without that machine's own password.
        if (peer.kind === 'machine' && peer.machineId && peer.machineId !== this.machineId) {
          new MachinePeerStore().pin(peer.machineId, peer.pub, peer.label)
        }
        this.onPeerLinked?.(peer)
      },
      onUnpaired: (pub) => this.onUnpaired?.(pub),
      onUnknownHello: (pub) => this.onUnknownHello?.(pub) ?? Promise.resolve(),
    })
    this.terminalP2p = new TerminalP2pResponderPool({
      sendSignal: (connId, type, payload) => this.sendP2pSignal(connId, type, payload),
      onData: (connId, data) => this.handleP2pData(connId, data),
      onUnavailable: (connId, reason) => this.demoteP2pConnection(connId, reason),
    })
  }

  // ── the link ───────────────────────────────────────────────────────────────────────────────────

  connect(): void { this.link.connect() }
  serveThisComputerOnly(): void { this.link.serveThisComputerOnly() }
  connected(): boolean { return this.link.isConnected() }

  async stop(): Promise<void> {
    // No reconnect from here on, whatever the socket does while the channels below close.
    this.link.close()
    await this.terminalP2p.stop()
    this.link.stop()
  }

  /** The link went down: no device can be watching, and every remote client went with it. */
  private linkGone(): void {
    // While the backend link is down we can neither observe device presence nor deliver a card, so
    // default the recap gate to OFF (safe value) instead of holding a stale count — otherwise a turn
    // completing during the gap burns a `claude -p` recap that goes nowhere. attachAdapter always
    // re-pushes the true count via recomputeAndSendClients on reconnect (and 0→N re-fires the replay).
    this.core.linkDown()
    this.setCommanderCount(0, null) // active count is unknown until the next __clients snapshot
    void this.terminalP2p.stop()
    this.p2pPendingOpens.clear()
    this.p2pStreams.clear()
    this.liveStreams.clear()
    this.routeCounters.clear()
    this.staleRouteLogged.clear()
    this.replayCommanderOnNextSnapshot = true
    this.tuiUntil = null
    this.uiGate = null
  }

  /** The ONE place commander presence changes. Both callers — the `__clients` snapshot and the link going
   *  down — mean the same thing when the count reaches zero: nobody is watching. They used to differ, and
   *  the link's forgot to drop the device's E2EE session, so `deviceE2eeConnected()` stayed true and the
   *  local dashboard kept a green "device connected" dot for a device long gone. */
  private setCommanderCount(commander: number, active: number | null): void {
    this.commanderCount = commander
    this.commanderActive = active
    this.core.commanders(commander, active)
    if (commander <= 0) {
      if (this.directDeviceSinks.size) this.e2ee.dropSessionsByRole('device', id => this.directDeviceSinks.has(id))
      else this.e2ee.dropSessionsByRole('device')
    }
  }

  holdRequests(): void {
    if (!this.requestsOpen) return
    this.requestsOpen = false
    this.requestGate = new Promise<void>((resolve) => { this.openRequestGate = resolve })
  }

  openRequests(): void {
    if (this.requestsOpen) return
    this.requestsOpen = true
    this.openRequestGate()
  }

  usageLaunch(signal: ProductUsageLaunchSignal): void {
    try { this.productUsage?.launch?.(signal) } catch { /* Optional measurement. */ }
  }

  usageCounter(metric: ProductUsageMetric): void {
    try { this.productUsage?.counter?.(metric) } catch { /* Work never waits for reporting. */ }
  }

  windowOpened(surface: WindowSurface): void {
    try { this.productUsage?.opened(surface) } catch { /* Reporting must not affect the relay. */ }
    this.link.sendAppPresence('open', surface)
  }

  localClients(windows: LocalWindows): void {
    this.localWindows = windows
    try { this.productUsage?.presence(windows.desktop + windows.tui > 0) } catch { /* Reporting is optional. */ }
    for (const surface of WINDOW_SURFACES) if (windows[surface] === 0) this.link.noLocalClients(surface)
  }

  // ── out, to remote clients ───────────────────────────────────────────────────────────────────────

  /** User-content events are group-encrypted (E2EE) here; system frames pass through as plaintext.
   *  [guest]: the guest whose harness the frame is about (the core reads it from the registry). The group
   *  never reaches a guest (manager.ts `groupKeyFor`, backend/src/lib/hub.ts), so its sessions are sent
   *  the frame sealed for each of them. */
  broadcast(frame: Frame, guest?: string): void {
    if ((frame.type === 'turn_started' || frame.type === 'turn_ended' || frame.type === 'text_delta' || frame.type === 'error') && typeof frame.agentId === 'string') {
      const interrupted = frame.type === 'turn_ended' && (frame.payload as { aborted?: unknown } | undefined)?.aborted === true
      try { this.productUsage?.observe(frame.type, frame.agentId, frame.replay === true, interrupted) } catch { /* Work continues without metrics. */ }
    }
    // A created harness whose engine then did not start is announced, not replied: the reply already said
    // created (core/agents/newPane.ts), so these were counted as launches that worked (production counters,
    // 2026-10-16). The core says it to every remote client in this frame; the gateway reads its launch state.
    if (frame.type === 'agent_synced' && this.productUsage?.launchState) {
      try {
        const agent = (frame.payload as { agent?: { id?: unknown; launch?: { state?: unknown; error?: unknown } } } | undefined)?.agent
        const state = agent?.launch?.state
        if (typeof agent?.id === 'string') {
          this.productUsage.launchState(agent.id, state === 'starting' || state === 'ready' || state === 'failed' || state === 'held' ? state : 'other',
            state === 'failed' ? launchErrorCode(agent.launch?.error) : undefined)
        }
      } catch { /* Work continues without metrics. */ }
    }
    if (this.link.servesThisComputerOnly()) return
    if (!this.heldForNoTerminalApp(frame.type) && !this.heldForNoUi(frame.type)) this.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })
    if (guest) {
      for (const connId of this.e2ee.guestSessions(guest)) {
        const sealed = this.e2ee.wrapFor(connId, frame)
        if (sealed) this.link.enqueue({ t: 'up', targetConnId: connId, frame: sealed })
      }
    }
  }

  /** Whether [type] is an event only a terminal app reads and the account has none open now, once the backend has said
   *  (docs/plans/2026-10-31-live-events-relay-design.md, change 5). A guest's own sealed copy is never held. */
  private heldForNoTerminalApp(type: unknown): boolean {
    return this.tuiUntil !== null && Date.now() >= this.tuiUntil && typeof type === 'string' && TUI_ONLY_EVENTS.has(type)
  }

  /** Whether [type] is a live event and no app can see it now: the backend said it may be held and counts none, and no
   *  remote app has sent a frame for a minute. A guest's own sealed copy, and every reply and targeted frame, are never held. */
  private heldForNoUi(type: unknown): boolean {
    return this.uiGate !== null && this.uiGate.ui === 0 && Date.now() - this.uiGate.at < UI_SNAPSHOT_MAX_MS
      && Date.now() - this.lastRemoteFrameAt >= UI_QUIET_MS
      && typeof type === 'string' && UI_GATED_EVENTS.has(type)
  }

  /** The guest a remote connection's session is (gateway/sharedTrust.ts), '' when its store did not
   *  record the account; undefined for everyone else. */
  private guestOf(connId: string): string | undefined {
    const identity = this.e2ee.sessionIdentity(connId)
    if (!identity) return undefined
    const peer = this.e2ee.pairedPeers().find((p) => p.identityPub === identity)
    return peer?.shared ? (peer.sharedWith ?? '') : undefined
  }

  /** A DEVICE-audience frame (commanderEligible, not web). User/data frames are group-encrypted (E2EE)
   *  here so the backend relays only ciphertext; system/presence frames pass through. */
  commander(frame: Frame): void {
    deviceDump.record('out', 'commander', undefined, frame)
    if (this.link.servesThisComputerOnly()) return
    this.link.enqueue({ t: 'up', webEligible: false, commanderEligible: true, frame: this.e2ee.wrapCommander(frame) })
  }

  /** Send a user-level notification to every logged-in browser that owns this machine. */
  user(frame: Frame): void {
    this.link.enqueue({ t: 'up', userEligible: true, webEligible: false, frame })
  }

  /** Send an up-frame to exactly ONE web connection (E2EE pairing/welcome + targeted RPC replies). */
  observer(connId: string, type: string, payload: Record<string, unknown>): boolean {
    return this.link.sendBestEffort({ t: 'up', targetConnId: connId, webEligible: false, commanderEligible: false, frame: { type, payload } })
  }

  /** A frame to one connection as it is: a device's direct link, a window on this computer (an answer to
   *  something it asked here), or the relay. */
  private sendTo(connId: string, frame: Frame): void {
    // Handshake frames only: device RPC, legacy replies and broadcasts are recorded in the clear where built.
    if (typeof frame.type === 'string' && frame.type.startsWith('e2e_') && deviceDump.enabled && this.isDeviceConn(connId)) deviceDump.record('out', 'wire', connId, frame)
    const direct = this.directDeviceSinks.get(connId)
    if (direct) { direct(frame); return }
    // Only its own socket ever reached a window on this computer: the core has it, or it has gone. Queued
    // for the relay, the frame would wait for a connection the backend has never heard of.
    if (isLocalClientId(connId)) { this.core.toLocal(connId, frame); return }
    this.link.enqueue({ t: 'up', targetConnId: connId, frame })
  }

  /** Pairwise-encrypt a connection-targeted non-RPC frame (a viewer's); false with no session or no link. */
  target(connId: string, type: string, payload: Record<string, unknown>): boolean {
    if (!this.connected()) return false
    const frame = this.e2ee.wrapTarget(connId, type, payload)
    if (!frame) return false
    this.sendTo(connId, frame)
    return true
  }

  /** Pairwise terminal output is never queued across reconnect: the stream/lease is closed on link loss. */
  terminal(connId: string, type: string, payload: Record<string, unknown>): boolean {
    const frame = this.e2ee.wrapTarget(connId, type, payload)
    if (!frame) return false
    this.noteLiveStream(connId, type, payload)
    if (this.routeTerminalOutputToP2p(connId, type, payload)) {
      if (this.terminalP2p.send(connId, JSON.stringify(frame))) return true
      this.demoteP2pConnection(connId, 'send_failed')
    }
    return this.link.sendBestEffort({
      t: 'up',
      targetConnId: connId,
      webEligible: true,
      commanderEligible: false,
      frame,
    })
  }

  /** Pairwise-encrypted binary terminal output/keyframe. The hop prefix exposes
   * only connId and direction to the opaque backend relay. */
  terminalBinary(connId: string, clear: TerminalBinaryClear): boolean {
    const clientFrame = this.e2ee.wrapTerminalBinary(connId, clear)
    if (!clientFrame) return false
    if (this.p2pStreams.get(connId)?.has(clear.streamId)) {
      if (this.terminalP2p.send(connId, Buffer.from(clientFrame))) return true
      this.demoteP2pConnection(connId, 'send_failed')
    }
    const packet = encodeTerminalHop(TerminalHopDirection.up, connId, clientFrame)
    if (!packet) return false
    return this.link.sendBinary(packet)
  }

  /**
   * The reply to a remote client's request. For an E2EE-session requester whose result carries user
   * content, the reply is encrypted with that connection's session key and delivered ONLY to it.
   * Content-bearing adapter data is never returned plaintext: even legacy backend nodeRequest
   * (`connId === ''`) gets only an error.
   */
  reply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void {
    const resultType = rpcResultType(type)
    // A window on this computer asked the gateway (`local`): it has the plain reply it always had.
    if (isLocalClientId(connId)) { this.core.toLocal(connId, { type: resultType, payload: { requestId, ...payload } }); return }
    if (connId && deviceDump.enabled && this.e2ee.sessionRole(connId) === 'device') deviceDump.record('out', 'legacy', connId, { type: resultType, payload: { requestId, ...payload } })
    if (connId && this.e2ee.hasSession(connId) && encryptRpcResult(resultType)) {
      let replyPayload = payload
      // ⚠️ The DIAL's frame budget, so only a dial's reply is fitted to it. The phone app and a remote
      // desktop are `web` sessions and search this reply for the agent's latest answer: fitted, a reply
      // over ~15KB dropped to one event without its `fullText`, so any agent doing real work — long
      // answers — could not be found by what it had just said.
      if (resultType === 'agent_recent_result' && this.e2ee.sessionRole(connId) === 'device') {
        const trim = fitRecentReplyPayloadForDevice(
          payload,
          (candidate) => this.e2ee.rpcReplyFrameBytes(connId, resultType, requestId, candidate),
        )
        replyPayload = trim.payload
        if (trim.trimmed) {
          console.warn(
            `[recent-trim] agent=${String(payload.agentId ?? '')} originalFrame=${trim.originalBytes ?? 'unknown'} ` +
            `finalFrame=${trim.finalBytes ?? 'unknown'} target=${DEVICE_RECENT_SAFE_FRAME_BYTES} ` +
            `textBytes=${trim.textBytes} recapBytes=${trim.recapBytes}`,
          )
        }
      }
      const wrapped = this.e2ee.wrapRpcReply(connId, resultType, requestId, replyPayload)
      if (wrapped) { this.sendTo(connId, wrapped); return }
    }
    // Enforcement ("no E2EE ⇒ no adapter data"): a content-bearing reply that could not be sealed is a
    // bare E2EE_REQUIRED, never its content in the clear. Either way it goes to the requester alone:
    // broadcast, a reply went to every web client of this machine and every window on it, though each
    // app takes a reply by its own request id and ignores the rest (ws_conn.dart in the desktop and
    // phone apps, hn's daemon.rs, the CLI's relay pool). The backend's own nodeRequest (`connId === ''`)
    // has no connection to be answered on: it hears the reply on the bus, and fails closed on the error;
    // the windows on this computer hear it too, as they did when it went out with every event.
    const reply = { type: resultType, payload: encryptRpcResult(resultType) ? { requestId, error: 'E2EE_REQUIRED' } : { requestId, ...payload } }
    if (connId) { this.sendTo(connId, reply); return }
    this.core.toLocal('', reply)
    this.broadcast(reply)
  }

  /**
   * Append one entry to the account's device key log, over this machine's own socket — the backend
   * ties a machine's entries to the machine that sent them. Resolves to the backend's answer
   * (`{head}` or `{error, head?}`), or null when it did not come in time.
   */
  appendDeviceLog(entry: Record<string, unknown>, timeoutMs = 15_000): Promise<Record<string, unknown> | null> {
    const requestId = `dl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
    return new Promise((resolve) => {
      const timer = setTimeout(() => { this.devlogAppends.delete(requestId); resolve(null) }, timeoutMs)
      timer.unref?.()
      this.devlogAppends.set(requestId, (payload) => { clearTimeout(timer); resolve(payload) })
      this.link.enqueue({ t: 'up', webEligible: false, frame: { type: 'devlog_append', payload: { requestId, entry } } })
    })
  }

  // ── in, from remote clients ──────────────────────────────────────────────────────────────────────

  /**
   * A client's frame, in its connection's order. P2P signalling has an order of its own: answering an offer
   * awaits a STUN race and ICE gathering (0.1–0.7s, 5s behind a dead STUN server), and in line with the
   * rest it held every frame the client sent after it. An offer and its candidates still go one at a time,
   * so a candidate never reaches a responder its offer has not built yet; a disconnect racing an offer is
   * the pool's to settle (`offerSeq`, `stillCurrent`).
   */
  private enqueueDown(frame: Frame, connId: string, transport: RemoteTransport): void {
    const key = connId || '__backend__'
    const chains = TERMINAL_P2P_SIGNAL_TYPES.has(frame.type as string) ? this.signalChains : this.downChains
    const previous = chains.get(key) ?? Promise.resolve()
    const next = previous
      .catch(() => { /* prior failure is already logged */ })
      .then(() => this.requestGate)
      .then(() => this.dispatchDown(frame, connId, transport))
      .catch((err) => {
        console.error('[backend] down-frame dispatch failed:', err instanceof Error ? err.message : err)
      })
      .finally(() => {
        if (chains.get(key) === next) chains.delete(key)
      })
    chains.set(key, next)
  }

  /**
   * A client's terminal bytes (keystrokes, a paste, an upload's chunks): opened as they arrive, in the order
   * they arrive, and handed to the core at once. They used to wait in line behind the connection's JSON
   * frames, and with them behind whatever those awaited: a P2P offer's answer here, and in one process
   * (`HARNESSD_SERVICES=none`) the core's own handling of each frame, a resize's keyframe included.
   * Nothing a JSON frame does is a precondition for a keystroke: a stream exists only once the client was
   * told so (`terminal_ready`), the session that opens these bytes only once it was welcomed, and the
   * core keeps each stream's bytes in their order (backendSocket.ts `enqueueTerminalBinary`). Opened here
   * rather than later, a hello that replaces this connection's session cannot leave the bytes sealed under
   * the old one unopenable.
   */
  private enqueueTerminalBinary(connId: string, raw: Uint8Array, via: RemoteTransport = 'relay'): void {
    try {
      const clear = this.e2ee.unwrapTerminalBinary(connId, raw)
      if (!clear) { const gone = this.e2ee.terminalSessionGone(connId, raw); if (gone) this.sendTo(connId, gone); return }
      if (env.TYPING_TRACE && (clear.kind === TerminalBinaryKind.input || clear.kind === TerminalBinaryKind.paste)) {
        console.log(`[typing] in conn=${sid(connId)} stream=${sid(clear.streamId)} ${clear.kind === TerminalBinaryKind.paste ? 'paste' : `seq=${clear.seq}`} ${clear.bytes.length}B via=${via}`)
      }
      void Promise.resolve(this.core.binary(connId, clear)).catch((err) => {
        console.error('[backend] binary terminal dispatch failed:', err instanceof Error ? err.message : err)
      })
    } catch (err) {
      console.error('[backend] binary terminal dispatch failed:', err instanceof Error ? err.message : err)
    }
  }

  /**
   * One frame from the relay or a client's P2P channel, in its connection's order. What the gateway
   * answers itself (the handshake, the backend's control frames, the pairings) it answers here; a client's
   * request goes on to the core opened, with the role of the session it opened under.
   */
  async dispatchDown(frame: Frame, connId: string, transport: RemoteTransport = 'relay'): Promise<void> {
    const type = frame.type as string | undefined
    if (!type) return
    // A relayed connection never names a window on this computer: the backend's connection ids are its
    // own UUIDs (backend/src/lib/hub.ts), and a window's is minted by the local socket. Read as local, a
    // relayed frame on a live window's id would take that window's trust; the gateway never lets one
    // that far.
    if (isLocalClientId(connId)) {
      console.warn(`[backend] ignoring ${logSafeType(type)} from ${transport} on a local connection id`)
      return
    }
    // ⚠️ The backend's own instructions, refused from anywhere else. See BACKEND_ONLY_DOWN_TYPES.
    // `transport === 'relay'` rather than "not local", so this keeps holding if the p2p allowlist
    // (`TERMINAL_P2P_DOWN_TYPES`) ever widens.
    //
    // Deliberately ABOVE the observer hand-off below. A genuine observer frame is `relay`, so this
    // never intercepts one; but placed after it, a forged `observer:` connId on a p2p frame would be
    // swallowed by Share and returned without ever reaching this line — silently, with no warning. The
    // grid-name incident was exactly a bypass nobody could see.
    if (transport !== 'relay' && BACKEND_ONLY_DOWN_TYPES.has(type)) {
      console.warn(`[backend] ignoring ${type} from ${transport} (${connId}) — only the backend may send it`)
      return
    }
    if (connId.startsWith('observer:')) {
      await this.core.observer(connId, type, (frame.payload ?? {}) as Record<string, unknown>)
      return
    }
    if (type.startsWith('observer_')) return
    // An app that connects sends its E2EE hello first, before the backend's next `__clients` counts it: live events flow
    // again from that frame on, so it misses nothing it could open. The backend's own frames (connId '' or `__`) and a
    // device's are no app viewing. A reconnecting device's hello, before it is known as one, opens it for a minute.
    if (connId && !type.startsWith('__') && !this.isDeviceConn(connId)) this.lastRemoteFrameAt = Date.now()
    // E2EE control frames (pairing/handshake) are handled by the manager, never as node RPCs.
    if (type.startsWith('e2e_')) {
      const deviceBefore = deviceDump.enabled && (this.isDeviceConn(connId) || (type === 'e2e_pair_intent' && (frame.payload as { role?: unknown } | undefined)?.role === 'device'))
      if (deviceBefore) deviceDump.record('in', 'wire', connId, frame)
      this.e2ee.handleFrame(connId, frame)
      // A reconnecting device is only known as one once its hello has been accepted.
      if (!deviceBefore && deviceDump.enabled && this.isDeviceConn(connId)) deviceDump.record('in', 'wire', connId, frame)
      return
    }
    if (type === 'autonomous_device_request') {
      await this.deviceRequest(connId, frame)
      return
    }
    // ⚠️ Default-deny: the relay is NOT trusted. A frame is acted on only if it opens under this connId's
    // E2EE session — whatever its type — or is one of the backend's own plaintext frames. A list of
    // "sensitive" types to check instead fails open: every type missing from it, including ones added
    // later, would be taken in the clear.
    //
    // The backend's own control frames are the mirror image: only ever plaintext, because the backend
    // holds no key — so one that arrives SEALED was sealed by a paired client, and opening it would let
    // that client speak as the backend (`machine_meta` repoints this computer's grid).
    const from = `${transport} (${connId ? `conn:${sid(connId)}` : 'backend'})`
    const wrapped = isWrapped(frame.payload)
    if (type.startsWith('__') || BACKEND_ONLY_DOWN_TYPES.has(type)) {
      // And only on the backend's OWN address: it sends these with `connId: ''`, while every frame a
      // client sends arrives stamped with that client's connId — so a client-shaped one was relayed, not
      // written by the backend, whichever socket let it through. `__client_disconnected` is the one the
      // hub addresses to a client's own connId; it only tears down that connection's state.
      if (transport !== 'relay' || wrapped || (connId !== '' && type !== '__client_disconnected')) {
        console.warn(`[backend] ignoring ${logSafeType(type)} from ${from} — only the backend sends it, and only in the clear`)
        return
      }
      if (deviceDump.enabled && this.e2ee.sessionRole(connId) === 'device') deviceDump.record('in', 'legacy', connId, frame)
      this.logRequest(connId, frame)
      await this.backendControl(type, frame, connId)
      return
    }
    if (!wrapped) {
      console.warn(`[backend] refusing plaintext ${logSafeType(type)} from ${from} — E2EE required`)
      const requestId = (frame.payload as { requestId?: unknown } | undefined)?.requestId
      if (requestId !== undefined) this.reply(connId, type, requestId, { error: 'E2EE_REQUIRED' })
      return
    }
    const opened = this.e2ee.unwrapDown(connId, frame)
    // Sealed for a session this process never had: told, rather than dropped without a word.
    if (!opened) { const gone = this.e2ee.sessionGone(connId, frame); if (gone) this.sendTo(connId, gone); return }
    // Opened under this connection's session, so it has one: its role is who asked.
    const role = this.e2ee.sessionRole(connId) as RemoteRole
    if (deviceDump.enabled && role === 'device') deviceDump.record('in', 'legacy', connId, opened)
    if (TERMINAL_P2P_SIGNAL_TYPES.has(type)) {
      await this.terminalP2p.handleSignal(connId, type, opened.payload)
      return
    }
    const payload = (opened.payload ?? {}) as Record<string, unknown>
    // A guest manages none of this machine's pairings and is no member of its trust group
    // (docs/plans/2026-10-19-guest-machine-sharing-plan.md): the rest it asks, the core decides.
    if ((type === 'group_sync' || GATEWAY_REQUEST_TYPES.has(type)) && this.guestOf(connId) !== undefined) {
      this.logRequest(connId, opened)
      this.reply(connId, type, payload.requestId, { error: 'GUEST_NOT_ALLOWED' })
      return
    }
    // Trust-group roster exchange: only over an E2EE session, from the identity that session proved —
    // the roster carries the keys this machine trusts, and the peer's own entry must be that identity.
    if (type === 'group_sync') {
      this.logRequest(connId, opened)
      const peerPub = this.e2ee.sessionIdentity(connId)
      if (!peerPub || role !== 'web' || !this.groupSync) { this.reply(connId, type, payload.requestId, { error: 'UNSUPPORTED' }); return }
      try { this.reply(connId, type, payload.requestId, this.groupSync.handle(peerPub, payload)) } catch { this.reply(connId, type, payload.requestId, { error: 'GROUP_SYNC_FAILED' }) }
      return
    }
    if (GATEWAY_REQUEST_TYPES.has(type)) {
      this.logRequest(connId, opened)
      await this.manage(connId, type, payload)
      return
    }
    // `unwrapDown` opened it, so its envelope counter is a number.
    if (type.startsWith('terminal_')) this.noteTerminalInputRoute(connId, type, payload, transport, (frame.payload as WrappedPayload).__e2e.n)
    await this.core.frame(connId, opened, transport, role)
  }

  /** The backend's own control frames, checked by the caller: in the clear, over the relay, on its own address. */
  private async backendControl(type: string, frame: Frame, connId: string): Promise<void> {
    // Cross-instance client snapshot. Generation detects leave/join cycles that coalesce to the same
    // count; count rise remains the compatibility fallback for older backends.
    if (type === '__clients') {
      const payload = (frame.payload ?? {}) as { ui?: number; commander?: number; commanderActive?: number; commanderJoinGeneration?: number; uiGate?: unknown }
      // A count that is no number is never 0, so it holds nothing.
      this.uiGate = payload.uiGate === true ? { ui: Number(payload.ui ?? 0), at: Date.now() } : null
      const commander = Number(payload.commander ?? 0)
      const rawGeneration = payload.commanderJoinGeneration
      const generation = typeof rawGeneration === 'number' && Number.isSafeInteger(rawGeneration) && rawGeneration >= 0
        ? rawGeneration
        : undefined
      const replay = shouldReplayCommander(
        this.commanderCount,
        commander,
        this.replayedCommanderGeneration,
        generation,
        this.replayCommanderOnNextSnapshot,
      )
      this.setCommanderCount(commander, payload.commanderActive != null ? Number(payload.commanderActive) : null)
      if (replay) {
        this.replayCommanderOnNextSnapshot = false
        if (generation != null) this.replayedCommanderGeneration = generation
        this.core.commanderJoined()
      }
      return
    }
    // A terminal app of the account is open for `forMs` (backend bus.ts noteTuiPresence), or none is (0).
    if (type === '__tui_open') {
      const forMs = Number((frame.payload as { forMs?: unknown } | undefined)?.forMs)
      this.tuiUntil = Date.now() + (Number.isFinite(forMs) && forMs > 0 ? Math.min(forMs, TUI_OPEN_MAX_MS) : 0)
      return
    }
    if (type === '__client_disconnected') {
      // The backend is authoritative for the outer connId. Drop both kinds of
      // connection-scoped state immediately; otherwise a dead Desktop keeps a
      // terminal controller lease until the 30-second heartbeat timeout.
      this.deviceClients.delete(connId)
      this.e2ee.dropSession(connId)
      await this.terminalP2p.closeConnection(connId, 'client_disconnected', false)
      this.p2pPendingOpens.delete(connId)
      this.p2pStreams.delete(connId)
      this.liveStreams.delete(connId)
      this.forgetRoutes(connId)
      await this.core.disconnected(connId)
      return
    }
    // A Lead's terminal request waits for an agent of this machine (spec 2026-11-02-poll-cost Part 4.2): the Swarm host picks
    // it up now. A `__` frame, so a daemon from before it drops it below; one naming no agent is no request.
    if (type === '__terminal_waiting') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
      if (typeof p.tabId === 'string' && typeof p.agentId === 'string') this.core.notice({ type, tabId: p.tabId, agentId: p.agentId })
      return
    }
    // The server renews the Swarm host's delivery push lease (task #2800, review of #2977): nothing to read, the host only
    // keeps reading idle workers' lists when told. A `__` frame, so a daemon from before it drops it below.
    if (type === '__deliveries_lease') {
      this.core.notice({ type })
      return
    }
    // Other backend-hub internal control frames (__clients_dirty) — not for us; drop silently.
    if (type.startsWith('__')) return

    // The machine was deleted/revoked from the web → stop for good (don't reconnect) and let the CLI
    // clear the saved token. Closing the link blocks the reconnect that would otherwise fire on socket drop.
    if (type === 'machine_revoked') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as { reason?: unknown; pub?: unknown }
      // Another key under this machine id was removed — an earlier install of this computer that this one
      // waits behind (`device_conflict`). The frame goes to the machine id, so it reaches this install too:
      // that removal is what lets this key register, not a sign-out. Re-read the log instead.
      if (p.reason === 'device_removed' && typeof p.pub === 'string' && this.isOwnDeviceKey && !this.isOwnDeviceKey(p.pub)) {
        this.onDeviceKeysChanged?.()
        return
      }
      this.link.close()
      // Removed from the account's device key log (not just signed out): the key itself is spent.
      if (p.reason === 'device_removed' && typeof p.pub === 'string') {
        try { this.onDeviceRemoved?.(p.pub) } catch { /* signing out still happens */ }
      }
      this.core.revoked()
      return
    }

    // The account's tabs changed on another computer (or in another window of this one): hand the
    // window the revision and let it fetch `/api/desk` through this daemon. Backend-only, like
    // machine_meta — a local client cannot make the window re-read anything by sending this.
    if (type === 'desk_changed' || type === 'zoo_changed') {
      const revision = (typeof frame.payload === 'object' && frame.payload !== null ? (frame.payload as { revision?: unknown }).revision : undefined)
      this.core.notice({ type, revision: typeof revision === 'number' ? revision : 0 })
      return
    }

    // The account's sealed connections changed (backend routes/connectorVault.ts): the connectors service
    // re-reads and merges them. Backend-only, like desk_changed.
    if (type === 'connectors_changed') {
      const revision = (typeof frame.payload === 'object' && frame.payload !== null ? (frame.payload as { revision?: unknown }).revision : undefined)
      this.core.notice({ type, revision: typeof revision === 'number' ? revision : 0 })
      return
    }

    // Work waits for an agent of this machine's (backend lib/adapterWs.ts): the Swarm host reads its deliveries now. Naming
    // none, the server says it pushes them. Backend-only like desk_changed: a client could only make the host read early.
    if (type === 'super_tab_deliveries') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
      this.core.notice(typeof p.tabId === 'string' && typeof p.agentId === 'string'
        ? { type, tabId: p.tabId, agentId: p.agentId } : { type })
      return
    }

    // A commit changed what this machine's Swarm host reads (backend lib/swarmHostPushes.ts): it reads its changes now.
    // Naming none, the server says it pushes them. Backend-only like desk_changed: a client could only make the host read early.
    if (type === 'swarm_host_changed') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
      this.core.notice(typeof p.tabId === 'string' && typeof p.lastChangedAt === 'number'
        ? { type, tabId: p.tabId, lastChangedAt: p.lastChangedAt } : { type })
      return
    }

    // A Swarm the account is in changed (backend lib/swarmClientPushes.ts): the windows read it again. Naming none, the server
    // says it pushes. Backend-only like desk_changed: a client could only make a window read early.
    if (type === 'swarm_changed') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
      const parts = Array.isArray(p.parts) && p.parts.length && p.parts.every(part => part === 'main' || part === 'machine') ? p.parts as Array<'main' | 'machine'> : null
      this.core.notice(typeof p.tabId === 'string' && typeof p.lastChangedAt === 'number' && parts
        ? { type, tabId: p.tabId, lastChangedAt: p.lastChangedAt, parts } : { type })
      return
    }

    // The account's device key log grew: this daemon re-reads and verifies it (deviceLogSyncer.ts), and
    // the window re-reads its Devices list. Backend-only for the same reason as desk_changed.
    if (type === 'device_keys_changed') {
      this.onDeviceKeysChanged?.()
      this.core.notice({ type: 'device_keys_changed' })
      return
    }
    // The backend's answer to this machine's own append to the device key log.
    if (type === 'devlog_append_result') {
      const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
      const done = typeof p.requestId === 'string' ? this.devlogAppends.get(p.requestId) : undefined
      if (done) { this.devlogAppends.delete(p.requestId as string); done(p) }
      return
    }

    // The account's machine list changed on some worker — a machine created / renamed / deleted, or a
    // shared harness invited / taken back. The window re-reads `/api/machines` through this daemon; this
    // push is why it does not have to poll for that. Backend-only for the same reason as desk_changed.
    if (type === 'machines_changed') {
      const reason = (typeof frame.payload === 'object' && frame.payload !== null ? (frame.payload as { reason?: unknown }).reason : undefined)
      this.core.notice({ type: 'machines_changed', reason: typeof reason === 'string' ? reason : 'updated' })
      return
    }

    // Machine display name (seed on connect + web renames) — mirrored locally for `harness status`.
    if (type === 'machine_meta') {
      // ⚠️ The BACKEND's frame and nobody else's. It carries this machine's display name and, more
      // to the point, the account's private grid — the grid every agent on this computer is then
      // pointed at. Accepted from any transport, it let a process that could open the daemon's local
      // port redirect the account's inference somewhere of its choosing, and a leftover test script
      // doing exactly that by accident cost hours to find. No client sends this frame; there is
      // nothing to be compatible with. The source check is in the caller.
      //
      // A malformed/hostile frame's payload need not be an object; `'gridName' in meta` would throw
      // on a primitive (and drop the whole frame). Guard the type first, the way the plain property
      // reads elsewhere in this dispatcher tolerate one.
      const meta = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as { name?: unknown; gridName?: unknown }
      // The account's private grid, pushed on connect. Held in memory only: it is the backend's
      // value, and a daemon that cached it on disk would keep answering with a stale one after the
      // account's grid changed. Only ACT on the key when it is present: the connect frame always
      // carries it (a string or null), but a rename pushes `{name}` alone — and treating that
      // absence as null used to WIPE a grid name a moment after it was set, leaving the picker
      // empty. Absent ⇒ unchanged; null ⇒ this account has none; a string ⇒ that grid.
      const said: { name?: string | null; gridName?: string | null } = {}
      if ('gridName' in meta) said.gridName = typeof meta.gridName === 'string' && meta.gridName.trim() ? meta.gridName.trim() : null
      // The same rule for the name: a frame that does not carry it leaves it as it was.
      if ('name' in meta) said.name = typeof meta.name === 'string' && meta.name.trim() ? meta.name.trim() : null
      this.core.meta(said)
    }
  }

  /** A request the gateway answers itself, logged as the core logs the ones it answers. */
  private logRequest(connId: string, frame: Frame): void {
    const type = String(frame.type)
    if (env.LOG_FRAMES && type !== 'phone_pair' && !type.startsWith('pair')) logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)
  }

  /** A local connection's E2EE management request, handed over by the core. */
  async local(connId: string, frame: Frame): Promise<void> {
    const type = typeof frame.type === 'string' ? frame.type : ''
    if (!GATEWAY_REQUEST_TYPES.has(type)) return
    await this.manage(connId, type, (frame.payload ?? {}) as Record<string, unknown>)
  }

  /** The E2EE management requests (GATEWAY_REQUEST_TYPES), from a remote client or a window here. */
  private async manage(connId: string, type: string, payload: Record<string, unknown>): Promise<void> {
    try {
      switch (type) {
        case 'device_e2ee_pair':
          await this.e2ee.pairDeviceFromTrustedWeb(connId, payload)
          return
        case 'phone_pair':
          // CPace waits for another connection. Do not block this browser's terminal queue.
          void this.e2ee.pairPhoneFromTrustedWeb(connId, payload)
          return
        case 'e2ee_pairings_list':
          this.reply(connId, type, payload.requestId, { pairs: this.e2ee.listPaired(connId) })
          return
        case 'e2ee_pairing_unpair':
          this.e2ee.revokeFromTrustedWeb(connId, payload)
          return
        default: // e2ee_pairings_unpair_all
          this.e2ee.revokeAllFromTrustedWeb(connId, payload.requestId)
          return
      }
    } catch (err) {
      console.error(`[backend] dispatch ${type} failed:`, err)
      if (payload.requestId !== undefined) this.reply(connId, type, payload.requestId, { error: 'INTERNAL' })
    }
  }

  // ── P2P terminal channels ────────────────────────────────────────────────────────────────────────

  private sendP2pSignal(connId: string, type: string, payload: TerminalP2pSignal): void {
    const frame = this.e2ee.wrapTarget(connId, type, { ...payload })
    if (frame) this.sendTo(connId, frame)
  }

  private handleP2pData(connId: string, data: TerminalP2pData): void {
    if (typeof data === 'string') {
      if (Buffer.byteLength(data, 'utf8') > 512 * 1024) return
      let frame: Frame
      try { frame = JSON.parse(data) as Frame } catch { return }
      if (typeof frame.type !== 'string' || !TERMINAL_P2P_DOWN_TYPES.has(frame.type)) return
      this.enqueueDown(frame, connId, 'p2p')
      return
    }
    if (data.length > 512 * 1024) return
    this.enqueueTerminalBinary(connId, data, 'p2p')
  }

  /** What the core has told a remote client about its terminal streams: one opened, one closed. */
  private noteLiveStream(connId: string, type: string, payload: Record<string, unknown>): void {
    const streamId = typeof payload.streamId === 'string' ? payload.streamId : ''
    if (!streamId) return
    if (type === 'terminal_ready') {
      let streams = this.liveStreams.get(connId)
      if (!streams) { streams = new Set(); this.liveStreams.set(connId, streams) }
      streams.add(streamId)
    } else if (type === 'terminal_closed') {
      const streams = this.liveStreams.get(connId)
      streams?.delete(streamId)
      if (streams?.size === 0) this.liveStreams.delete(connId)
      this.forgetRoutes(connId, streamId)
    }
  }

  /**
   * Which wire a client's frame says its stream's output should ride, read from the frame's E2EE
   * [counter] — see `routeCounters`. Only a frame sealed AFTER the decision in force can change it:
   * - a `terminal_resync` over P2P moves a live stream onto P2P (live migration: remoteRelay.ts and the
   *   phone send a SECOND resync over the channel once it is ready, after the first, over the relay,
   *   drained and snapshotted the stream). The live-stream check guards against promoting a streamId
   *   whose pane was closed in the same instant the migration was in flight;
   * - any `terminal_*` frame for the stream over the relay moves it back: a client demotes with a relay
   *   resync, or, for one stream, by simply sending its next frame (an ack, `terminal_alive`) over the relay.
   * A relay frame sealed before the stream moved onto P2P changes nothing, and neither does a P2P frame
   * sealed before the client moved it back.
   */
  private noteTerminalInputRoute(
    connId: string,
    type: string,
    payload: Record<string, unknown>,
    transport: RemoteTransport,
    counter: number,
  ): void {
    if (type === 'terminal_open' && typeof payload.requestId === 'string') {
      let pending = this.p2pPendingOpens.get(connId)
      if (!pending) { pending = new Map(); this.p2pPendingOpens.set(connId, pending) }
      if (transport === 'p2p') pending.set(payload.requestId, counter)
      else pending.delete(payload.requestId)
      return
    }
    const streamId = typeof payload.streamId === 'string' ? payload.streamId : ''
    // Only a stream the core told this client it has has a route to decide (and a counter worth keeping).
    if (!streamId || !this.liveStreams.get(connId)?.has(streamId)) return
    const decided = this.routeCounters.get(connId)?.get(streamId) ?? -1
    if (counter <= decided) {
      if (transport !== 'p2p' && this.p2pStreams.get(connId)?.has(streamId)) this.logStaleRoute(connId, streamId, type, counter, decided)
      return
    }
    if (type === 'terminal_resync' && transport === 'p2p') {
      this.routeToP2p(connId, streamId, counter, 'terminal_resync')
      return
    }
    if (transport === 'p2p') return
    this.decideRoute(connId, streamId, counter)
    if (this.p2pStreams.get(connId)?.delete(streamId)) {
      if (this.p2pStreams.get(connId)!.size === 0) this.p2pStreams.delete(connId)
      console.log(`[terminal-p2p] conn=${sid(connId)} stream=${sid(streamId)} route=relay by=${logSafeType(type)} n=${counter}`)
    }
  }

  private routeToP2p(connId: string, streamId: string, counter: number, by: string): void {
    this.decideRoute(connId, streamId, counter)
    this.staleRouteLogged.delete(`${connId}\0${streamId}`)
    let streams = this.p2pStreams.get(connId)
    if (!streams) { streams = new Set(); this.p2pStreams.set(connId, streams) }
    if (streams.has(streamId)) return
    streams.add(streamId)
    console.log(`[terminal-p2p] conn=${sid(connId)} stream=${sid(streamId)} route=p2p by=${by} n=${counter}`)
  }

  private decideRoute(connId: string, streamId: string, counter: number): void {
    let streams = this.routeCounters.get(connId)
    if (!streams) { streams = new Map(); this.routeCounters.set(connId, streams) }
    streams.set(streamId, counter)
  }

  /** A relay frame sealed before its stream moved onto P2P, kept from undoing the move: said once per move. */
  private logStaleRoute(connId: string, streamId: string, type: string, counter: number, decided: number): void {
    const key = `${connId}\0${streamId}`
    if (this.staleRouteLogged.has(key)) return
    this.staleRouteLogged.add(key)
    console.log(`[terminal-p2p] conn=${sid(connId)} stream=${sid(streamId)} kept on p2p: relay ${logSafeType(type)} n=${counter} was sealed before the move (n=${decided})`)
  }

  /** Forget the routing decisions for one stream, or for every stream of a connection. */
  private forgetRoutes(connId: string, streamId?: string): void {
    if (streamId === undefined) {
      this.routeCounters.delete(connId)
      for (const key of this.staleRouteLogged) if (key.startsWith(`${connId}\0`)) this.staleRouteLogged.delete(key)
      return
    }
    const streams = this.routeCounters.get(connId)
    streams?.delete(streamId)
    if (streams?.size === 0) this.routeCounters.delete(connId)
    this.staleRouteLogged.delete(`${connId}\0${streamId}`)
  }

  private routeTerminalOutputToP2p(connId: string, type: string, payload: Record<string, unknown>): boolean {
    const requestId = typeof payload.requestId === 'string' ? payload.requestId : ''
    const streamId = typeof payload.streamId === 'string' ? payload.streamId : ''
    const pending = this.p2pPendingOpens.get(connId)
    const openedAt = requestId ? pending?.get(requestId) : undefined
    if ((type === 'terminal_ready' || type === 'terminal_error') && openedAt !== undefined) {
      pending!.delete(requestId)
      if (pending!.size === 0) this.p2pPendingOpens.delete(connId)
      if (type === 'terminal_ready' && streamId) this.routeToP2p(connId, streamId, openedAt, 'terminal_open')
      return true
    }
    const streams = this.p2pStreams.get(connId)
    const selected = !!streamId && streams?.has(streamId) === true
    if (selected && type === 'terminal_closed') {
      streams!.delete(streamId)
      if (streams!.size === 0) this.p2pStreams.delete(connId)
    }
    return selected
  }

  private demoteP2pConnection(connId: string, reason: string): void {
    this.p2pPendingOpens.delete(connId)
    this.p2pStreams.delete(connId)
    this.forgetRoutes(connId)
    console.warn(`[terminal-p2p] conn=${sid(connId)} fallback=relay reason=${reason}`)
  }

  // ── the Wi-Fi device's direct links, which ride the same E2EE sessions ──────────────────────────

  /** A connection that is, or is pairing as, an Autonomous device — what the device dump records. */
  private isDeviceConn(connId: string): boolean {
    return this.directDeviceSinks.has(connId) || this.e2ee.sessionRole(connId) === 'device'
      || (this.e2ee.pendingConnection() === connId && this.e2ee.pendingPair()?.role === 'device')
  }
  attachDirectDevice(connId: string, send: (frame: Frame) => void): void { this.directDeviceSinks.set(connId, send) }
  detachDirectDevice(connId: string): void {
    this.directDeviceSinks.delete(connId); this.directDevicePins.delete(connId); this.deviceClients.delete(connId); this.e2ee.dropSession(connId)
    void this.core.disconnected(connId)
    this.core.commanders(this.commanderCount, this.commanderActive, true)
  }
  pairedDirectFingerprint(connId: string): string | null { const pub = this.directDevicePins.get(connId); return pub ? fingerprint(b64d(pub)) : null }
  async receiveDirectDevice(connId: string, frame: Frame, pairingAllowed: boolean): Promise<void> {
    if (!this.directDeviceSinks.has(connId)) return
    const type = frame.type
    if (type !== 'autonomous_device_request') deviceDump.record('in', 'wire', connId, frame) // requests: decrypted in the relay
    if (type === 'machine_selected') return
    if (type === 'autonomous_device_request') { await this.deviceRequest(connId, frame); return }
    const controls = pairingAllowed ? ['e2e_pair_intent', 'e2e_pair_cancel', 'e2e_pake', 'e2e_hello', 'e2e_status'] : ['e2e_hello', 'e2e_status']
    if ((type === 'e2e_pake' || type === 'e2e_pair_cancel') && this.e2ee.pendingConnection() !== connId) return
    if (typeof type === 'string' && controls.includes(type)) this.e2ee.handleFrame(connId, frame)
  }

  /**
   * A Wi-Fi device's request, for the device service's relay in the core (lib/autonomous-device/relay.ts),
   * opened here under the session that sealed it. Opened only when the relay would open it (a device's
   * session, a sealed frame, no session id beside it), so its replay window moves exactly as it did when
   * the relay opened the frame itself.
   */
  private async deviceRequest(connId: string, frame: Frame): Promise<void> {
    const opens = !!this.e2ee.sessionIdentity(connId) && this.e2ee.sessionRole(connId) === 'device' && isWrapped(frame.payload) && frame.dbSessionId === undefined
    await this.core.device(connId, frame, opens ? this.e2ee.unwrapDown(connId, frame) : null)
  }

  /** The device service's answer or event for one Wi-Fi device session, sealed to it. */
  device(connId: string, type: string, payload: Record<string, unknown>): boolean {
    const wrapped = this.e2ee.wrapTarget(connId, type, payload)
    if (!wrapped) return false
    this.sendTo(connId, wrapped)
    return true
  }

  deviceClient(connId: string, identity: string | null): void {
    if (identity) this.deviceClients.set(connId, identity)
    else this.deviceClients.delete(connId)
  }

  /**
   * App-side revoke: tell the device while its authenticated session still exists (the E2eeManager drops
   * the session right after this), so it clears its own pin instead of showing "paired / disconnected"
   * forever. The device service's relay did this itself when it shared this process; the core is now a
   * frame away, and the session would be gone by the time it answered, so the gateway sends the same frame
   * to the same sessions here, and the service hears of the unpairing once they are gone. Best-effort: a
   * device that is offline learns it on reconnect, when its e2e_hello gets e2e_denied.
   */
  private deviceUnpaired(identity: string): void {
    for (const [connId, client] of [...this.deviceClients]) {
      if (client !== identity) continue
      this.deviceClients.delete(connId)
      if (this.e2ee.sessionIdentity(connId) !== identity || this.e2ee.sessionRole(connId) !== 'device') continue
      const event = { type: 'pair.revoke', machineId: this.machineId }
      try {
        deviceDump.record('out', 'rpc', connId, { type: 'autonomous_device_event', payload: event })
        this.device(connId, 'autonomous_device_event', event)
      } catch { /* Local removal must proceed regardless. */ }
    }
    // After the sessions are dropped, which the manager does once this returns: the service's relay then
    // finds none left to tell, and only forgets the identity.
    setImmediate(() => this.core.deviceRevoked(identity))
  }

  // ── the pairings, for the daemon's own commands (`harness pair`, `unpair`, `remote-password`, …) ──

  /** True after a paired device has completed the E2EE hello/welcome session. */
  deviceE2eeConnected(): boolean { return this.e2ee.deviceConnected() }
  /** A browser waiting to pair (`/api/status`), or null. */
  pendingPair(): ReturnType<E2eeManager['pendingPair']> { return this.e2ee.pendingPair() }
  /** Run CPace pairing for a code entered via `harness pair <code>` (delegated to the manager). */
  pair(code: string): Promise<PairResult> { return this.e2ee.onPair(code) }
  fingerprint(): string { return this.e2ee.fingerprint() }
  /** `harness pairings` — list paired clients. */
  listPairs(): ReturnType<E2eeManager['listPaired']> { return this.e2ee.listPaired() }
  /** `harness unpair <id>` — unpair one client (signals it to re-pair if online). */
  revoke(id: string): ReturnType<E2eeManager['revoke']> { return this.e2ee.revoke(id) }
  /** `harness unpair --all` — unpair every client. */
  revokeAll(): ReturnType<E2eeManager['revokeAll']> { return this.e2ee.revokeAll() }
  /** `harness remote-password set` — stretch + persist a new persistent remote password. */
  setRemotePassword(password: string): ReturnType<E2eeManager['setRemotePassword']> { return this.e2ee.setRemotePassword(password) }
  /** `harness remote-password clear` — remove the persistent remote password. */
  clearRemotePassword(): void { this.e2ee.clearRemotePassword() }
  /** `harness link connect` — trust the machine this one just linked as a client too (mutual link). */
  trustPeer(peer: LinkedPeer): void { this.e2ee.trustPeer(peer) }
  /** Stop trusting `pub` here (unlink / trust-group removal); true when it was trusted. */
  untrustPeer(pub: string): boolean { return this.e2ee.untrustPeer(pub) }
  pairedPeers(): ReturnType<E2eeManager['pairedPeers']> { return this.e2ee.pairedPeers() }
  /** `harness remote-password status` — whether one is set, and its fingerprint. */
  remotePasswordStatus(): ReturnType<E2eeManager['remotePasswordStatus']> { return this.e2ee.remotePasswordStatus() }
}