Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

33.2 KB
Raw Blame
// The JOIN POINT on the host (docs/remote-sessions.md 4c): once two humans have mutually approved
// each other, the bridged peer becomes a FIRST-CLASS CorePlatform client of this core.
//
// There is very little code here on purpose. The platform is multi-client (a client is a webContents
// OR a UiSink in a peer registry), and Stages 1-3 wrote presence, the canvas reflector and terminal
// co-attach against CorePlatform. So the whole of "a remote desktop opens as a project tab" reduces
// to: mint one ClientId, register one sink, join presence, and route the encrypted tunnel into
// `dispatch` / `cast`. Everything else just works (src/main/peer-integration.test.ts proved it
// against a fake sink; this module supplies the socket).
//
// THE SEAM. Everything shell-specific — minting the ClientId, the peer registry, the presence join,
// the platform's dispatch/cast and where a mutual approval is pinned — arrives through `PeerAttach`
// and `PinStore`, so the desktop's Team Access (src/main/remote/relay-host.ts) and the Server
// Edition's hosted team relay (docs/hosted-team-relay.md) run this ONE handshake + tunnel. The
// optional `RelayHostHooks` let a host that serves several roles answer, refuse, narrow or filter
// per session; a host that passes none (the desktop) takes exactly the unhooked path.
//
// It is the relay twin of `src/server/ws.ts`, and it deliberately mirrors that file's shape: attach
// the sink, join the hub, req → dispatch → respond, cast → cast, and on close run the ONE teardown
// (leave → dropClient → prune). Divergence between the two remote surfaces is a bug.
//
// SECURITY — nothing is served before MUTUAL approval. The peer is registered (and therefore able to
// reach any channel the shell registered on the platform) only from the trust gate's `onOpen`, i.e.
// after BOTH humans compared the same SAS and pressed Confirm. The E2EE handshake completing
// (`onReady`) proves only that SOMEONE holds the pairing token — a pre-approval request is answered
// with E_UNAUTHORIZED and never touches a handler. Between mutual approval and `onOpen` (the pin
// write is in flight) the peer's frames are HELD, not refused, and served at open through the same
// checks as live ones — still nothing before it (see HELD_FRAMES_MAX). A pairing grants shell
// access; the SAS is the only thing between a relay MITM and that shell.
//
// SCOPE: this is the DESKTOP-peer vocabulary (the invited peer is fully trusted, as the invite copy
// states). The standing PHONE host keeps its existing legacy vocabulary in `host-service.ts` — with
// its deny-by-default fs jail — and is deliberately NOT routed through this dispatch path.
import { connectRelay, type RelayTransport } from './relay-socket'
import {
  createTrustGate,
  deniedFrame,
  parseDenied,
  type PinStore,
  type TrustDeniedReason,
  type TrustGate
} from './relay-trust'
import type { KeyPair } from './e2ee'
import type { UiSink } from '../ui-sink-registry'
import {
  E_UNAUTHORIZED,
  parseRpcMessage,
  type RpcCast,
  type RpcErr,
  type RpcOk,
  type RpcRequest
} from '../../shared/rpc'
import { IPC } from '../../shared/ipc'
import { scopeWorkspaceToProject } from '../../shared/relay-workspace-scope'
import { outOfProjectScope } from './relay-project-scope'
import { HOST_ONLY_REFUSAL, isHostOnlyChannel } from '../../shared/host-control'
import type { Workspace } from '../../shared/types'

/**
 * How a mutually-approved peer joins the shell's core, and how it leaves. The shell owns every step
 * (ClientId allocation, the peer registry, presence, the platform's dispatch table); this module
 * only decides WHEN.
 */
export interface PeerAttach {
  /** Register the sink AND join presence as a 'desktop' peer. Returns the peer's ClientId. */
  attach(sink: UiSink): number
  /** The ONE teardown (presence leave → dropClient → registry prune). */
  detach(id: number): void
  /** Answer the peer's request. May REJECT (or throw): the host answers that request `E_HANDLER`
   *  and the session keeps serving — a failed dispatch never goes unanswered or unhandled. */
  dispatch(id: number, req: RpcRequest): Promise<RpcOk | RpcErr>
  /** Deliver the peer's cast. Must NOT throw: the tunnel cast path and the teardown's board-log
   *  unsubscribe replay call it unguarded (a cast has no reply channel — isolate and log inside,
   *  as both platforms' `cast` already do). */
  cast(id: number, method: string, args: unknown[]): void
}

