@andrian.yablonskyy/thub-agent 1.1.19 → 1.1.20

package/README.md

@@ -45,6 +45,10 @@ thub cancel   <jobId>          Cancel a job
 thub power    on|off|reset <jobId> [--delay <sec>] [--port <n>]   Switch the USB power of the Client running your job (owner only)
 thub report   <jobId> [--post gitlab|bitbucket|github] [--commit-status]   The job's report, or a sticky MR/PR comment
 thub resources                 List resources and their status
+thub reserve  <client> [--for <dur>]   Only your jobs run on this runner until then (default 1h)
+thub release  <client>                 End your reservation (maintainers: anyone's)
+thub connect  <client> [--target <name>]   Your reserved board's UARTs and SWD (GDB) on local ports
+thub console  <client> [--uart <n>]    A reserved board's UART in this terminal (Ctrl-] quits)
 thub jobs     [--mine] [--state <s>]   List recent jobs (a cli token: only its own; a ci token: all, or its own with --mine)
 thub config   set <key> <value>        Save coordinator URL / key / default user locally
 thub check-update                      Compare this Agent with the latest published version
@@ -173,6 +177,12 @@ thub run --type sw --download-file https://does-not-exist.invalid/app.bin \
 
 **Run in a resource group:** there's no `--group` option. An admin or maintainer gives your user (or a CI token) one group on the dashboard, and every job it submits runs only on that group's resources; `thub whoami` shows it.
 
+**Reserve a board** to iterate on it without a pipeline taking it between your runs: `thub reserve lab-hw-01 --for 2h`. Until then the scheduler gives lab-hw-01 only your jobs (`thub run --client lab-hw-01 …`); everyone else's go to another runner or wait. `thub release lab-hw-01` gives it back early, otherwise it frees itself when the time is up — a job still running keeps running. `--for` takes whole minutes (`30m`, `2h`) up to the runner's own maximum (8 h unless a maintainer set another on its card); reserving it again extends it from now. `thub resources` shows who holds what. Needs a user's key — a CI token can't reserve.
+
+**Its UARTs and SWD on your machine:** `thub connect lab-hw-01 --target stm32f4x` keeps a live connection to the reserved board and prints the link and a local port per device: UART 1 on `127.0.0.1:5001` (and up; `--uart-port`), ST-Link 1's GDB server on `127.0.0.1:3333` (and up; `--gdb-port`) — `arm-none-eabi-gdb -ex "target extended-remote 127.0.0.1:3333"`, `socat -,raw,echo=0 TCP:127.0.0.1:5001`, or pyserial's `socket://127.0.0.1:5001`. Each GDB connection starts its own OpenOCD on the Client with `target/<name>.cfg` (`--target`, else the probe's OpenOCD target set on the runner card). `thub console lab-hw-01 --uart 1` puts a UART right in your terminal (Ctrl-] quits). A dropped connection is made again by itself (a UART port stays connected through it, GDB has to reconnect); the session ends with the reservation. Each reservation has its own link (`thub reserve` prints it): reserve again later and `thub connect` again for the new one.
+
+**Watch the board:** on a runner with a USB camera (label `video-stream`), its stream starts with your reservation, and `thub connect` prints a local link of that reservation's own — `http://127.0.0.1:8090/<reservation id>/video.ts` (`--video-port`) for VLC, ffplay or mpv; `--video-udp 5600` also sends it as UDP to `udp://127.0.0.1:5600`.
+
 **Who submitted a job** comes from your key: your username (a CI token: its name), shown on the dashboard, in `thub jobs`, on the Client's console and as `JOB_USER`. There's no `--user`.
 
 ## Environment variables and secrets

package/RELEASE.md

@@ -2,6 +2,12 @@
 
 What changed in each release, newest first. `## Unreleased` collects the changes since the version on npm; `bin/publish` turns that heading into the version and date it releases.
 
+## 1.1.20 — 2026-10-15
+
+### Changed
+
+- Requires thub-common 2.2.3.
+
 ## 1.1.19 — 2026-10-14
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-agent",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Andrian Yablonskyy <andrian.yablonskyy@gmail.com>",
@@ -15,8 +15,9 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^2.2.2",
-    "commander": "^13.1.0"
+    "@andrian.yablonskyy/thub-common": "^2.2.3",
+    "commander": "^13.1.0",
+    "ws": "8.21.3"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",

package/src/cli.js

@@ -2,7 +2,7 @@
 
 /**
  * @file        packages/agent/src/cli.js
- * @description thub CLI entry point: run/status/cancel/power/report/resources/jobs/config commands (README §7)
+ * @description thub CLI entry point: run/status/cancel/power/report/resources/reserve/release/connect/console/jobs/config commands (README §7)
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -18,8 +18,9 @@
 const { Command } = require('commander'),
   {
     ApiClient, EXIT_CODES, ACTIVE_JOB_STATES, exitCodeForJobState, PACKAGES, fetchLatestVersion, isNewer, isValidVersion, formatDateTime,
-    parseEnvList, POWER_ACTIONS, DEFAULT_RESET_DELAY_SEC, MAX_RESET_DELAY_SEC, powerRequestErrors
+    parseEnvList, POWER_ACTIONS, DEFAULT_RESET_DELAY_SEC, MAX_RESET_DELAY_SEC, powerRequestErrors, OPENOCD_TARGET_RE
   } = require('@andrian.yablonskyy/thub-common'),
+  { RemoteSession, listenLocal, serveVideo } = require('./remote'),
   { resolveConnection, writeConfigFile, readConfigFile, CONFIG_PATH } = require('./config'),
   { parseDurationSec } = require('./duration'),
   { followJob } = require('./streaming'),
@@ -384,6 +385,7 @@ program
         ['STATUS', (r) => r.status],
         ['BUSY', (r) => r.busySource || '-'],
         ['LABELS', (r) => r.labels.join(',')],
+        ['RESERVED', (r) => (r.reservation ? `${r.reservation.by} until ${formatDateTime(r.reservation.until)}` : '-')],
         ['LAST HEARTBEAT', (r) => r.lastHeartbeatAt || 'never']
       ]);
     }
@@ -392,6 +394,269 @@ program
     }
   });
 
+// README §5.5: hold a runner for your own jobs for a while — everyone
+// else's go elsewhere or wait — and give it back, or let the time run out.
+program
+  .command('reserve')
+  .description('Reserve a runner for your own jobs, for a while: until then only your jobs run on it')
+  .argument('<client>', 'The runner\'s name or id (thub resources)')
+  .option('--for <duration>', 'How long, e.g. 30m, 2h (default 1h; at most what the runner allows). Again on your own: extends it from now')
+  .option('--json', 'Machine-readable output', false)
+  .action(async (name, opts) => {
+    try {
+      let minutes;
+      if (opts.for !== undefined){
+        const sec = parseDurationSec(opts.for);
+        if (!sec || sec % 60){
+          throw usageError(`--for must be whole minutes, e.g. 30m or 2h (got "${opts.for}")`);
+        }
+        minutes = sec / 60;
+      }
+      const r = await client().post(`/resources/${encodeURIComponent(name)}/reserve`, minutes ? { minutes } : {});
+      if (opts.json){
+        return console.log(JSON.stringify(r));
+      }
+      console.log(`${r.name} is reserved for you until ${formatDateTime(r.reservation.until)}.\n` +
+        `Only your jobs run on it (thub run --client ${r.name} …); thub release ${r.name} when you're done.\n` +
+        `Its UARTs and SWD: thub connect ${r.name} (local ports), thub console ${r.name} (serial in this terminal).` +
+        (r.reservation.link ? `\nThis reservation's link: ${r.reservation.link}` : ''));
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+program
+  .command('release')
+  .description('End your reservation of a runner (maintainers: anyone\'s) — everyone\'s jobs can run on it again')
+  .argument('<client>', 'The runner\'s name or id')
+  .option('--json', 'Machine-readable output', false)
+  .action(async (name, opts) => {
+    try {
+      const r = await client().post(`/resources/${encodeURIComponent(name)}/release`);
+      if (opts.json){
+        return console.log(JSON.stringify(r));
+      }
+      console.log(r.released ? `${r.name} released.` : `${r.name} wasn't reserved.`);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+// README §5.6: the reserved board's UARTs and SWD, live from the Client
+// through the Coordinator — `thub connect` on local TCP ports for any tool
+// (GDB, socat, pyserial), `thub console` right in this terminal. Both make
+// a dropped connection again by themselves, until the reservation ends.
+// Each reservation has its own link (README §5.6): the one you hold now.
+// A later reservation of the same runner is a new link — run this again.
+async function remoteSession(name){
+  const { token } = resolveConnection(program.opts()),
+    { resources } = await client().get('/resources'),
+    r = resources.find((x) => x.name === name || x.id === name);
+  if (!r){
+    throw usageError(`Unknown client "${name}" (thub resources lists them)`);
+  }
+  if (!r.reservation?.link){
+    throw usageError(r.reservation
+      ? `${r.name} is reserved by ${r.reservation.by} — only their reservation's link connects`
+      : `${r.name} isn't reserved — thub reserve ${r.name} first`);
+  }
+  return new RemoteSession({ url: r.reservation.link, token, client: r.name, userAgent: `thub-agent/${version}` });
+}
+
+function onRemoteTrouble(session, log, cleanup){
+  session.on('status', (s) => s.state === 'waiting' &&
+    log(`Waiting for ${s.client}'s Client to connect — it does within a heartbeat of the reservation…`));
+  session.on('disconnected', ({ retryMs, reason }) =>
+    log(`Connection lost${reason ? ` (${reason})` : ''} — reconnecting in ${Math.max(1, Math.round(retryMs / 1000))} s…`));
+  session.on('connected', ({ again }) => again && log('Reconnected.'));
+  session.on('fatal', (message) => {
+    cleanup();
+    fail(Object.assign(new Error(message), { status: EXIT_CODES.USAGE }));
+  });
+}
+
+program
+  .command('connect')
+  .description('Share your reserved board\'s UARTs and SWD (GDB via OpenOCD) on local TCP ports, over a live connection that reconnects by itself')
+  .argument('<client>', 'The runner you reserved (thub reserve)')
+  .option('--target <name>', 'OpenOCD target for SWD, e.g. stm32f4x (target/<name>.cfg; default: the probe\'s openocdTarget on the Client)')
+  .option('--uart-port <port>', 'Local port of UART 1 (UART n: this + n - 1)', (v) => Number(v), 5001)
+  .option('--gdb-port <port>', 'Local GDB port of ST-Link 1 (ST-Link n: this + n - 1)', (v) => Number(v), 3333)
+  .option('--bind <address>', 'Local address to listen on (another than loopback shares the board with your network)', '127.0.0.1')
+  .option('--video-port <port>', 'Local HTTP port of the board\'s USB camera stream, if it has one', (v) => Number(v), 8090)
+  .option('--video-udp <port>', 'Also send the camera stream as UDP (MPEG-TS) to this local port, e.g. 5600', (v) => Number(v))
+  .option('--json', 'Print the ports as JSON once connected', false)
+  .action(async (name, opts) => {
+    try {
+      if (opts.target !== undefined && !OPENOCD_TARGET_RE.test(opts.target)){
+        throw usageError(`--target must be an OpenOCD target script name such as stm32f4x (got "${opts.target}")`);
+      }
+      for (const [flag, v]of [['--uart-port', opts.uartPort], ['--gdb-port', opts.gdbPort], ['--video-port', opts.videoPort],
+        ...(opts.videoUdp !== undefined ? [['--video-udp', opts.videoUdp]] : [])]){
+        if (!Number.isInteger(v) || v < 0 || v > 65535){
+          throw usageError(`${flag} must be a port number`);
+        }
+      }
+      const session = await remoteSession(name),
+        log = (m) => console.error(m);
+      let listening = null,
+        until = null;
+      const cleanup = () => {
+        session.stop();
+        listening?.then(({ servers, video }) => {
+          servers.forEach((srv) => srv.close());
+          video?.close();
+        }).catch(() => {});
+      };
+      onRemoteTrouble(session, log, cleanup);
+      session.on('status', (s) => {
+        until = s.until;
+      });
+      session.on('devices', (devices) => {
+        if (listening){
+          return;
+        }
+        listening = (async () => {
+          const local = await listenLocal(session, devices, {
+              host: opts.bind, uartBase: opts.uartPort, gdbBase: opts.gdbPort, target: opts.target, log
+            }),
+            // The camera (README §5.7) on a URL with this reservation's own id in it.
+            video = devices.camera
+              ? await serveVideo(session, {
+                host: opts.bind, port: opts.videoPort, reservation: session.url.split('/').pop(), udpPort: opts.videoUdp, log
+              })
+              : null;
+          return { ...local, video };
+        })();
+        listening
+          .then(({ ports, video }) => printConnection(name, session.url, until, ports, devices, opts, video))
+          .catch((err) => {
+            cleanup();
+            fail(usageError(err.code === 'EADDRINUSE'
+              ? `Local port ${err.port} is in use — pick others with --uart-port / --gdb-port / --video-port`
+              : `Can't listen locally: ${err.message}`));
+          });
+      });
+      process.on('SIGINT', () => {
+        cleanup();
+        log(`Disconnected from ${name} (its reservation stays — thub release ${name} ends it).`);
+        process.exit(0);
+      });
+      session.start();
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+// The connection link and how to use each port.
+function printConnection(name, link, until, ports, devices, opts, video){
+  if (opts.json){
+    return console.log(JSON.stringify({
+      client: name, link, until, ports: ports.map((p) => ({ kind: p.kind, ...p.device, host: opts.bind, port: p.port })),
+      video: video ? { camera: devices.camera.name, url: video.url, udp: video.udp } : null
+    }));
+  }
+  const host = opts.bind === '0.0.0.0' || opts.bind === '::' ? 'localhost' : opts.bind,
+    lines = [
+      `Connected to ${name}${until ? ` — reserved until ${formatDateTime(until)} (thub release ${name} ends it)` : ''}`,
+      `Link: ${link}`,
+      ''
+    ];
+  for (const { kind, device: d, port }of ports){
+    if (kind === 'uart'){
+      lines.push(`UART ${d.index}  ${d.label}  ${d.baudRate} 8N1  tcp://${host}:${port}`,
+        `        terminal: thub console ${name} --uart ${d.index}`,
+        `        or: socat -,raw,echo=0 TCP:${host}:${port}  ·  pyserial: serial_for_url('socket://${host}:${port}')`);
+    }
+    else {
+      const target = opts.target || d.target;
+      lines.push(`SWD  ${d.index}  ${d.label}${d.serial ? ` (ST-Link ${d.serial})` : ''}  ` +
+        `OpenOCD target ${target || '— none: add --target <name>'}  GDB: ${host}:${port}`,
+      `        arm-none-eabi-gdb -ex "target extended-remote ${host}:${port}"   (each connection starts its own OpenOCD)`);
+    }
+  }
+  if (video){
+    lines.push(`Video   ${devices.camera.name}  H.264 (MPEG-TS)  ${video.url}`,
+      `        vlc ${video.url}  ·  ffplay -fflags nobuffer ${video.url}` +
+      (video.udp ? `\n        UDP: ${video.udp}  (ffplay -fflags nobuffer ${video.udp})` : '  ·  UDP too: --video-udp 5600'));
+  }
+  if (!ports.length && !video){
+    lines.push(`${name} has no UARTs, ST-Links or camera.`);
+  }
+  if (devices.uarts.length && !devices.serial){
+    lines.push('', 'UARTs won\'t open: the \'serialport\' package isn\'t installed on the Client host.');
+  }
+  lines.push('', 'Ctrl-C disconnects; a dropped connection is made again by itself.');
+  console.log(lines.join('\n'));
+}
+
+program
+  .command('console')
+  .description('Your reserved board\'s UART in this terminal: its output here, your typing to the board. Ctrl-] quits')
+  .argument('<client>', 'The runner you reserved (thub reserve)')
+  .option('--uart <n>', 'Which UART (thub connect lists them)', (v) => Number(v), 1)
+  .action(async (name, opts) => {
+    try {
+      const session = await remoteSession(name),
+        log = (m) => process.stderr.write(`\r\n— ${m} —\r\n`),
+        tty = process.stdin.isTTY;
+      let ch = null;
+      const restore = () => {
+          if (tty){
+            process.stdin.setRawMode(false);
+          }
+          process.stdin.pause();
+        },
+        cleanup = () => {
+          session.stop();
+          restore();
+        },
+        quit = (code = 0) => {
+          cleanup();
+          process.stderr.write(`\r\nDisconnected from ${name}.\r\n`);
+          process.exit(code);
+        };
+      onRemoteTrouble(session, log, cleanup);
+      session.on('devices', (devices) => {
+        if (ch !== null){
+          return;
+        }
+        const uart = devices.uarts.find((u) => u.index === opts.uart);
+        if (!uart){
+          cleanup();
+          return fail(usageError(`${name} has no UART ${opts.uart} (it has ${devices.uarts.length})`));
+        }
+        process.stderr.write(`Connected to ${name} UART ${uart.index} (${uart.label}, ${uart.baudRate} 8N1). Ctrl-] quits.\r\n`);
+        ch = session.open('uart', uart.index, {
+          data: (buf) => process.stdout.write(buf),
+          note: log,
+          closed: (reason) => {
+            log(reason);
+            quit(EXIT_CODES.USAGE);
+          }
+        }, { persistent: true });
+        if (tty){
+          process.stdin.setRawMode(true);
+        }
+        process.stdin.on('data', (buf) => {
+          if (buf.includes(0x1d)){
+            return quit();
+          }
+          session.write(ch, buf);
+        });
+        process.stdin.resume();
+      });
+      process.on('SIGINT', () => quit());
+      session.start();
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
 program
   .command('jobs')
   .description('List recent jobs')

package/src/remote.js

@@ -0,0 +1,357 @@
+/**
+ * @file        packages/agent/src/remote.js
+ * @description Remote board access (README §5.6): the Agent's WebSocket session to a reserved runner, reconnecting
+ *              by itself, and the local TCP ports (`thub connect`) and terminal (`thub console`) on top of it
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const net = require('node:net'),
+  http = require('node:http'),
+  dgram = require('node:dgram'),
+  { EventEmitter } = require('node:events'),
+  { decodeData, dataMessages, parseControl, backoffMs, REMOTE_CLOSE } = require('@andrian.yablonskyy/thub-common');
+
+// Without a ping from the Coordinator (every 30 s) for this long, the
+// connection is taken for dead and made again.
+const PING_TIMEOUT_MS = 75_000,
+  // HTTP answers to the upgrade that won't change by trying again.
+  FINAL_STATUSES = new Set([401, 403, 404, 409]);
+
+// One WebSocket to the reservation's own link (/api/v1/remote/<reservation>,
+// from GET /resources), made again whenever it drops (1 s, 2 s, 4 s … 30 s
+// apart) until that reservation ends or stop(). Channels are opened with open(); a `persistent` one (a UART) is
+// opened again on its own once the Client is back, a GDB one is closed —
+// a debugger's state doesn't survive a dropped connection anyway.
+//
+// Events: status ({ state, client, until }), devices ({ uarts, probes }),
+// disconnected ({ retryMs, reason }), connected, fatal (message).
+class RemoteSession extends EventEmitter{
+  constructor({ url, token, client, userAgent, WebSocket = require('ws') }){
+    super();
+    Object.assign(this, { url, token, client, userAgent, WebSocket });
+    this.ws = null;
+    this.ready = false;
+    this.stopped = false;
+    this.attempt = 0;
+    this.everConnected = false;
+    this.channels = new Map(); // ch -> { kind, index, extra, persistent, handler, open, queue }
+    this.nextCh = 1;
+    this.devices = null;
+  }
+
+  start(){
+    this.stopped = false;
+    this._connect();
+    return this;
+  }
+
+  stop(){
+    this.stopped = true;
+    clearTimeout(this.retryTimer);
+    clearTimeout(this.pingTimer);
+    for (const ch of [...this.channels.keys()]){
+      this.close(ch);
+    }
+    this.ws?.close(1000, 'bye');
+  }
+
+  _connect(){
+    if (this.stopped){
+      return;
+    }
+    const ws = new this.WebSocket(this.url, {
+      headers: { Authorization: `Bearer ${this.token}`, ...(this.userAgent ? { 'User-Agent': this.userAgent } : {}) },
+      handshakeTimeout: 15_000
+    });
+    this.ws = ws;
+    let refused = null;
+    const alive = () => {
+      clearTimeout(this.pingTimer);
+      this.pingTimer = setTimeout(() => ws.terminate(), PING_TIMEOUT_MS);
+      this.pingTimer.unref?.();
+    };
+    ws.on('open', () => {
+      this.attempt = 0;
+      alive();
+      this.emit('connected', { again: this.everConnected });
+      this.everConnected = true;
+    });
+    ws.on('ping', alive);
+    ws.on('unexpected-response', (req, res) => {
+      let body = '';
+      res.on('data', (c) => {
+        body += c;
+      });
+      res.on('end', () => {
+        let error;
+        try {
+          error = JSON.parse(body).error;
+        }
+        catch {
+          error = null;
+        }
+        refused = { status: res.statusCode, error: error || `HTTP ${res.statusCode}` };
+        ws.terminate();
+      });
+    });
+    ws.on('message', (data, isBinary) => (isBinary ? this._onData(data) : this._onControl(parseControl(data))));
+    ws.on('error', () => {}); // 'close' follows, and says what to do
+    ws.on('close', (code, reasonBuf) => {
+      clearTimeout(this.pingTimer);
+      if (this.ws !== ws){
+        return;
+      }
+      this.ws = null;
+      this._remoteGone('the connection dropped');
+      const reason = String(reasonBuf || '') || refused?.error || null;
+      if (this.stopped){
+        return;
+      }
+      if ((refused && FINAL_STATUSES.has(refused.status)) || code === REMOTE_CLOSE.RESERVATION_ENDED || code === REMOTE_CLOSE.REPLACED){
+        this.stopped = true;
+        const message = reason || 'The Coordinator ended the connection';
+        for (const ch of [...this.channels.keys()]){
+          this._finish(ch, message);
+        }
+        return this.emit('fatal', message);
+      }
+      const retryMs = backoffMs(this.attempt++);
+      this.emit('disconnected', { retryMs, reason });
+      this.retryTimer = setTimeout(() => this._connect(), retryMs);
+    });
+  }
+
+  // Everything open on the Client side is gone (link or connection down).
+  _remoteGone(reason){
+    this.ready = false;
+    for (const [ch, c]of [...this.channels]){
+      c.open = false;
+      if (!c.persistent){
+        this._finish(ch, reason);
+      }
+    }
+  }
+
+  _onControl(msg){
+    if (!msg){
+      return;
+    }
+    if (msg.t === 'status'){
+      this.emit('status', msg);
+      if (msg.state === 'waiting'){
+        this._remoteGone(`${msg.client || 'the runner'}'s Client went away`);
+      }
+      return;
+    }
+    if (msg.t === 'devices'){
+      this.devices = { uarts: msg.uarts || [], probes: msg.probes || [], serial: msg.serial !== false, camera: msg.camera || null };
+      this.emit('devices', this.devices);
+      // Ready again: every channel still wanted is opened on the Client.
+      this.ready = true;
+      for (const [ch, c]of this.channels){
+        if (!c.open){
+          this._sendOpen(ch, c);
+        }
+      }
+      return;
+    }
+    const c = this.channels.get(msg.ch);
+    if (!c){
+      return;
+    }
+    if (msg.t === 'opened'){
+      c.open = true;
+      c.handler.opened?.(msg);
+      for (const data of c.queue.splice(0)){
+        this._sendData(msg.ch, data);
+      }
+    }
+    else if (msg.t === 'note'){
+      c.handler.note?.(String(msg.text || ''));
+    }
+    else if (msg.t === 'close'){
+      this._finish(msg.ch, msg.reason || 'closed by the Client');
+    }
+  }
+
+  _onData(buf){
+    const frame = decodeData(buf);
+    frame && this.channels.get(frame.ch)?.handler.data?.(frame.data);
+  }
+
+  _sendJson(msg){
+    if (this.ws?.readyState === this.WebSocket.OPEN){
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  _sendData(ch, data){
+    if (this.ws?.readyState === this.WebSocket.OPEN){
+      for (const msg of dataMessages(ch, data)){
+        this.ws.send(msg, { binary: true });
+      }
+    }
+  }
+
+  _sendOpen(ch, c){
+    this._sendJson({ t: 'open', ch, kind: c.kind, index: c.index, ...c.extra });
+  }
+
+  // A new channel to UART/probe `index`. `handler`: { opened(msg), data(buf),
+  // note(text), closed(reason) }. Returns its id.
+  open(kind, index, handler, { persistent = false, extra = {} } = {}){
+    let ch = this.nextCh;
+    while (this.channels.has(ch)){
+      ch = ch >= 0xffff ? 1 : ch + 1;
+    }
+    this.nextCh = ch >= 0xffff ? 1 : ch + 1;
+    const c = { kind, index, extra, persistent, handler, open: false, queue: [] };
+    this.channels.set(ch, c);
+    if (this.ready){
+      this._sendOpen(ch, c);
+    }
+    return ch;
+  }
+
+  // Bytes for the channel's device; queued (GDB's first packets) until the
+  // Client has it open, dropped while a UART waits for the Client to return.
+  write(ch, data){
+    const c = this.channels.get(ch);
+    if (!c){
+      return;
+    }
+    if (c.open){
+      this._sendData(ch, data);
+    }
+    else if (!c.persistent){
+      c.queue.push(data);
+    }
+  }
+
+  close(ch){
+    if (this.channels.has(ch)){
+      this.channels.delete(ch);
+      this._sendJson({ t: 'close', ch });
+    }
+  }
+
+  _finish(ch, reason){
+    const c = this.channels.get(ch);
+    if (c){
+      this.channels.delete(ch);
+      c.handler.closed?.(reason);
+    }
+  }
+}
+
+// `thub connect`: a local TCP port per UART (every connection to it sees the
+// board's output and types to it) and per ST-Link (a GDB server: each
+// connection gets its own OpenOCD on the Client). Returns the servers.
+function listenLocal(session, devices, { host, uartBase, gdbBase, target, log }){
+  const servers = [],
+    bridge = (kind, index, opts) => (sock) => {
+      sock.setNoDelay(true);
+      let ch = null;
+      const end = () => {
+        if (ch !== null){
+          session.close(ch);
+          ch = null;
+        }
+      };
+      ch = session.open(kind, index, {
+        data: (buf) => sock.write(buf),
+        note: (text) => log(`${kind === 'uart' ? 'UART' : 'SWD'} ${index}: ${text}`),
+        closed: (reason) => {
+          ch = null;
+          log(`${kind === 'uart' ? 'UART' : 'SWD'} ${index}: ${reason}`);
+          sock.destroy();
+        }
+      }, opts);
+      sock.on('data', (buf) => ch !== null && session.write(ch, buf));
+      sock.on('close', end);
+      sock.on('error', end);
+    },
+    listen = (port, onConn) => new Promise((resolve, reject) => {
+      const srv = net.createServer(onConn);
+      srv.once('error', reject);
+      srv.listen(port, host, () => {
+        servers.push(srv);
+        resolve(srv.address().port);
+      });
+    });
+  return Promise.all([
+    ...devices.uarts.map(async (u) => ({
+      kind: 'uart', device: u, port: await listen(uartBase ? uartBase + u.index - 1 : 0, bridge('uart', u.index, { persistent: true }))
+    })),
+    ...devices.probes.map(async (p) => ({
+      kind: 'swd', device: p,
+      port: await listen(gdbBase ? gdbBase + p.index - 1 : 0, bridge('swd', p.index, { extra: target ? { target } : {} }))
+    }))
+  ]).then((ports) => ({ servers, ports }));
+}
+
+// `thub connect`: the board's USB camera (README §5.7) — H.264 in MPEG-TS,
+// streamed by the Client since the reservation started — on a local URL
+// that's this reservation's own: http://<host>:<port>/<reservation>/video.ts
+// (VLC, ffplay, mpv). Each viewer is a channel of its own. With `udpPort`,
+// also re-sent as UDP datagrams to udp://<host>:<udpPort> (QGroundControl,
+// GStreamer). Resolves to { server, url, udp, close() }.
+function serveVideo(session, { host, port, reservation, udpPort = null, log }){
+  const target = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host,
+    videoPath = `/${reservation}/video.ts`,
+    server = http.createServer((req, res) => {
+      if (req.method !== 'GET' || req.url !== videoPath){
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        return res.end('Not this reservation\'s video — thub connect prints its current link.\n');
+      }
+      res.writeHead(200, { 'Content-Type': 'video/mp2t', 'Cache-Control': 'no-store' });
+      let ch = session.open('video', 1, {
+        data: (buf) => res.write(buf),
+        note: (text) => log(`Video: ${text}`),
+        closed: (reason) => {
+          ch = null;
+          log(`Video: ${reason}`);
+          res.end();
+        }
+      }, { persistent: true });
+      req.on('close', () => ch !== null && session.close(ch));
+    });
+  let udp = null,
+    udpCh = null;
+  if (udpPort){
+    udp = dgram.createSocket(target.includes(':') ? 'udp6' : 'udp4');
+    udp.on('error', (err) => log(`Video (UDP): ${err.message}`));
+    udpCh = session.open('video', 1, {
+      data: (buf) => udp.send(buf, udpPort, target),
+      note: (text) => log(`Video: ${text}`),
+      closed: (reason) => log(`Video (UDP): ${reason}`)
+    }, { persistent: true });
+  }
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve({
+      server,
+      url: `http://${target.includes(':') ? `[${target}]` : target}:${server.address().port}${videoPath}`,
+      udp: udpPort ? `udp://${target}:${udpPort}` : null,
+      close: () => {
+        server.close();
+        server.closeAllConnections?.();
+        if (udpCh !== null){
+          session.close(udpCh);
+        }
+        udp?.close();
+      }
+    }));
+  });
+}
+
+module.exports = { RemoteSession, listenLocal, serveVideo };