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.

feat(watch-link): the viewer's relay client, tested against the real host socket, plus vectors

reviewfee1b94e14e4
diff --git a/src/core/watch-link/client.test.ts b/src/core/watch-link/client.test.ts
new file mode 100644
index 000000000..be2248434
--- /dev/null
+++ b/src/core/watch-link/client.test.ts
@@ -0,0 +1,165 @@
+// The viewer client runs against the REAL host-role relay socket, not a fake. That is what pins the
+// wire constants src/shared/watch-link/wire.ts restates (the seq header, TAG_*, ROLE_*, NONCE_BYTES):
+// they are module-private in relay-socket.ts, so a drift there shows up here as a handshake that
+// never completes or a frame the host never sees. It lives in core because it imports core modules
+// the web tsconfig project that vendors src/shared/watch-link cannot see.
+import { describe, it, expect, vi } from 'vitest'
+import nacl from 'tweetnacl'
+import { connectRelay } from '../relay/relay-socket'
+import { transportPair } from '../relay/transport-pair'
+import { publicKeyToB64 } from '../relay/e2ee'
+import { encodePtyData } from '../../shared/rpc'
+import { connectWatchClient, TRUST_CONFIRM_JSON } from '../../shared/watch-link/client'
+import { deriveWatchLinkKeys } from '../../shared/watch-link/keys'
+
+function hostWith(keys = deriveWatchLinkKeys(nacl.randomBytes(32))) {
+ const { hostT, peerT } = transportPair()
+ const tunnel: string[] = []
+ let ready = false
+ const host = connectRelay({
+ url: 'wss://x', token: 't', role: 'host',
+ ourKeys: { publicKey: keys.host.publicKey, secretKey: keys.host.secretKey },
+ transport: hostT,
+ onReady: () => { ready = true },
+ onRpc: () => {}, onFrame: () => {}, onClose: () => {},
+ onTunnel: (kind, payload) => { if (kind === 'text') tunnel.push(new TextDecoder().decode(payload)) }
+ })
+ return { keys, host, hostT, peerT, tunnel, isReady: () => ready }
+}
+
+function events() {
+ const log = { open: 0, events: [] as [string, unknown[]][], pty: [] as [string, string][], denied: [] as string[], closed: 0 }
+ return {
+ log,
+ ev: {
+ onOpen: () => { log.open++ },
+ onEvent: (c: string, a: unknown[]) => { log.events.push([c, a]) },
+ onPtyData: (s: string, d: string) => { log.pty.push([s, d]) },
+ onDenied: (r: string) => { log.denied.push(r) },
+ onClose: () => { log.closed++ }
+ }
+ }
+}
+
+describe('connectWatchClient against the real relay socket', () => {
+ it('completes the handshake, confirms trust, and opens once the host confirms', async () => {
+ const h = hostWith()
+ const { log, ev } = events()
+ const c = connectWatchClient({ socket: h.peerT, keys: h.keys, events: ev })
+ await vi.waitFor(() => expect(h.isReady()).toBe(true))
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ expect(h.host.peerPublicKeyB64()).toBe(publicKeyToB64(h.keys.viewer.publicKey))
+ expect(c.isOpen()).toBe(false)
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ expect(log.open).toBe(1)
+ expect(c.isOpen()).toBe(true)
+ })
+
+ it('delivers ev frames and pty data only after it is open', async () => {
+ const h = hostWith()
+ const { log, ev } = events()
+ connectWatchClient({ socket: h.peerT, keys: h.keys, events: ev })
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(JSON.stringify({ t: 'ev', channel: 'watch:meta', args: [{ v: 1 }] }))
+ h.host.sendTunnelBinary(encodePtyData('s1', 'early'))
+ expect(log.events).toEqual([])
+ expect(log.pty).toEqual([])
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ h.host.sendTunnelText(JSON.stringify({ t: 'ev', channel: 'watch:meta', args: [{ v: 1 }] }))
+ h.host.sendTunnelBinary(encodePtyData('s1', 'late'))
+ expect(log.events).toEqual([['watch:meta', [{ v: 1 }]]])
+ expect(log.pty).toEqual([['s1', 'late']])
+ })
+
+ it('reports a denial and never opens', async () => {
+ const h = hostWith()
+ const { log, ev } = events()
+ connectWatchClient({ socket: h.peerT, keys: h.keys, events: ev })
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(JSON.stringify({ t: 'cast', method: 'trust:denied', args: ['denied'] }))
+ expect(log.denied).toEqual(['denied'])
+ expect(log.open).toBe(0)
+ })
+
+ it('cannot talk to a host whose key is not the link one', async () => {
+ const real = deriveWatchLinkKeys(nacl.randomBytes(32))
+ const impostor = hostWith(deriveWatchLinkKeys(nacl.randomBytes(32)))
+ connectWatchClient({ socket: impostor.peerT, keys: real, events: events().ev })
+ await new Promise((r) => setTimeout(r, 20))
+ expect(impostor.isReady()).toBe(false)
+ })
+
+ it('sends a chat cast only while open', async () => {
+ const h = hostWith()
+ const c = connectWatchClient({ socket: h.peerT, keys: h.keys, events: events().ev })
+ expect(c.sendChat('Ada', 'hi')).toBe(false)
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ expect(c.sendChat('Ada', 'hi')).toBe(true)
+ expect(h.tunnel.at(-1)).toBe(JSON.stringify({ t: 'cast', method: 'watch:chat', args: [{ name: 'Ada', text: 'hi' }] }))
+ })
+
+ it('keeps both directions flowing past seq 255', async () => {
+ // A strictly increasing counter stays increasing under most encodings, so a short exchange
+ // cannot tell the relay's little-endian seq from a byte-swapped copy. Past one byte it can:
+ // a swapped 256 decodes below a swapped 255 and the receiver drops it as a replay.
+ const h = hostWith()
+ const { log, ev } = events()
+ const c = connectWatchClient({ socket: h.peerT, keys: h.keys, events: ev })
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ for (let i = 0; i < 300; i++) h.host.sendTunnelBinary(encodePtyData('s1', String(i)))
+ expect(log.pty).toHaveLength(300)
+ expect(log.pty.at(-1)).toEqual(['s1', '299'])
+ for (let i = 0; i < 300; i++) expect(c.sendChat('Ada', String(i))).toBe(true)
+ expect(h.tunnel.at(-1)).toBe(JSON.stringify({ t: 'cast', method: 'watch:chat', args: [{ name: 'Ada', text: '299' }] }))
+ expect(h.tunnel.filter((m) => m.includes('watch:chat'))).toHaveLength(300)
+ })
+
+ it('keeps the sealed stream in order across keepalives, and stops them when the socket closes', async () => {
+ const h = hostWith()
+ const { log, ev } = events()
+ const timer: { tick?: () => void; ms?: number } = {}
+ const stopped: unknown[] = []
+ let sent = 0
+ const c = connectWatchClient({
+ socket: { ...h.peerT, send: (d) => { sent++; h.peerT.send(d) } }, keys: h.keys, events: ev,
+ setInterval: (fn, ms) => { timer.tick = fn; timer.ms = ms; return 'handle' },
+ clearInterval: (handle) => { stopped.push(handle) }
+ })
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ expect(timer.ms).toBe(25_000)
+ // A keepalive is a real sealed frame and spends a seq number; the host must still accept what
+ // follows it.
+ const before = sent
+ timer.tick?.()
+ timer.tick?.()
+ expect(sent - before).toBe(2)
+ expect(c.sendChat('Ada', 'after keepalives')).toBe(true)
+ expect(h.tunnel.at(-1)).toBe(JSON.stringify({ t: 'cast', method: 'watch:chat', args: [{ name: 'Ada', text: 'after keepalives' }] }))
+ // The far side hangs up: the client reports it once, stops its keepalive, and stops sending.
+ h.hostT.close()
+ expect(log.closed).toBe(1)
+ expect(stopped).toEqual(['handle'])
+ expect(c.isOpen()).toBe(false)
+ expect(c.sendChat('Ada', 'too late')).toBe(false)
+ })
+
+ it('does not report a close the caller asked for, and still stops its keepalive', async () => {
+ const h = hostWith()
+ const { log, ev } = events()
+ const stopped: unknown[] = []
+ const c = connectWatchClient({
+ socket: h.peerT, keys: h.keys, events: ev,
+ setInterval: () => 'handle',
+ clearInterval: (handle) => { stopped.push(handle) }
+ })
+ await vi.waitFor(() => expect(h.tunnel).toContain(TRUST_CONFIRM_JSON))
+ h.host.sendTunnelText(TRUST_CONFIRM_JSON)
+ c.close()
+ expect(log.closed).toBe(0)
+ expect(stopped).toEqual(['handle'])
+ expect(c.isOpen()).toBe(false)
+ })
+})
diff --git a/src/core/watch-link/wire.test.ts b/src/core/watch-link/wire.test.ts
index 96f211e37..6d7c89a7b 100644
--- a/src/core/watch-link/wire.test.ts
+++ b/src/core/watch-link/wire.test.ts
@@ -4,7 +4,7 @@ import nacl from 'tweetnacl'
import { encodePtyData, encodeArgs, parseRpcMessage } from '../../shared/rpc'
import { decrypt, deriveSessionKey, encrypt, randomSessionNonce } from '../relay/e2ee'
import { hkdfSha256 } from '../../shared/watch-link/hkdf'
-import { sealBox, openBox, withHeader, readHeader, encodePtyFrame, decodePtyFrame, parseTunnelJson, RELAY_SESSION_INFO } from '../../shared/watch-link/wire'
+import { sealBox, openBox, withHeader, readHeader, encodePtyFrame, decodePtyFrame, parseTunnelJson, NONCE_BYTES, RELAY_SESSION_INFO } from '../../shared/watch-link/wire'
import { sanitizeChatText, sanitizeChatName, isWatchEndReason, WATCH_CHAT_CAST, WATCH_EVENT_PREFIX } from '../../shared/watch-link/protocol'
import { concatBytes, utf8 } from '../../shared/watch-link/bytes'
@@ -20,6 +20,9 @@ describe('the wire rules match the relay they were copied from', () => {
const base = nacl.randomBytes(32), hn = randomSessionNonce(), cn = randomSessionNonce()
expect(await hkdfSha256(base, concatBytes(hn, cn), utf8(RELAY_SESSION_INFO), 32)).toEqual(deriveSessionKey(base, hn, cn))
})
+ it("the session nonce is as long as e2ee's randomSessionNonce", () => {
+ expect(randomSessionNonce()).toHaveLength(NONCE_BYTES)
+ })
it('a box sealed here opens with e2ee.decrypt and vice versa', () => {
const key = nacl.randomBytes(32), plain = utf8('hello')
expect(decrypt(sealBox(plain, key), key)).toEqual(plain)
diff --git a/src/shared/watch-link/client.ts b/src/shared/watch-link/client.ts
new file mode 100644
index 000000000..8133bf30b
--- /dev/null
+++ b/src/shared/watch-link/client.ts
@@ -0,0 +1,165 @@
+// The browser half of a live link: the CLIENT role of src/core/relay/relay-socket.ts (handshake,
+// sealed frames, keepalive) plus the trust gate's client obligation (send our own trust:confirm,
+// open only once the host's arrives). Nothing here can write to the terminal: the only message it
+// can send after the handshake is a chat cast, which the host accepts for Commenter links only.
+import nacl from 'tweetnacl'
+import { b64ToBytes, bytesToB64, concatBytes, utf8 } from './bytes'
+import { hkdfSha256 } from './hkdf'
+import type { WatchLinkKeys } from './keys'
+import { WATCH_CHAT_CAST } from './protocol'
+import {
+ NONCE_BYTES, RELAY_SESSION_INFO, ROLE_CLIENT, ROLE_HOST, TAG_RPC, TAG_TUNNEL_BIN, TAG_TUNNEL_TEXT,
+ decodePtyFrame, openBox, parseTunnelJson, readHeader, sealBox, withHeader
+} from './wire'
+
+export interface WatchSocket {
+ send(data: string | Uint8Array): void
+ close(): void
+ onMessage(cb: (data: unknown) => void): void
+ onClose(cb: () => void): void
+}
+export interface WatchClientEvents {
+ onOpen(): void
+ onEvent(channel: string, args: unknown[]): void
+ onPtyData(sessionId: string, data: string): void
+ onDenied(reason: string): void
+ onClose(): void
+}
+export interface WatchClient {
+ sendChat(name: string, text: string): boolean
+ close(): void
+ isOpen(): boolean
+}
+
+export const TRUST_CONFIRM_JSON = '{"t":"cast","method":"trust:confirm","args":[]}'
+const KEEPALIVE_MS = 25_000
+const KEEPALIVE_JSON = '{"kind":"keepalive"}'
+
+function toBytes(data: unknown): Uint8Array | null {
+ if (data instanceof Uint8Array) return data
+ if (data instanceof ArrayBuffer) return new Uint8Array(data)
+ return null
+}
+function json(raw: string): Record<string, unknown> | null {
+ try {
+ const v = JSON.parse(raw)
+ return v && typeof v === 'object' ? (v as Record<string, unknown>) : null
+ } catch {
+ return null
+ }
+}
+
+export function connectWatchClient(opts: {
+ socket: WatchSocket
+ keys: WatchLinkKeys
+ events: WatchClientEvents
+ setInterval?: (fn: () => void, ms: number) => unknown
+ clearInterval?: (h: unknown) => void
+}): WatchClient {
+ const { socket, keys, events } = opts
+ const every = opts.setInterval ?? ((fn: () => void, ms: number) => setInterval(fn, ms))
+ const stopEvery = opts.clearInterval ?? ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>))
+ const ourNonce = nacl.randomBytes(NONCE_BYTES)
+ const baseKey = nacl.box.before(keys.host.publicKey, keys.viewer.secretKey)
+ let state: 'hello' | 'deriving' | 'auth' | 'ready' | 'closed' = 'hello'
+ let sessionKey: Uint8Array | null = null
+ let sendSeq = 0
+ let recvSeq = -1
+ let hostConfirmed = false
+ let opened = false
+ let keepalive: unknown = null
+
+ function sendSealed(tag: number, body: Uint8Array): boolean {
+ if (!sessionKey || state === 'closed') return false
+ socket.send(sealBox(withHeader(ROLE_CLIENT, sendSeq++, concatBytes(Uint8Array.of(tag), body)), sessionKey))
+ return true
+ }
+ function maybeOpen(): void {
+ if (opened || !hostConfirmed || state !== 'ready') return
+ opened = true
+ events.onOpen()
+ }
+ function shutdown(): void {
+ if (state === 'closed') return
+ state = 'closed'
+ if (keepalive !== null) stopEvery(keepalive)
+ keepalive = null
+ }
+
+ async function onControl(raw: string): Promise<void> {
+ const m = json(raw)
+ if (state !== 'hello' || m?.type !== 'e2ee_ready' || typeof m.nonceB64 !== 'string') return
+ const hostNonce = b64ToBytes(m.nonceB64)
+ if (!hostNonce || hostNonce.length !== NONCE_BYTES) return
+ state = 'deriving'
+ const key = await hkdfSha256(baseKey, concatBytes(hostNonce, ourNonce), utf8(RELAY_SESSION_INFO), 32)
+ if (state !== 'deriving') return
+ sessionKey = key
+ state = 'auth'
+ sendSealed(TAG_RPC, utf8('{"type":"e2ee_auth"}'))
+ }
+
+ socket.onMessage((data) => {
+ if (state === 'closed') return
+ if (typeof data === 'string') {
+ void onControl(data)
+ return
+ }
+ const bytes = toBytes(data)
+ if (!bytes || !sessionKey) return
+ const plain = openBox(bytes, sessionKey)
+ const h = plain && readHeader(plain)
+ if (!h || h.role !== ROLE_HOST || h.seq <= recvSeq || h.body.length < 1) return
+ recvSeq = h.seq
+ const tag = h.body[0]
+ const body = h.body.subarray(1)
+ if (state === 'auth') {
+ if (tag !== TAG_RPC || json(new TextDecoder().decode(body))?.type !== 'e2ee_authenticated') return
+ state = 'ready'
+ keepalive = every(() => void sendSealed(TAG_RPC, utf8(KEEPALIVE_JSON)), KEEPALIVE_MS)
+ // After this handler returns: over an in-process transport the host is still inside its own
+ // send and has not created its trust gate yet, and a confirm it cannot see is lost for good.
+ queueMicrotask(() => {
+ sendSealed(TAG_TUNNEL_TEXT, utf8(TRUST_CONFIRM_JSON))
+ maybeOpen()
+ })
+ return
+ }
+ if (state !== 'ready') return
+ if (tag === TAG_TUNNEL_TEXT) {
+ const m = parseTunnelJson(new TextDecoder().decode(body))
+ if (!m) return
+ if (m.t === 'cast' && m.method === 'trust:confirm') {
+ hostConfirmed = true
+ maybeOpen()
+ } else if (m.t === 'cast' && m.method === 'trust:denied') {
+ events.onDenied(typeof m.args[0] === 'string' ? m.args[0] : 'denied')
+ } else if (m.t === 'ev' && opened) {
+ events.onEvent(m.channel, m.args)
+ }
+ return
+ }
+ if (tag === TAG_TUNNEL_BIN && opened) {
+ const f = decodePtyFrame(body)
+ if (f) events.onPtyData(f.sessionId, f.data)
+ }
+ })
+ socket.onClose(() => {
+ const wasOpen = state !== 'closed'
+ shutdown()
+ if (wasOpen) events.onClose()
+ })
+ socket.send(JSON.stringify({ type: 'e2ee_hello', publicKeyB64: bytesToB64(keys.viewer.publicKey), nonceB64: bytesToB64(ourNonce) }))
+
+ return {
+ sendChat(name, text) {
+ if (!opened || state !== 'ready') return false
+ return sendSealed(TAG_TUNNEL_TEXT, utf8(JSON.stringify({ t: 'cast', method: WATCH_CHAT_CAST, args: [{ name, text }] })))
+ },
+ close() {
+ shutdown()
+ socket.close()
+ },
+ isOpen: () => opened && state === 'ready'
+ }
+}
diff --git a/src/shared/watch-link/vectors.json b/src/shared/watch-link/vectors.json
new file mode 100644
index 000000000..2ed65f557
--- /dev/null
+++ b/src/shared/watch-link/vectors.json
@@ -0,0 +1,44 @@
+{
+ "version": 1,
+ "keys": [
+ {
+ "secretHex": "0000000000000000000000000000000000000000000000000000000000000000",
+ "linkId": "AAAAAAAAAAAAAAAAAAAAAA",
+ "hostPublicHex": "248c49740f0280865e9ca638c9cc1f32b015020a6ad0695b0b5c2d7d70ad9e61",
+ "viewerPublicHex": "074dd1d6df9be25839ef8d69e5d9ed41b69523d9255dcc050ca3b409cf6d8961",
+ "joinKeyHex": "257ba29f11037668071cafc88d291c8d63a088cbb2825db768f0b83c74dda201",
+ "joinKeyHashHex": "719d067205a29f7687a7f4c44c49370530eacf2f908f4c8e724b9f88c036d12e",
+ "url": "https://nodeterm.dev/s/AAAAAAAAAAAAAAAAAAAAAA#1.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+ },
+ {
+ "secretHex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+ "linkId": "AbCdEfGhIjKlMnOpQrStUv",
+ "hostPublicHex": "38d7d938cec47e82954388abcaf4c5f5bcf56a8d34f8c23b356db98539f6d408",
+ "viewerPublicHex": "beda76d249bcd037d1511ea2438833aa0cdc57fdbe258c2976baefb049fbbc69",
+ "joinKeyHex": "580abda58a4fda2821d7791d4d6abaaaa2946b7b56c6b09c40bff22d596e91fe",
+ "joinKeyHashHex": "0e46259ff2ae7ae4fa121f053ad89ab71dd8eccd3e68763138c3eb5ddb3951ab",
+ "url": "https://nodeterm.dev/s/AbCdEfGhIjKlMnOpQrStUv#1.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
+ },
+ {
+ "secretHex": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ "linkId": "-_-_-_-_-_-_-_-_-_-_-_",
+ "hostPublicHex": "e7d5c5757e8b6956555f854561fc3858b1856fb9bbf6daf8ef61884bff81742b",
+ "viewerPublicHex": "45df4e450d431b11c6be7dd91dbadfc680a24b10f4e392835d200950fa5a5129",
+ "joinKeyHex": "06774dd6c06178807a798c85add0bdaeb60a03efefe6d48916b7d97cb188799c",
+ "joinKeyHashHex": "7eb31e2557fbe97b6cdb072994bd032bcf9544f2df6251b9de282a657a1b25a4",
+ "url": "https://nodeterm.dev/s/-_-_-_-_-_-_-_-_-_-_-_#1.__________________________________________8"
+ }
+ ],
+ "ptyFrames": [
+ {
+ "sessionId": "s1",
+ "data": "hello",
+ "hex": "010002733168656c6c6f"
+ },
+ {
+ "sessionId": "sess-é",
+ "data": "a\u001b[31mb",
+ "hex": "010007736573732dc3a9611b5b33316d62"
+ }
+ ]
+}
diff --git a/src/shared/watch-link/vectors.test.ts b/src/shared/watch-link/vectors.test.ts
new file mode 100644
index 000000000..3e5296cae
--- /dev/null
+++ b/src/shared/watch-link/vectors.test.ts
@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { deriveWatchLinkKeys, sha256Hex } from './keys'
+import { bytesToHex } from './bytes'
+import { formatWatchLink } from './link'
+import { encodePtyFrame } from './wire'
+
+// vectors.json is what nodeterm-web's copy is tested against. It is the fixture; this test proves
+// the code still produces it. Regenerate ONLY for a deliberate protocol change (bump the version).
+const vectors = JSON.parse(readFileSync(join(__dirname, 'vectors.json'), 'utf8').replace(/\r\n/g, '\n'))
+
+describe('watch-link vectors', () => {
+ it('the code reproduces every vector', async () => {
+ for (const v of vectors.keys) {
+ const secret = Uint8Array.from(Buffer.from(v.secretHex, 'hex'))
+ const k = deriveWatchLinkKeys(secret)
+ expect(bytesToHex(k.host.publicKey)).toBe(v.hostPublicHex)
+ expect(bytesToHex(k.viewer.publicKey)).toBe(v.viewerPublicHex)
+ expect(bytesToHex(k.joinKey)).toBe(v.joinKeyHex)
+ expect(await sha256Hex(k.joinKey)).toBe(v.joinKeyHashHex)
+ expect(formatWatchLink(v.linkId, secret)).toBe(v.url)
+ }
+ for (const f of vectors.ptyFrames) expect(bytesToHex(encodePtyFrame(f.sessionId, f.data))).toBe(f.hex)
+ })
+})
diff --git a/src/shared/watch-link/wire.ts b/src/shared/watch-link/wire.ts
index 8d7ac9e64..95aaa4ebf 100644
--- a/src/shared/watch-link/wire.ts
+++ b/src/shared/watch-link/wire.ts
@@ -1,11 +1,15 @@
// The relay's wire rules, restated without Node so the browser can speak them. The SOURCE of truth
// is src/core/relay/relay-socket.ts + e2ee.ts + src/shared/rpc.ts, and two tests pin this copy to it:
-// - src/core/watch-link/wire.test.ts compares against the originals directly: the seq header, the
-// sealed box (both directions), the pty frame, the tunnel JSON, and the HKDF info string + salt
-// order (against e2ee's deriveSessionKey). An edit to any of those in the originals fails it.
-// - TAG_*, ROLE_* and NONCE_BYTES are module-private in relay-socket.ts, so nothing compares them
-// directly; src/core/watch-link/client.test.ts pins them END TO END, by running the client that
-// uses them against the real host-role relay socket.
+// - src/core/watch-link/wire.test.ts compares against the originals directly: the sealed box (both
+// directions), the pty frame, the tunnel JSON, the HKDF info string + salt order (against e2ee's
+// deriveSessionKey), and NONCE_BYTES against e2ee's randomSessionNonce. An edit to any of those in
+// the originals fails it.
+// - The seq header, TAG_*, ROLE_* and the nonce length the host accepts are module-private in
+// relay-socket.ts, so nothing compares them directly; src/core/watch-link/client.test.ts pins them
+// END TO END, by running the client that uses them against the real host-role relay socket. Its
+// past-seq-255 case is what catches a byte-swapped seq word. The one thing it cannot reach is the
+// order of the two seq words (only a seq past 2^32 would show it), and wire.test.ts pins that
+// layout to a literal copied from relay-socket.ts's private withHeader.
// Both tests live in core because they import core modules the web tsconfig project cannot see.
//
// Sealed box: nonce(24) ‖ nacl.box.after(plain). Plain: [role:1][seqHi u32 LE][seqLo u32 LE][tag:1][body].