/** A per-request verdict. `args` (when present) replaces the peer's args for everything downstream. */
export type AccessDecision = { allow: true; args?: unknown[] } | { allow: false; message: string }

/**
 * Optional per-session policy. Absent (the desktop) = the unhooked path, byte for byte.
 *
 * A hook that THROWS never reaches the socket (a throw there escapes into the WebSocket's own
 * synchronous message emit, which then delivers nothing more and never closes: the peer hangs and
 * stays attached). Instead: `interceptReq` / `access` on a req → the request is answered
 * `E_HANDLER`; `access` on a cast → the cast is dropped and logged; `narrowResponse` → `E_HANDLER`,
 * never the un-narrowed result; `wrapSink` → the session FAILS CLOSED (see `open`).
 *
 * `access` FAILS CLOSED on a malformed answer too: anything but a well-formed `AccessDecision`
 * (`undefined`, `null`, `{}`, non-array `args`, a refusal without a `message`) DENIES — `E_ROLE`
 * for a req, dropped and logged for a cast. Only an ABSENT `access` hook means allow-all.
 */
export interface RelayHostHooks {
  /**
   * Answer a request here instead of dispatching it. `null` = not intercepted.
   *
   * An intercepted request BYPASSES `access` and every project-scope jail below: nothing else looks
   * at it. An interceptor therefore enforces its own role and scope checks. The hosted team's do
   * (src/core/relay/hosted-service.ts): only `relay:hosted:self` is open to any team member (and to a
   * session whose own approval could not be pinned, served as the lowest role); approve, deny,
   * invite-code and pending are owner-only, judged from the CALLER's own session key in the team
   * store — never from anything the request carries.
   */
  interceptReq?(s: RelayHostSession, method: string, args: unknown[]): Promise<unknown> | null
  /** Allow (optionally rewriting args) or refuse a request/cast before any scope check or dispatch. */
  access?(s: RelayHostSession, kind: 'req' | 'cast', method: string, args: unknown[]): AccessDecision
  /** Filter what reaches the peer. Keep `bufferedAmount` pointing at the base sink's (obligation 2). */
  wrapSink?(s: RelayHostSession, sink: UiSink): UiSink
  /** Narrow a SUCCESSFUL dispatch result before it goes back over the tunnel. */
  narrowResponse?(s: RelayHostSession, method: string, result: unknown): unknown
}

export interface RelayHostSession {
  /** The peer's presence/platform ClientId once it is open, else null. */
  clientId(): number | null
  /** The 10-digit SAS (v2, "NNN NNN NNNN") both humans compare, or null before the key is derived. */
  sas(): string | null
  /** The peer's stable box public key (base64), or null before the handshake learned it. */
  peerKeyB64(): string | null
  /** The single project this hosting session shares with the peer, or undefined if unscoped. */
  sharedProjectId(): string | undefined
  /** This human confirmed the SAS (from the approve dialog). */
  confirm(): void
  /** Refuse the peer: tell it WHY over the encrypted tunnel, then close. Idempotent. */
  deny(reason: TrustDeniedReason): void
  /** Tear down: detach the peer (leave + dropClient + prune), close the socket. Idempotent. */
  close(): void
}

