herdr-remote-relay 0.2.1 → 0.2.2

package/README.md

@@ -1,27 +1,21 @@
 # herdr-remote-relay
 
-Standalone relay server for [Herdr Remote](https://www.npmjs.com/package/herdr-remote):
-it serves the mobile web terminal and brokers browser ↔ workstation sessions.
+*[English](README.md) · [简体中文](README.zh-CN.md)*
 
-Its only runtime dependency is `ws`, so the machine running it needs no
-compiler, no Herdr and no plugin. It never runs a shell and never touches your
-Herdr socket — only the host connector on your own workstation does that.
+Standalone relay server and WebUI for [Herdr Remote](https://www.npmjs.com/package/herdr-remote).
 
-**You usually do not need to install this yourself.** `herdr-remote` starts a
-relay locally unless you point it at one you host. Install this package only
-when you want to reach your workstation from outside your own network.
+Brokers WebSocket connections between browsers and workstation host connectors. Runtime dependency is `ws` only; requires no compilers or Herdr binaries.
+
+> **Note**: `herdr-remote` runs a local relay automatically. Install this package only when deploying a dedicated relay server.
+
+## Installation
 
 ```bash
 npm install -g herdr-remote-relay
-herdr-remote-relay --public-url https://herdr.example.com \
-  --password your-password --admin-token your-long-random-admin-token \
-  --trust-proxy
+herdr-remote-relay --public-url https://herdr.example.com --password <password>
 ```
 
-Requirements: Node.js 22+, a domain name, and TLS. Terminate TLS in a reverse
-proxy in front of the relay — nginx, Caddy, Traefik and Cloudflare Tunnel all
-work. Example configs for nginx, Cloudflare Tunnel, systemd and Docker Compose
-ship in `deploy/` inside this package.
+Requirements: Node.js 22+, TLS reverse proxy (nginx, Caddy, Cloudflare Tunnel).
 
 ## Docker
 
@@ -32,7 +26,7 @@ docker run -d --name herdr-relay --restart unless-stopped \
   -e RELAY_BIND=0.0.0.0 \
   -e RELAY_PUBLIC_URL=https://herdr.example.com \
   -e RELAY_PASSWORD=your-password \
-  -e RELAY_ADMIN_TOKEN=your-long-random-admin-token \
+  -e RELAY_ADMIN_TOKEN=your-admin-token \
   -e RELAY_TRUST_PROXY=1 \
   -e RELAY_AUTH_STATE_FILE=/data/relay-auth.json \
   node:22-alpine npx -y herdr-remote-relay
@@ -40,63 +34,33 @@ docker run -d --name herdr-relay --restart unless-stopped \
 
 ## Options
 
-Every setting has a flag, an environment variable and a JSON config file key
-(`--config`, or `HERDR_RELAY_CONFIG`). Precedence runs defaults → file →
-environment → flags.
-
-| Variable | Default | |
-|---|---|---|
-| `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | URL browsers open |
-| `RELAY_PASSWORD` | *(none)* | Password a workstation must present. **Empty = public relay** |
-| `RELAY_ADMIN_TOKEN` | *(none)* | Operator token for the relay dashboard at `/admin` |
-| `RELAY_BIND` | `127.0.0.1` | Listen address (`0.0.0.0` in Docker) |
-| `RELAY_PORT` | `8787` | Listen port |
-| `RELAY_TRUST_PROXY` | `0` | Set to `1` behind a reverse proxy |
-| `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | Device records |
-| `RELAY_ALLOWED_ORIGINS` | *(same-origin)* | Extra browser origins, comma separated |
-| `RELAY_MAX_CLIENTS_PER_HOST` | `16` | Browsers per workstation |
-| `RELAY_DEPLOYMENT_MODE` | `remote` | `local` is reserved for the workstation-managed relay |
-
-Whatever proxy you put in front must forward WebSocket upgrades and must not
-time out idle connections — a terminal is idle between keystrokes.
-
-## Public relays
-
-Leaving `RELAY_PASSWORD` empty makes the relay public: anyone may connect a
-workstation to it. That is safe to share, because each workstation is reachable
-only through its own host token — generated on that machine, never handed out
-by the relay. Nobody else can pair a device to your terminal.
-
-What a public relay does give away is bandwidth and the fact that your
-workstation is online. Set a password if that matters.
-
-## Connect a workstation
-
-On the workstation, run `herdr-remote`, open the **Relay** tab and set the
-access mode to **Self-hosted relay**, the relay URL to
-`wss://herdr.example.com`, and the relay password to the same `RELAY_PASSWORD`.
-Then check:
-
+| Option | Env Var | Default | Description |
+|---|---|---|---|
+| `--public-url` | `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | Public URL for browsers |
+| `--password` | `RELAY_PASSWORD` | *(empty)* | Workstation join password (empty = public) |
+| `--admin-token` | `RELAY_ADMIN_TOKEN` | *(empty)* | Operator token for `/admin` |
+| `--bind` | `RELAY_BIND` | `127.0.0.1` | Listen address |
+| `--port` | `RELAY_PORT` | `8787` | Listen port |
+| `--trust-proxy` | `RELAY_TRUST_PROXY` | `0` | Trust `X-Forwarded-For` header (`1` behind proxy) |
+| `--state-file` | `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | Auth state file path |
+| `--allowed-origins` | `RELAY_ALLOWED_ORIGINS` | *(same-origin)* | Allowed CORS origins, comma-separated |
+| `--max-clients` | `RELAY_MAX_CLIENTS_PER_HOST` | `16` | Maximum browser clients per host |
+| `--config` | `HERDR_RELAY_CONFIG` | *(none)* | JSON configuration file path |
+
+Reverse proxies must pass WebSocket `Upgrade` headers and maintain long idle timeouts. Deployment examples for nginx, systemd, and Docker Compose are in `deploy/`.
+
+## Connecting a Workstation
+
+In `herdr-remote` TUI under **Relay** tab:
+- Set mode to **Self-hosted relay**
+- Set Relay URL to `wss://herdr.example.com`
+- Set Relay Password to matching `RELAY_PASSWORD`
+
+Check connection status:
 ```bash
-curl https://herdr.example.com/healthz    # hosts should be 1
+curl https://herdr.example.com/healthz
 ```
 
-| Symptom | Cause |
-|---|---|
-| `hosts: 0` | Workstation not connected — check `herdr-remote status` |
-| `relay_password_required` | Password differs between the two sides |
-| Page loads, terminal never opens | Proxy is not forwarding `Upgrade` headers |
-| Drops after ~60s idle | Proxy read timeout too short |
-
-## Security
-
-- Tokens are stored as SHA-256 hashes, never in clear text. Terminal content is
-  never written to disk.
-- Pairing codes are single-use, expire in ten minutes, and are rate limited.
-- The `/admin` operator credential is separate from the workstation join
-  password and from paired device tokens.
-- Losing the state file just means re-pairing your devices.
-
 ## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,66 @@
+# herdr-remote-relay
+
+*[English](README.md) · [简体中文](README.zh-CN.md)*
+
+[Herdr Remote](https://www.npmjs.com/package/herdr-remote) 的独立 Relay 服务端与 WebUI。
+
+负责在浏览器与工作站主机连接器之间转发 WebSocket 连接。运行时仅依赖 `ws`，无需编译环境或 Herdr 二进制文件。
+
+> **提示**：`herdr-remote` 默认在本地自动运行 relay。仅在需要部署独立中继服务器时安装本包。
+
+## 安装
+
+```bash
+npm install -g herdr-remote-relay
+herdr-remote-relay --public-url https://herdr.example.com --password <密码>
+```
+
+前置要求：Node.js 22+、TLS 反向代理（nginx、Caddy、Cloudflare Tunnel 等）。
+
+## Docker 运行
+
+```bash
+docker run -d --name herdr-relay --restart unless-stopped \
+  -p 127.0.0.1:8787:8787 \
+  -v herdr-relay:/data \
+  -e RELAY_BIND=0.0.0.0 \
+  -e RELAY_PUBLIC_URL=https://herdr.example.com \
+  -e RELAY_PASSWORD=你的密码 \
+  -e RELAY_ADMIN_TOKEN=你的管理令牌 \
+  -e RELAY_TRUST_PROXY=1 \
+  -e RELAY_AUTH_STATE_FILE=/data/relay-auth.json \
+  node:22-alpine npx -y herdr-remote-relay
+```
+
+## 配置参数
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|---|---|---|---|
+| `--public-url` | `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | 浏览器访问的公开地址 |
+| `--password` | `RELAY_PASSWORD` | *(空)* | 工作站接入密码（留空为公用 Relay） |
+| `--admin-token` | `RELAY_ADMIN_TOKEN` | *(空)* | `/admin` 管理后台操作员令牌 |
+| `--bind` | `RELAY_BIND` | `127.0.0.1` | 监听地址 |
+| `--port` | `RELAY_PORT` | `8787` | 监听端口 |
+| `--trust-proxy` | `RELAY_TRUST_PROXY` | `0` | 信任 `X-Forwarded-For` 头（反代后设为 `1`） |
+| `--state-file` | `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | 认证状态文件路径 |
+| `--allowed-origins` | `RELAY_ALLOWED_ORIGINS` | *(同源)* | 允许的跨域源，逗号分隔 |
+| `--max-clients` | `RELAY_MAX_CLIENTS_PER_HOST` | `16` | 每台工作站最大客户端连接数 |
+| `--config` | `HERDR_RELAY_CONFIG` | *(无)* | JSON 配置文件路径 |
+
+反向代理必须转发 WebSocket `Upgrade` 头，并设置较长空闲超时时间。`deploy/` 目录下提供 nginx、systemd 与 Docker Compose 示例。
+
+## 工作站连接
+
+在工作站的 `herdr-remote` TUI 中进入 **Relay** 页面：
+- 访问方式选择 **自建 relay**
+- Relay 地址填写 `wss://herdr.example.com`
+- Relay 密码填写对应的 `RELAY_PASSWORD`
+
+验证连接状态：
+```bash
+curl https://herdr.example.com/healthz
+```
+
+## 开源协议
+
+MIT

package/bin/herdr-remote-relay.js

@@ -17,22 +17,21 @@ const USAGE = `herdr-remote-relay ${VERSION} — standalone relay for Herdr Remo
 Usage: herdr-remote-relay [options]
 
 Options:
-  --password <password>      Password a workstation must present (RELAY_PASSWORD).
-                             Leave unset for a public relay.
-  --admin-token <token>      Operator token for the relay dashboard (RELAY_ADMIN_TOKEN).
-  --deployment-mode <mode>   WebUI deployment mode: local or remote (default remote).
-  --public-url <url>         Public URL browsers use (RELAY_PUBLIC_URL)
+  --password <password>      Workstation password (RELAY_PASSWORD, empty for public)
+  --admin-token <token>      Admin dashboard token (RELAY_ADMIN_TOKEN)
+  --deployment-mode <mode>   Deployment mode: local or remote (default remote)
+  --public-url <url>         Public URL for browsers (RELAY_PUBLIC_URL)
   --bind <address>           Listen address (default 127.0.0.1, RELAY_BIND)
   --port <number>            Listen port (default 8787, RELAY_PORT)
-  --trust-proxy              Read X-Forwarded-For for rate limiting (RELAY_TRUST_PROXY)
-  --state-file <file>        Where device/host records are stored (RELAY_AUTH_STATE_FILE)
-  --allowed-origins <list>   Extra comma-separated browser origins (RELAY_ALLOWED_ORIGINS)
-  --max-clients <number>     Max browsers per workstation (RELAY_MAX_CLIENTS_PER_HOST)
-  --config <file>            JSON config file (also HERDR_RELAY_CONFIG)
-  -h, --help                 Show this help
-  -v, --version              Show the version
+  --trust-proxy              Trust X-Forwarded-For headers (RELAY_TRUST_PROXY)
+  --state-file <file>        Auth state file path (RELAY_AUTH_STATE_FILE)
+  --allowed-origins <list>   Allowed browser origins, comma-separated
+  --max-clients <number>     Max clients per workstation (default 16)
+  --config <file>            JSON config file (HERDR_RELAY_CONFIG)
+  -h, --help                 Show help
+  -v, --version              Show version
 
-See docs/self-hosted-relay.md.
+Guide: docs/self-hosted-relay.md
 `;
 
 function webUiBuilt() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "herdr-remote-relay",
-  "version": "0.2.1",
-  "description": "Standalone relay server for Herdr Remote: serves the mobile web terminal and brokers browser <-> workstation sessions",
+  "version": "0.2.2",
+  "description": "Standalone relay server and web terminal for Herdr Remote",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,7 +37,8 @@
     "src",
     "web/dist",
     "deploy",
-    "config.example.json"
+    "config.example.json",
+    "README.zh-CN.md"
   ],
   "scripts": {
     "build": "npm --prefix web run build",

package/src/metrics.js

@@ -92,15 +92,19 @@ class RelayMetrics {
     }
     const memory = process.memoryUsage();
     const load = os.loadavg();
-    const controller = clients.find((client) => client.role === 'controller');
+    // Every attached window has full input, so there is no "active controller"
+    // to name: reporting the first of them as one had an operator reading a
+    // distinction that does not exist. The host is still worth naming, and any
+    // client knows which workstation it is on.
+    const anyClient = clients[0];
     return {
       version: this.version,
       protocolVersion: this.protocolVersion,
       uptimeSeconds: Math.floor((now - this.startedAt) / 1000),
       startTime: new Date(this.startedAt).toISOString(),
       serverTime: new Date(now).toISOString(),
-      activeControllerId: controller?.id || null,
-      activeHostId: controller?.hostId || hosts[0]?.id || null,
+      activeControllerId: null,
+      activeHostId: anyClient?.hostId || hosts[0]?.id || null,
       clients,
       hosts,
       ptys,

package/src/relay-server.js

@@ -11,13 +11,26 @@ const { loadRelayConfig, defaultStateDir, PACKAGE_ROOT } = require('./relay-conf
 const { AuthStore } = require('./auth-store');
 const { RelayMetrics } = require('./metrics');
 const { unpackStreamFrame, packStreamFrame, sanitizeTerminalPalette } = require('./stream-frame');
-const { isWheelOnlyInput } = require('./scroll-input');
 const { ensureDir } = require('./state');
 
 const VERSION = require('../package.json').version;
 const { PROTOCOL_VERSION } = require('./stream-frame');
 const MAX_DIMENSION = 500;
 
+/**
+ * How much recent PTY output the relay keeps per shared session.
+ *
+ * A browser that joins a session already in progress has missed everything
+ * printed before it arrived. Replaying the tail of the stream is what makes
+ * "every window shows the same thing" true on the *first* frame rather than
+ * only after the next repaint.
+ */
+const SESSION_REPLAY_BYTES = 512 * 1024;
+
+/** Never shrink a shared grid below something a program can still draw in. */
+const MIN_SHARED_COLS = 20;
+const MIN_SHARED_ROWS = 6;
+
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
 }
@@ -433,6 +446,10 @@ class RelayServer {
           arch: typeof message.arch === 'string' ? message.arch.slice(0, 32) : process.arch,
           connectedAt: new Date(pending.connectedAt).toISOString(),
           connectedAtMs: pending.connectedAt,
+          // One shared terminal per workstation. Every browser attached to this
+          // host reads and writes the same PTY, so what one window shows is
+          // what all of them show.
+          session: null,
           // Colors are the workstation's to declare, but only in the one shape
           // a browser renderer accepts.
           terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
@@ -472,9 +489,14 @@ class RelayServer {
         closeSocket(host.ws, 1003, error.message);
         return;
       }
-      const client = this.clients.get(frame.streamId);
-      if (frame.type !== 'output' || !client || client.hostId !== host.id) return;
-      if (isOpen(client.ws)) {
+      // Output belongs to the workstation's one shared session, so it goes to
+      // every browser attached to it rather than to a single stream owner.
+      const session = host.session;
+      if (frame.type !== 'output' || !session || session.streamId !== frame.streamId) return;
+      this.rememberOutput(session, frame.payload);
+      for (const clientId of host.clients) {
+        const client = this.clients.get(clientId);
+        if (!client || !isOpen(client.ws)) continue;
         client.ws.send(frame.payload);
         client.bytesSent += frame.payload.length;
         this.metrics.recordOut(frame.payload.length);
@@ -488,16 +510,168 @@ class RelayServer {
       host.ptys = Array.isArray(message.ptys) ? message.ptys.slice(0, 256) : [];
       return;
     }
-    const client = typeof message.clientId === 'string' ? this.clients.get(message.clientId) : null;
-    if (!client || client.hostId !== host.id) return;
+    // Session-level news concerns the whole room: the host talks about the one
+    // shared stream, and every attached browser has to hear it.
+    const session = host.session;
+    const streamId = typeof message.clientId === 'string' ? message.clientId : message.streamId;
+    if (!session || (streamId && streamId !== session.streamId)) return;
     if (message.type === 'session_ready') {
-      jsonSend(client.ws, { type: 'session_ready', clientId: client.id });
+      session.ready = true;
+      this.broadcastToClients(host, (client) => ({ type: 'session_ready', clientId: client.id }));
     } else if (message.type === 'session_exit') {
-      jsonSend(client.ws, { type: 'exit', code: Number.isInteger(message.code) ? message.code : null });
-      this.detachClient(client, { notify: false });
+      const code = Number.isInteger(message.code) ? message.code : null;
+      host.session = null;
+      this.broadcastToClients(host, () => ({ type: 'exit', code }));
+      for (const clientId of [...host.clients]) {
+        const client = this.clients.get(clientId);
+        if (client) this.detachClient(client, { notify: false });
+      }
     } else if (message.type === 'error') {
-      jsonSend(client.ws, { type: 'error', code: message.code || 'host_error', message: String(message.message || 'Host connector error') });
+      this.broadcastToClients(host, () => ({
+        type: 'error',
+        code: message.code || 'host_error',
+        message: String(message.message || 'Host connector error'),
+      }));
+    }
+  }
+
+  /** Send one JSON message to every browser attached to `host`. */
+  broadcastToClients(host, build) {
+    for (const clientId of [...host.clients]) {
+      const client = this.clients.get(clientId);
+      if (!client) continue;
+      const payload = build(client);
+      if (payload) jsonSend(client.ws, payload);
+    }
+  }
+
+  /** Keep the tail of the shared stream so a late joiner can be caught up. */
+  rememberOutput(session, payload) {
+    session.replay.push(Buffer.from(payload));
+    session.replayBytes += payload.length;
+    while (session.replayBytes > SESSION_REPLAY_BYTES && session.replay.length > 1) {
+      session.replayBytes -= session.replay.shift().length;
+    }
+  }
+
+  /**
+   * The grid the shared PTY runs at.
+   *
+   * The smallest attached window wins, exactly as it does in tmux: a column a
+   * phone cannot show is a column the program must not paint, or every other
+   * window sees wrapped rubbish. Nothing else keeps a shared terminal legible
+   * on two different screens at once.
+   */
+  sharedDimensions(host) {
+    let cols = MAX_DIMENSION;
+    let rows = MAX_DIMENSION;
+    let found = false;
+    for (const clientId of host.clients) {
+      const client = this.clients.get(clientId);
+      if (!client) continue;
+      found = true;
+      cols = Math.min(cols, client.cols);
+      rows = Math.min(rows, client.rows);
+    }
+    if (!found) return null;
+    return {
+      cols: Math.max(MIN_SHARED_COLS, cols),
+      rows: Math.max(MIN_SHARED_ROWS, rows),
+    };
+  }
+
+  /**
+   * Attach `client` to the workstation's shared terminal, starting it if this
+   * is the first browser through the door.
+   *
+   * A later arrival does not get its own PTY: it is handed the stream already
+   * running, the output that has been printed so far, and — once the geometry
+   * has settled — a repaint, so it lands on the same screen everyone else is
+   * looking at.
+   */
+  attachSession(host, client) {
+    if (!host.session) {
+      host.session = {
+        streamId: randomId('session'),
+        cols: client.cols,
+        rows: client.rows,
+        ready: false,
+        replay: [],
+        replayBytes: 0,
+      };
+      const dims = this.sharedDimensions(host) || { cols: client.cols, rows: client.rows };
+      host.session.cols = dims.cols;
+      host.session.rows = dims.rows;
+      jsonSend(host.ws, {
+        type: 'session_start',
+        clientId: host.session.streamId,
+        streamId: host.session.streamId,
+        cols: dims.cols,
+        rows: dims.rows,
+        role: 'controller',
+      });
+      // Said out loud even when this window is the only one, so a browser that
+      // reconnects is never left painting the grid of a session that has since
+      // been torn down and started again at a different size.
+      jsonSend(client.ws, { type: 'shared_resize', cols: dims.cols, rows: dims.rows });
+      return;
+    }
+
+    const session = host.session;
+    if (session.ready) jsonSend(client.ws, { type: 'session_ready', clientId: client.id });
+    for (const chunk of session.replay) {
+      if (!isOpen(client.ws)) break;
+      client.ws.send(chunk);
+      client.bytesSent += chunk.length;
+    }
+    // Geometry may now be smaller than it was; the resize doubles as the
+    // repaint that puts the newcomer on the same screen as everyone else.
+    this.syncDimensions(host, { force: true });
+  }
+
+  /**
+   * Push the shared grid to the workstation.
+   *
+   * `force` asks for a repaint even when the numbers did not move: a browser
+   * that just joined needs the program to draw itself again, and a resize is
+   * the only signal a PTY has for "paint everything".
+   */
+  syncDimensions(host, { force = false } = {}) {
+    const session = host.session;
+    if (!session) return;
+    const dims = this.sharedDimensions(host);
+    if (!dims) return;
+    const changed = dims.cols !== session.cols || dims.rows !== session.rows;
+    session.cols = dims.cols;
+    session.rows = dims.rows;
+    if (!changed && !force) return;
+    // Every window has to be told what the shared grid became, not just the
+    // workstation. A browser that keeps rendering at its own width would wrap
+    // a stream written for a narrower terminal, which is the one thing a
+    // shared session must not do: the same bytes have to look the same in
+    // every window.
+    this.broadcastToClients(host, () => ({
+      type: 'shared_resize',
+      cols: dims.cols,
+      rows: dims.rows,
+    }));
+    if (!changed && force) {
+      // A no-op resize is ignored by the PTY, so bounce one row and come back.
+      jsonSend(host.ws, {
+        type: 'resize',
+        clientId: session.streamId,
+        streamId: session.streamId,
+        cols: dims.cols,
+        rows: Math.max(MIN_SHARED_ROWS, dims.rows - 1),
+      });
     }
+    jsonSend(host.ws, {
+      type: 'resize',
+      clientId: session.streamId,
+      streamId: session.streamId,
+      cols: dims.cols,
+      rows: dims.rows,
+    });
   }
 
   handleClientConnection(ws, req) {
@@ -522,18 +696,12 @@ class RelayServer {
         const host = this.hosts.get(device.hostId);
         if (!host) return this.rejectHandshake(ws, 'paired Herdr host is offline', 'host_offline');
 
-        // One live session per browser. A browser that reconnects before the
-        // relay has noticed the old socket is gone would otherwise end up
-        // holding two sessions: the stale one keeps the controller lease, so
-        // the reconnected tab is stuck read-only against its own ghost. Retire
-        // that session first; the controller lease is released with it and this
-        // connection can take it again.
-        //
-        // Keyed on the browser-supplied client id, not on the device token:
-        // sharing one token across two browsers is the supported multi-viewer
-        // case and must keep working.
-        this.detachSupersededSession(device.deviceId, message.clientId, host);
-
+        // Two tabs of one browser are two windows onto the same terminal, not
+        // rivals. Nothing is retired here: the relay used to close whichever
+        // session shared this browser's client id, which made two open tabs
+        // evict each other in a loop that never converged — each eviction
+        // triggered the other tab's auto-reconnect, which evicted this one
+        // back, forever.
         if (host.clients.size >= this.config.relay.maxClientsPerHost) return this.rejectHandshake(ws, 'host client limit reached', 'too_many_clients');
         clearTimeout(deadline);
         const clientId = randomId('client');
@@ -545,8 +713,11 @@ class RelayServer {
           // Stable per browser profile; used to recognise a reconnect from the
           // same browser rather than a genuinely separate viewer.
           browserClientId: typeof message.clientId === 'string' ? message.clientId : null,
-          role: host.controllerId ? 'viewer' : 'controller',
-          controllerId: host.controllerId,
+          // Every paired window may type. Pairing is the permission boundary;
+          // once a device is through it, holding a second window read-only
+          // serves nobody — they are all views of one shared terminal.
+          role: 'controller',
+          controllerId: null,
           connectedAt: new Date().toISOString(),
           connectedAtMs: Date.now(),
           lastSeenAt: Date.now(),
@@ -558,8 +729,7 @@ class RelayServer {
           cols: clampDimension(message.cols, 80),
           rows: clampDimension(message.rows, 24),
         };
-        if (client.role === 'controller') host.controllerId = client.id;
-        client.controllerId = host.controllerId;
+        client.controllerId = null;
         // Persist how this device identifies itself so the operator dashboard
         // can name it in the revoke list instead of showing a bare device id.
         this.auth.noteDeviceSeen(device.deviceId, { userAgent: client.userAgent, ip: client.ip });
@@ -580,14 +750,19 @@ class RelayServer {
         jsonSend(ws, {
           type: 'ready',
           role: client.role,
-          controllerId: host.controllerId,
+          // There is no controller to name: every window has full input. The
+          // field stays in the message for clients built against protocol 1,
+          // which read it to decide whether somebody else held the lease — and
+          // `null` is exactly the answer that means "nobody does".
+          controllerId: null,
           hostId: host.id,
           clientId: client.id,
           // Delivered with `ready`, before the first PTY byte, so the terminal
           // is painted in the host's colors from its very first frame.
           terminalPalette: host.terminalPalette || null,
+          clientCount: host.clients.size,
         });
-        jsonSend(host.ws, { type: 'session_start', clientId: client.id, streamId: client.id, cols: client.cols, rows: client.rows, role: client.role });
+        this.attachSession(host, client);
         this.broadcastControlState(host);
         return;
       }
@@ -605,16 +780,12 @@ class RelayServer {
     const host = this.hosts.get(client.hostId);
     if (!host) return this.detachClient(client, { notify: true, reason: 'host_offline' });
     if (isBinary) {
-      // A read-only device may still scroll. Like `resize` below, scrolling is
-      // not a shared-terminal action: each client drives its own PTY stream, so
-      // a wheel report moves only that viewer's own screen. Everything else —
-      // keystrokes, clicks, drags — stays behind the control lease.
-      if (client.role !== 'controller' && !isWheelOnlyInput(raw)) {
-        jsonSend(client.ws, { type: 'control_denied', message: 'this device is read-only' });
-        return;
-      }
       if (raw.length > this.config.relay.maxPayloadBytes) return;
-      const frame = packStreamFrame('input', client.id, raw);
+      const session = host.session;
+      if (!session) return;
+      // Every window writes into the one shared terminal, so input is stamped
+      // with the session's stream id rather than the sender's.
+      const frame = packStreamFrame('input', session.streamId, raw);
       if (isOpen(host.ws)) {
         host.ws.send(frame);
         client.bytesReceived += raw.length;
@@ -631,47 +802,41 @@ class RelayServer {
       client.lastPingAt = new Date().toISOString();
       jsonSend(client.ws, { type: 'pong' });
     } else if (message.type === 'resize') {
-      // Every client drives its *own* PTY stream — `session_start` is emitted
-      // per client with `streamId: client.id`, and the host resizes only that
-      // session — so geometry is not a shared-terminal action and must not
-      // require the control lease. Gating it here left a viewer's PTY at the
-      // 80x24 it was opened with: the agent then painted into a grid the
-      // terminal did not have, leaving blank rows under the content and
-      // columns clipped off the right edge.
+      // The shared grid is the smallest attached window, so one client's resize
+      // is recomputed across the room rather than applied on its own.
       client.cols = clampDimension(message.cols, client.cols);
       client.rows = clampDimension(message.rows, client.rows);
-      jsonSend(host.ws, { type: 'resize', clientId: client.id, cols: client.cols, rows: client.rows });
+      this.syncDimensions(host);
     } else if (message.type === 'claim_control') {
-      this.claimControl(host, client, Boolean(message.force));
+      // Control is no longer a lease. Answering the old request keeps clients
+      // built against the previous protocol working.
+      client.role = 'controller';
+      jsonSend(client.ws, { type: 'control_granted' });
     } else if (message.type === 'release_control') {
-      if (host.controllerId === client.id) {
-        host.controllerId = null;
-        this.broadcastControlState(host);
-      }
-    }
-  }
-
-  claimControl(host, client, force) {
-    if (host.controllerId === client.id) return jsonSend(client.ws, { type: 'control_granted' });
-    if (host.controllerId && !force) return jsonSend(client.ws, { type: 'control_denied', message: 'another device currently controls this Herdr' });
-    const previous = host.controllerId ? this.clients.get(host.controllerId) : null;
-    if (previous) {
-      previous.role = 'viewer';
-      jsonSend(previous.ws, { type: 'control_revoked', controllerId: client.id });
+      // Nothing to release: the window keeps its input either way, and saying
+      // so beats a silence an older client would wait on.
+      jsonSend(client.ws, { type: 'control_state', role: 'controller', controllerId: null });
     }
-    host.controllerId = client.id;
-    client.role = 'controller';
-    jsonSend(client.ws, { type: 'control_granted' });
-    this.broadcastControlState(host);
   }
 
+  /**
+   * Tell every window who is attached.
+   *
+   * There is no controller to announce any more, so this carries the one fact
+   * that changed: how many windows now share this terminal.
+   */
   broadcastControlState(host) {
     for (const clientId of host.clients) {
       const client = this.clients.get(clientId);
       if (!client) continue;
-      client.role = host.controllerId === client.id ? 'controller' : 'viewer';
-      client.controllerId = host.controllerId;
-      jsonSend(client.ws, { type: 'control_state', role: client.role, controllerId: host.controllerId || null });
+      client.role = 'controller';
+      client.controllerId = null;
+      jsonSend(client.ws, {
+        type: 'control_state',
+        role: 'controller',
+        controllerId: null,
+        clientCount: host.clients.size,
+      });
     }
   }
 
@@ -693,47 +858,25 @@ class RelayServer {
     return closed;
   }
 
-  /**
-   * Retire the session the same browser already holds on this host, if any.
-   *
-   * `browserClientId` is the identifier the browser persists for itself, so two
-   * tabs of one browser collapse to a single session while two genuinely
-   * different browsers sharing a device token stay independent viewers. A
-   * client that sends no id cannot be matched and is left alone.
-   */
-  detachSupersededSession(deviceId, browserClientId, host) {
-    if (!deviceId || typeof browserClientId !== 'string' || !browserClientId) return 0;
-    let closed = 0;
-    for (const clientId of [...host.clients]) {
-      const existing = this.clients.get(clientId);
-      if (!existing || existing.deviceId !== deviceId) continue;
-      if (existing.browserClientId !== browserClientId) continue;
-      this.detachClient(existing, { notify: false, reason: 'superseded_by_new_session' });
-      closeSocket(existing.ws, 1000, 'replaced by a newer session from the same browser');
-      closed += 1;
-    }
-    return closed;
-  }
-
   detachClient(client, { notify = true, reason = 'client_disconnected' } = {}) {
     if (!client || !this.clients.has(client.id)) return;
     this.clients.delete(client.id);
     const host = this.hosts.get(client.hostId);
     if (host) {
       host.clients.delete(client.id);
-      if (isOpen(host.ws)) jsonSend(host.ws, { type: 'session_stop', clientId: client.id });
-      const wasController = host.controllerId === client.id;
-      if (wasController) {
-        host.controllerId = null;
-        const next = [...host.clients]
-          .map((id) => this.clients.get(id))
-          .filter(Boolean)
-          .sort((a, b) => a.connectedAtMs - b.connectedAtMs)[0];
-        if (next) {
-          host.controllerId = next.id;
-          next.role = 'controller';
-          jsonSend(next.ws, { type: 'control_granted' });
+      // The shared terminal outlives any one window: it is torn down only when
+      // the last of them has gone, so closing a tab never kills the session the
+      // other tabs are still watching.
+      if (host.clients.size === 0) {
+        if (host.session) {
+          if (isOpen(host.ws)) {
+            jsonSend(host.ws, { type: 'session_stop', clientId: host.session.streamId, streamId: host.session.streamId });
+          }
+          host.session = null;
         }
+        host.controllerId = null;
+      } else {
+        this.syncDimensions(host);
         this.broadcastControlState(host);
       }
     }
@@ -820,7 +963,14 @@ class RelayServer {
       activePtyCount: host.ptys.length,
       load: host.load,
     }));
-    const ptys = [...this.hosts.values()].flatMap((host) => host.ptys.map((pty) => ({ ...pty, hostId: host.id })));
+    // The workstation counts one PTY per stream and cannot know how many
+    // windows are watching it; the relay does, and that is the number an
+    // operator needs when the session is shared.
+    const ptys = [...this.hosts.values()].flatMap((host) => host.ptys.map((pty) => ({
+      ...pty,
+      hostId: host.id,
+      activeClients: host.clients.size,
+    })));
     // The paired-device roster identifies people's hardware, so it is served to
     // the relay operator only — never on /api/status, which any paired device
     // may read.