export interface ConnectRelayHostOptions {
  url: string
  token: string
  ourKeys: KeyPair
  /** How the approved peer joins (and leaves) the shell's core. */
  attach: PeerAttach
  /** TEST ONLY: an in-process RelayTransport. Production opens a real ws (relay-socket.ts). */
  transport?: RelayTransport
  /** The single project this hosting session shares with the peer. Undefined → unscoped (legacy
   *  behaviour: the peer sees the whole workspace). Held on the session for Task 2's scoped serve. */
  sharedProjectId?: string
  /** Where a mutual approval is pinned. Absent = pin nothing (the session still opens). */
  pins?: PinStore
  /**
   * Latch THIS end's confirm without a human, for a peer key this host already trusts. Asked once,
   * with the HANDSHAKE's peer key (the key whose shared secret produced the SAS), and it must answer
   * from the host's OWN pin store — never from anything the peer sent. It never touches the peer's
   * half: the peer must still confirm over the encrypted tunnel. An auto-approved peer raises no
   * `onPeerPending`.
   */
  autoApprove?: (peerKeyB64: string) => boolean
  /** Per-session policy (roles). Absent = the unhooked path. */
  hooks?: RelayHostHooks
  /** The SAS is known — ask the human to compare it. */
  onPeerPending(session: RelayHostSession): void
  /** Mutually approved: the peer is a CorePlatform client of this core now. */
  onOpen(session: RelayHostSession): void
  /**
   * The session ended without this shell asking: fires AT MOST ONCE, when the relay socket drops,
   * when a throwing `wrapSink` fails the session closed, when the session key is found swapped (the
   * key-swap self-close), or when the peer overflows the frames held between approval and open
   * (`HELD_FRAMES_MAX`). The peer is already torn down when it fires. `close()`, `deny()` and
   * `killRelayHostsByPeerKey` NEVER fire it — their caller already knows, and owes its own
   * bookkeeping for that end.
   */
  onClose(): void
}

const errorMessage = (err: unknown): string => (err instanceof Error ? err.message : String(err))

/** A well-formed `AccessDecision` — anything else from an `access` hook is a DENIAL (R12). */
function isAccessDecision(d: unknown): d is AccessDecision {
  if (typeof d !== 'object' || d === null) return false
  const o = d as { allow?: unknown; args?: unknown; message?: unknown }
  if (o.allow === true) return o.args === undefined || Array.isArray(o.args)
  if (o.allow === false) return typeof o.message === 'string'
  return false
}

/** The access hook's verdict: decided, threw, or answered something that is not a decision. */
type AccessVerdict =
  | { kind: 'decided'; decision: AccessDecision }
  | { kind: 'threw'; err: unknown }
  | { kind: 'malformed' }

/** The refusal a req gets when the access hook's answer is not a decision (never its raw value). */
const ACCESS_CHECK_FAILED = 'Access check failed.'

/**
 * How many req/cast frames a peer may send between mutual approval and `open` (while the pin write
 * is in flight) before the session is closed. Those frames are HELD, not refused: a client opens as
 * soon as it has the host's confirm, so the first thing a new teammate sends (`workspace:load` at
 * `onApproved`) routinely lands inside the host's pin write. Bounded, because nothing reads them
 * until the pin settles.
 */
export const HELD_FRAMES_MAX = 256

/** Live bridged peers, for revocation: unpinning a key refuses the NEXT handshake, but the OPEN
 *  socket keeps full shell access until it is cut (see revocation.ts). */
const live = new Set<RelayHostSession>()

/** Cut every live session with this peer key. The revoker's `onRevoke` (src/main/index.ts). With a
 *  reason, the peer is told why over the encrypted tunnel first (`deny`); without one it is closed. */
export function killRelayHostsByPeerKey(peerKeyB64: string, reason?: TrustDeniedReason): void {
  killRelayHostsWhere((key) => key === peerKeyB64, reason)
}

/** Cut every live session (bridged or still awaiting mutual approval) whose peer key satisfies
 *  `match`. A session whose key is not known yet is never matched. */
export function killRelayHostsWhere(match: (peerKeyB64: string) => boolean, reason?: TrustDeniedReason): void {
  for (const session of [...live]) {
    const key = session.peerKeyB64()
    if (!key || !match(key)) continue
    if (reason) session.deny(reason)
    else session.close()
  }
}

export function connectRelayHost(opts: ConnectRelayHostOptions): RelayHostSession {
  let clientId: number | null = null
  let gate: TrustGate | null = null
  let closed = false
  // OBLIGATION (a) — defence in depth. The peer's ECDH public key at the moment the gate is created
  // (the same key `emptyMutualApproval` is seeded with, and whose shared secret produced the SAS the
  // humans compared). If the socket's live peer key ever diverges from this, the session key was
  // swapped under us (a mid-session re-key by a relay MITM) — we then refuse to advance approval,
  // dispatch peer traffic, or open the sink. relay-socket's layer-1 guard already prevents the swap;
  // this is the second, independent check so the property does not rest on that one guard.
  let sessionPeerKey: string | null = null
  // True once we have detected a key swap and cut the session, so we don't do it twice.
  let keySwapped = false

  // Board-log onChanged over the relay rides the core's per-project watch refcount
  // (registerBoardLogHandlers): the guest casts board-log:subscribe / :unsubscribe, which start/stop
  // the host watch. But a guest whose tab closes or whose socket drops sends no balancing unsubscribe,
  // so we track THIS connection's net per-project subscribe count and replay the unsubscribes on
  // teardown (see detach) — the host watch is released, and the shared local refcount is never touched
  // below this connection's own contribution (an unbalanced guest unsubscribe is ignored).
  const boardLogSubs = new Map<string, number>()

  // Frames the peer sent after BOTH humans approved but before `open` (the pin write is in flight).
  // Served in arrival order at `open`, through the same path as live frames; dropped with the session.
  const held: Array<RpcRequest | RpcCast> = []

  /** The ONE teardown, mirroring src/server/ws.ts's close path exactly: `attach.detach` IS the three
   *  steps (presence leave → onPeerGone → PtyManager.dropClient → registry prune). Do NOT
   *  re-implement them here. */
  const detach = (): void => {
    if (clientId === null) return
    // Release any board-log watches this connection still holds — a dropped guest tab never sends the
    // balancing unsubscribe, so replay one per outstanding count before the client id is gone.
    for (const [projectId, count] of boardLogSubs) {
      for (let i = 0; i < count; i++) opts.attach.cast(clientId, IPC.boardLogUnsubscribe, [projectId])
    }
    boardLogSubs.clear()
    opts.attach.detach(clientId)
    clientId = null
  }

  const session: RelayHostSession = {
    clientId: () => clientId,
    sas: () => gate?.sas() ?? null,
    peerKeyB64: () => gate?.peerKeyB64() ?? null,
    sharedProjectId: () => opts.sharedProjectId,
    confirm: () => gate?.confirmHere(),
    deny(reason) {
      if (closed) return
      // Over the ENCRYPTED tunnel, so only the real peer can read it (and the relay cannot forge it).
      socket.sendTunnelText(deniedFrame(reason))
      session.close()
    },
    close() {
      if (closed) return
      closed = true
      held.length = 0
      live.delete(session)
      detach()
      socket.close()
    }
  }

  /** End the session on the core's own initiative (a swapped key, a throwing wrapSink, a flooded
   *  hold queue). A self-initiated close() never reaches the socket's onClose, and the shell did not
   *  ask for this one: tell it, at most once, and never for a session that was already closed. Its
   *  bookkeeping (a seat, a pending request, a standing listener counted as bridged) must hear every
   *  end. */
  const closeUnasked = (): void => {
    const wasLive = !closed
    session.close()
    if (wasLive) opts.onClose()
  }

  /** The socket's live peer key still matches the one bound into the gate/approval state. A false
   *  return means the session key was swapped under us — refuse everything and cut the session. */
  const peerKeyIntact = (): boolean => {
    if (keySwapped) return false
    if (sessionPeerKey !== null && socket.peerPublicKeyB64() === sessionPeerKey) return true
    keySwapped = true
    closeUnasked()
    return false
  }

  /** Both humans confirmed: the peer joins this core as a client. */
  const open = (): void => {
    if (closed || clientId !== null) return
    // The key that keyed this session must still be the original peer's (belt to layer-1's brace).
    if (!peerKeyIntact()) return
    // A DEAD socket must THROW (the registry evicts a sink after 2 consecutive throws and runs the
    // full teardown), and a healthy one must NOT (two throws in a row would kick a live peer out).
    // sendTunnel* returns false only when the channel is gone — turn exactly that into a throw.
    //
    // OBLIGATION 2. The number Stage 2's per-client backpressure AND the 8 MB WS_DROP_WATER
    // drop-and-redraw ceiling key on (src/core/ui-sink-registry.ts). `bufferedAmount` is OPTIONAL
    // on UiSink and defaults to 0, so a sink that omits it — or stubs it — typechecks, passes every
    // test, and silently disables the ceiling: a slow peer then queues pty output without bound,
    // nothing pauses the pty or drops its backlog, and the HOST'S MEMORY GROWS UNTIL THE PROCESS
    // DIES. RelaySocket.bufferedAmount() is honest (ws.bufferedAmount + the pre-open queue).
    // Never make this a constant.
    //
    // A `wrapSink` hook must keep its `bufferedAmount` pointing at `base.bufferedAmount`.
    //
    // A session this host already CLOSED is not a dead socket: it is being torn down right now, and
    // `detach` broadcasts on its way out — the presence hub's `leave` diff goes to every registered
    // sink, the leaver's own included, before the sink is unregistered. Delivering to a peer that is
    // gone loses nothing, so that send is dropped; throwing would log a false dead-socket strike on
    // every ordinary disconnect (measured on a real headless boot, src/server/hosted-e2e.test.ts).
    // Only a socket that dies while the session still counts as open throws, which is what the
    // registry's eviction is for.
    const base: UiSink = {
      sendText: (json) => {
        if (closed) return
        if (!socket.sendTunnelText(json)) throw new Error('relay socket is not connected')
      },
      sendBinary: (buf) => {
        if (closed) return
        if (!socket.sendTunnelBinary(buf)) throw new Error('relay socket is not connected')
      },
      bufferedAmount: () => socket.bufferedAmount()
    }
    let sink: UiSink = base
    if (opts.hooks?.wrapSink) {
      try {
        sink = opts.hooks.wrapSink(session, base)
      } catch (err) {
        // FAIL CLOSED. A wrapSink is a FILTER (a viewer's view of the host); falling back to the bare
        // base sink would hand the peer everything the filter exists to withhold. Attach nothing and
        // end the session, and tell the shell (closeUnasked).
        console.warn(`[relay-host] wrapSink threw; closing the session: ${errorMessage(err)}`)
        closeUnasked()
        return
      }
    }
    const id = opts.attach.attach(sink)
    clientId = id
    opts.onOpen(session)
    // What the peer sent while the pin was being written, in arrival order, exactly as if it had
    // arrived now. A frame that ends the session stops the rest.
    for (const m of held.splice(0)) {
      if (closed || clientId === null) break
      serve(m)
    }
  }

  /** UX scope, NOT a trust boundary: for the ONE `workspace:load` method, when this hosting session
   *  is bound to a single project, narrow the successful response to that project (see
   *  scopeWorkspaceToProject). Every other method — and an error response, and an unscoped session —
   *  passes through byte-identical. This can only NARROW: it never exposes anything the core did not
   *  already return, and it never touches a non-`workspace:load` response. */
  const scopeResponse = (method: string, res: RpcOk | RpcErr): RpcOk | RpcErr => {
    if (!opts.sharedProjectId || method !== IPC.workspaceLoad || res.ok !== true) return res
    return { ...res, result: scopeWorkspaceToProject(res.result as Workspace, opts.sharedProjectId) }
  }

  /** The hook's narrowing, for a SUCCESSFUL response only. No hook → the response untouched. */
  const narrowResponse = (method: string, res: RpcOk | RpcErr): RpcOk | RpcErr => {
    if (!opts.hooks?.narrowResponse || res.ok !== true) return res
    return { ...res, result: opts.hooks.narrowResponse(session, method, res.result) }
  }

  /** The answer to a request whose handler (a hook, or the shell's dispatch) threw or rejected. */
  const handlerError = (id: number, err: unknown): string =>
    JSON.stringify({ t: 'res', id, ok: false, error: { code: 'E_HANDLER', message: errorMessage(err) } })

  /** Ask the access hook, and never let it throw or mis-answer its way into the socket: a throw is
   *  `threw`, a malformed answer is `malformed` (both deny). Only an ABSENT hook allows all. */
  const checkAccess = (kind: 'req' | 'cast', method: string, args: unknown[]): AccessVerdict => {
    if (!opts.hooks?.access) return { kind: 'decided', decision: { allow: true } }
    let answer: unknown
    try {
      answer = opts.hooks.access(session, kind, method, args)
    } catch (err) {
      return { kind: 'threw', err }
    }
    return isAccessDecision(answer) ? { kind: 'decided', decision: answer } : { kind: 'malformed' }
  }

  /** Send the response `build` produces. If building or serialising it throws (a narrowResponse hook,
   *  an unserialisable result), answer `E_HANDLER` instead. Never throws: it runs inside a `.then`,
   *  where a throw would be an unhandled rejection and a request nobody ever answers. */
  const respond = (id: number, build: () => RpcOk | RpcErr): void => {
    let json: string
    try {
      json = JSON.stringify(build())
    } catch (err) {
      json = handlerError(id, err)
    }
    socket.sendTunnelText(json)
  }

  /** SCOPE jail for the board log (beyond the host registry's own projectId jail): a session bound to
   *  one project must never let the guest reach ANOTHER project's board log. A board-log method naming
   *  a different projectId is out of scope. Unscoped sessions pass through — the registry is the only
   *  gate then, exactly as for the host's own renderer. The guest can never supply a filesystem path;
   *  only a projectId the host resolves through its own router. */
  const boardLogOutOfScope = (projectId: unknown): boolean =>
    !!opts.sharedProjectId && projectId !== opts.sharedProjectId

  /** The degraded response for an out-of-scope board-log request — the SAME shape the router gives an
   *  unknown project, produced WITHOUT dispatching (never resolving a path). Never throws. */
  const boardLogRefusal = (method: string, id: number): RpcOk =>
    method === IPC.boardLogRead
      ? { t: 'res', id, ok: true, result: { entries: [], unsupported: true } }
      : { t: 'res', id, ok: true, result: false }

  /** SCOPE jail for every project-naming channel class (`relay-project-scope.ts`): a method in a
   *  scoped class that names another project — or that the table cannot read a projectId out of —
   *  is refused on a session bound to one project. Fail-closed by class, so a channel added to
   *  `githubIssues:*` / `board-log:*` / `projects.*` without a table row is refused, not waved on. */
  const projectOutOfScope = (method: string, args: unknown[]): boolean =>
    outOfProjectScope(opts.sharedProjectId, method, args)

  const projectScopeRefusal = (method: string, id: number): RpcErr => ({
    t: 'res',
    id,
    ok: false,
    error: {
      code: 'E_FORBIDDEN',
      message: method.startsWith('githubIssues:')
        ? 'GitHub Issues project is outside this relay session'
        : 'That project is outside this relay session'
    }
  })

  /** Serve one req/cast of an OPEN session: interceptor, access, scope jails, then dispatch/cast.
   *  Live frames and held ones (see `held`) both come through here, so they meet the same checks. */
  const serve = (m: RpcRequest | RpcCast): void => {
    if (clientId === null) return
    // HOST-ONLY channels (shared/host-control.ts) are refused to EVERY relay peer, before any hook
    // or dispatch — here, in core, so the Server Edition's hosted peers meet the same list the
    // desktop's platform dispatch already enforced (a hosted Editor passes every role check).
    if ((m.t === 'req' || m.t === 'cast') && isHostOnlyChannel(m.method)) {
      if (m.t === 'req') {
        socket.sendTunnelText(
          JSON.stringify({ t: 'res', id: m.id, ok: false, error: { code: 'E_FORBIDDEN', message: HOST_ONLY_REFUSAL } })
        )
      }
      return
    }
    if (m.t === 'req') {
      // A hook may answer the request itself — it then never reaches a scope check or the core.
      // Every hook call below is guarded: a throw is ANSWERED (E_HANDLER), never let into the
      // socket's message emit (see RelayHostHooks).
      let intercepted: Promise<unknown> | null
      try {
        intercepted = opts.hooks?.interceptReq?.(session, m.method, m.args) ?? null
      } catch (err) {
        socket.sendTunnelText(handlerError(m.id, err))
        return
      }
      if (intercepted) {
        void intercepted.then(
          (result) => respond(m.id, () => ({ t: 'res', id: m.id, ok: true, result: result ?? null })),
          (err) => socket.sendTunnelText(handlerError(m.id, err))
        )
        return
      }
      const verdict = checkAccess('req', m.method, m.args)
      if (verdict.kind === 'threw') {
        socket.sendTunnelText(handlerError(m.id, verdict.err))
        return
      }
      if (verdict.kind === 'malformed') {
        console.warn(`[relay-host] access returned a malformed decision on req ${m.method}; refused`)
        socket.sendTunnelText(JSON.stringify({ t: 'res', id: m.id, ok: false, error: { code: 'E_ROLE', message: ACCESS_CHECK_FAILED } }))
        return
      }
      const decision = verdict.decision
      if (!decision.allow) {
        socket.sendTunnelText(JSON.stringify({ t: 'res', id: m.id, ok: false, error: { code: 'E_ROLE', message: decision.message } }))
        return
      }
      const args = decision.args ?? m.args
      // Board-log read/append naming a project outside this session's scope: refuse WITHOUT
      // dispatching (the host router never resolves it), degrading exactly as an unknown project.
      // Checked before the generic jail so these two keep their established degraded shape.
      if (
        (m.method === IPC.boardLogAppend || m.method === IPC.boardLogRead) &&
        boardLogOutOfScope(args[0])
      ) {
        socket.sendTunnelText(JSON.stringify(boardLogRefusal(m.method, m.id)))
        return
      }
      if (projectOutOfScope(m.method, args)) {
        socket.sendTunnelText(JSON.stringify(projectScopeRefusal(m.method, m.id)))
        return
      }
      const id = clientId
      let pending: Promise<RpcOk | RpcErr>
      try {
        pending = opts.attach.dispatch(id, { ...m, args })
      } catch (err) {
        socket.sendTunnelText(handlerError(m.id, err))
        return
      }
      void pending.then(
        (res) => respond(m.id, () => narrowResponse(m.method, scopeResponse(m.method, res))),
        (err) => socket.sendTunnelText(handlerError(m.id, err))
      )
    } else if (m.t === 'cast') {
      // A cast has no reply channel: a policy that throws or cannot decide DROPS it — and says so,
      // because a silently dropped pty:write swallows keystrokes with nothing in any log (the same
      // reason both platforms log a throwing cast listener).
      const verdict = checkAccess('cast', m.method, m.args)
      if (verdict.kind === 'threw') {
        console.warn(`[relay-host] access threw on cast ${m.method}:`, errorMessage(verdict.err))
        return
      }
      if (verdict.kind === 'malformed') {
        console.warn(`[relay-host] access returned a malformed decision on cast ${m.method}; dropped`)
        return
      }
      const d = verdict.decision
      if (!d.allow) return
      const args = d.args ?? m.args
      if (projectOutOfScope(m.method, args)) return
      // Board-log subscribe/unsubscribe: scope-jail out-of-scope projects, and track this
      // connection's net per-project count so a dropped guest's watch is released in detach().
      if (m.method === IPC.boardLogSubscribe || m.method === IPC.boardLogUnsubscribe) {
        const projectId = args[0]
        if (typeof projectId !== 'string' || boardLogOutOfScope(projectId)) return
        if (m.method === IPC.boardLogSubscribe) {
          boardLogSubs.set(projectId, (boardLogSubs.get(projectId) ?? 0) + 1)
        } else {
          const cur = boardLogSubs.get(projectId) ?? 0
          if (cur <= 0) return // this connection holds no such watch — never decrement the shared count
          if (cur === 1) boardLogSubs.delete(projectId)
          else boardLogSubs.set(projectId, cur - 1)
        }
      }
      opts.attach.cast(clientId, m.method, args)
    }
  }

  const socket = connectRelay({
    url: opts.url,
    token: opts.token,
    role: 'host',
    ourKeys: opts.ourKeys,
    transport: opts.transport,
    onReady: () => {
      // E2EE is up. This proves only that SOMEONE holds the pairing token — NOT that the human at
      // the other end is who we think. Serve nothing yet: build the gate and ask for the SAS.
      const peerKey = socket.peerPublicKeyB64()
      if (!peerKey || gate) return
      // Bind the session to THIS peer key. Every later approval/dispatch step re-asserts it.
      sessionPeerKey = peerKey
      // Asked with the HANDSHAKE key, before the gate exists: a pinned peer skips the dialog. A
      // pin-store lookup that throws reads as "not pinned" — the human is asked instead.
      let auto = false
      try {
        auto = opts.autoApprove?.(peerKey) === true
      } catch (err) {
        console.warn(`[relay-host] autoApprove threw; asking the human instead: ${errorMessage(err)}`)
      }
      gate = createTrustGate({
        peerKeyB64: peerKey,
        sessionId: `${peerKey}:${Date.now()}`, // obligation (b): ONE state per pairing attempt
        sas: () => socket.sas(),
        sendConfirm: (json) => socket.sendTunnelText(json),
        onOpen: open,
        pins: opts.pins,
        // Never let the gate send its confirm while it is being built: see the deferral below.
        autoApprove: false
      })
      live.add(session)
      if (auto) {
        // The auto-confirm goes out AFTER the current turn, never inside onReady. Over an in-process
        // transport this onReady runs inside the PEER's connectRelay call — before the peer holds its
        // socket or its gate — so a confirm sent now is dropped on the floor and a pinned reconnect
        // never opens. Over a real WebSocket the microtask costs nothing.
        queueMicrotask(() => {
          if (!closed) gate?.confirmHere()
        })
      } else {
        opts.onPeerPending(session)
      }
    },
    // The legacy phone dialect is not served here: nothing is wired to onRpc / onFrame.
    onRpc: () => {},
    onFrame: () => {},
    onTunnel: (kind, payload) => {
      // Binary peer→host frames are ignored: pty input rides JSON casts, exactly as on the WS.
      if (kind !== 'text') return
      // OBLIGATION (a) — before ANYTHING (advancing approval via the gate, or dispatching a peer
      // RPC/cast): the session key must still belong to the ORIGINAL peer. A tunnel frame that
      // decrypted under a swapped key must not advance confirmRemote or reach the core.
      if (!peerKeyIntact()) return
      const json = new TextDecoder().decode(payload)
      // A denial is the HOST's word to a peer, never the other way round: a peer that sends one is
      // ignored, and the frame never reaches the core (the gate does not consume it).
      if (parseDenied(json)) return
      // Trust frames are consumed BEFORE dispatch and never reach the core.
      if (gate?.onTunnelText(json)) return
      const m = parseRpcMessage(json)
      if (!m) return
      if (clientId === null) {
        // Mutually approved, not yet open (the pin write is in flight): HOLD, never refuse — the
        // client is already open and its first request would otherwise fail. Nothing is judged or
        // served before `open`; a peer that floods the hold is cut.
        if (gate?.isApproved() && (m.t === 'req' || m.t === 'cast')) {
          if (held.length >= HELD_FRAMES_MAX) {
            console.warn(`[relay-host] a peer sent more than ${HELD_FRAMES_MAX} frames before its session opened; closing it`)
            closeUnasked()
            return
          }
          held.push(m)
          return
        }
        // Not mutually approved: refuse — but ANSWER, or the peer's `await` would hang forever.
        if (m.t === 'req') {
          socket.sendTunnelText(
            JSON.stringify({
              t: 'res',
              id: m.id,
              ok: false,
              error: { code: E_UNAUTHORIZED, message: 'Awaiting mutual approval.' }
            })
          )
        }
        return
      }
      // res/ev from a peer are ignored (mirrors src/server/ws.ts).
      if (m.t === 'req' || m.t === 'cast') serve(m)
    },
    onClose: () => {
      // The peer is GONE — the same state a closed browser tab leaves the core in. Mark the session
      // closed FIRST: a gate whose pin write is still in flight will call open() later, and open()
      // must then bail — never attach the peer to this dead socket, and never reach the wrapSink
      // fail-closed path that would fire onClose a second time (R13).
      closed = true
      held.length = 0
      live.delete(session)
      detach()
      opts.onClose()
    }
  })

  return session
}