herdr-remote 0.2.18 → 0.2.20

package/src/host-connector.js

@@ -1,1069 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { WebSocket } = require('ws');
-const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require('./config');
-const { ensureDir } = require('./state');
-const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
-const { PtySession } = require('./pty-session');
-const {
-  resolveHerdrCommand,
-  verifyHerdrCommand,
-  herdrNotFoundMessage,
-  herdrOutdatedMessage,
-  herdrVersion,
-} = require('./herdr-command');
-// The wire format lives in the relay package so both ends of the protocol are
-// generated from one definition.
-const {
-  packStreamFrame,
-  unpackStreamFrame,
-  packStreamFrameV2,
-  FRAME_TYPE_OUTPUT,
-  PROTOCOL_VERSION,
-  TERMINAL_FONT_CHUNK_BYTES,
-} = require('herdr-remote-relay/protocol');
-const { resolveHostPalette } = require('./terminal-palette');
-const { loadHostTerminalFont, publicTerminalFont, readFontChunk } = require('./terminal-font');
-const { FontSubsetter } = require('./font-subset');
-const { requestHerdr, subscribeHerdr } = require('./herdr-api');
-const { sameSummary, summarizeAgents } = require('./agent-status');
-const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
-const { savePastedFile, cleanPastedDir } = require('./pasted-files');
-const { ensureHerdrServer, probeHerdrServer } = require('./herdr-server');
-const {
-  checkForUpdate,
-  compareVersions,
-  currentVersion,
-  installedVersionOnDisk,
-  updateChecksEnabled,
-} = require('./updater');
-
-/** Windows opening within this long of a check reuse its answer. */
-const UPDATE_RECHECK_MS = 60_000;
-
-/** Cut fonts kept for the slices a browser has yet to fetch, by total size. */
-const FONT_SUBSET_CACHE_BYTES = 48 * 1024 * 1024;
-
-/** How often the agent summary is re-read while a browser is watching. */
-const AGENT_STATUS_POLL_MS = 5_000;
-const AGENT_STATUS_EVENT_DEBOUNCE_MS = 150;
-const AGENT_STATUS_SUBSCRIPTIONS = [
-  { type: 'pane.focused' },
-  { type: 'tab.focused' },
-  { type: 'workspace.focused' },
-  { type: 'pane.agent_detected' },
-];
-
-function randomId(prefix) {
-  return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
-}
-
-function sendJson(ws, payload) {
-  if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(payload));
-}
-
-function closeSocket(ws, reason = 'host connector stopping') {
-  if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) return;
-  try { ws.close(1000, reason); } catch {}
-}
-
-function terminateSocket(ws) {
-  if (!ws || ws.readyState === WebSocket.CLOSED) return;
-  try {
-    if (typeof ws.terminate === 'function') {
-      ws.terminate();
-    } else if (typeof ws.destroy === 'function') {
-      ws.destroy();
-    } else if (typeof ws.close === 'function') {
-      ws.close();
-    }
-  } catch {}
-}
-
-function pidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error.code === 'EPERM';
-  }
-}
-
-class HostConnector {
-  /**
-   * A session that dies this fast never really started. Anything longer is a
-   * session the user actually used and then left.
-   */
-  static FAST_FAILURE_MS = 1500;
-  /** How many broken starts in a row before we stop calling them exits. */
-  static FAST_FAILURE_LIMIT = 3;
-
-  constructor(options = {}) {
-    const config = options.config || loadConfig();
-    this.config = config;
-    this.relayUrl = options.relayUrl
-      || (process.env.RELAY_URL ? hostWebSocketUrl(process.env.RELAY_URL) : resolveHostRelayUrl(config));
-    this.hostId = options.hostId || process.env.RELAY_HOST_ID || randomId('host');
-    this.hostToken = options.hostToken || process.env.RELAY_HOST_TOKEN || '';
-    // Optional; a relay without a password accepts any workstation.
-    this.relayPassword = options.relayPassword ?? process.env.RELAY_PASSWORD ?? '';
-    this.socketPath = options.socketPath || resolveSocketPath(config.herdr.socketPath);
-    // Where to look for Herdr when the command has to be resolved again; the
-    // real environment unless a caller narrows it.
-    this.herdrLookup = options.herdrLookup || {};
-    this.herdrCommand = options.herdrCommand || resolveHerdrCommand(this.herdrLookup);
-    this.readHerdrVersion = options.readHerdrVersion || herdrVersion;
-    this.herdrVersionWarned = false;
-    this.herdrArgs = options.herdrArgs || config.herdr.args;
-    this.cwd = options.cwd || config.herdr.cwd;
-    /**
-     * What the workstation's own terminal looks like. A browser has no way to
-     * know it — the PTY carries color indices, not colors — so the host reports
-     * it and the browser renders the session the way the workstation sees it.
-     * Normally captured by the start path that still had a terminal and passed
-     * down in the environment; `null` when nobody could ask.
-     */
-    this.terminalPalette = options.terminalPalette !== undefined
-      ? options.terminalPalette
-      : resolveHostPalette();
-    /**
-     * The terminal's font, with the local files behind it. Only the family,
-     * size and file hashes leave this process; a browser that lacks the font
-     * fetches the files by hash, one chunk at a time. Injectable for tests.
-     */
-    this.loadTerminalFont = options.loadTerminalFont || loadHostTerminalFont;
-    this.terminalFont = options.terminalFont !== undefined
-      ? options.terminalFont
-      : this.loadTerminalFont();
-    /** Cuts characters out of large fonts; see font-subset.js. */
-    this.fontSubsetter = options.fontSubsetter || new FontSubsetter();
-    /** Subsets too large for one message, by hash, until fetched. */
-    this.fontSubsets = new Map();
-    this.ws = null;
-    this.sessions = new Map();
-    this.streamIndexToId = new Map();
-    this.PtySession = options.PtySession || PtySession;
-    /** Is Herdr's server answering, and how to start it; injectable for tests. */
-    this.probeHerdr = options.probeHerdr || probeHerdrServer;
-    this.ensureHerdr = options.ensureHerdr || ensureHerdrServer;
-    this.herdrLogPath = options.herdrLogPath || path.join(stateDir(), 'herdr-server.log');
-    /** Windows whose session waits on a Herdr that is not running, by stream. */
-    this.waitingForHerdr = new Map();
-    /** Session starts between their liveness check and their PTY, by stream. */
-    this.probingStarts = new Map();
-    /** One start at a time, however many windows asked for it. */
-    this.herdrLaunch = null;
-    /**
-     * Whether a newer herdr-remote is out, asked when a window opens. The
-     * version this process runs is fixed at start; the one on disk moves when
-     * somebody updates without restarting.
-     */
-    this.checkUpdate = options.checkUpdate !== undefined
-      ? options.checkUpdate
-      : (updateChecksEnabled() ? checkForUpdate : null);
-    this.readInstalledVersion = options.readInstalledVersion || installedVersionOnDisk;
-    this.runningVersion = options.runningVersion || currentVersion();
-    this.updateCheckedAt = 0;
-    this.updateCheck = null;
-    /** The side channel that answers "does anything need me?"; see startAgentStatus. */
-    this.requestHerdr = options.requestHerdr || requestHerdr;
-    this.subscribeHerdr = options.subscribeHerdr || subscribeHerdr;
-    this.agentStatusTimer = null;
-    this.agentStatusDebounceTimer = null;
-    this.agentStatusSubscription = null;
-    this.agentStatusPending = false;
-    this.lastAgentSummary = null;
-    this.fastFailures = 0;
-    this.reconnectTimer = null;
-    this.heartbeatTimer = null;
-    this.keepaliveTimer = null;
-    this.reconnectAttempts = 0;
-    this.clientCount = 0;
-    this.legacyHeartbeat = false;
-    this.ready = false;
-    this.authFailure = false;
-    this.stopping = false;
-    this.lockPath = options.lockPath
-      || process.env.HERDR_REMOTE_HOST_LOCK
-      || path.join(stateDir(), 'host-connector.lock');
-    this.lockFd = null;
-    try { cleanPastedDir(); } catch {}
-  }
-
-  acquireLock() {
-    if (this.lockFd !== null) return;
-    ensureDir(path.dirname(this.lockPath));
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-      try {
-        const fd = fs.openSync(this.lockPath, 'wx', 0o600);
-        fs.writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostId: this.hostId, startedAt: new Date().toISOString() })}\n`);
-        this.lockFd = fd;
-        return;
-      } catch (error) {
-        if (error.code !== 'EEXIST') throw error;
-        let owner = null;
-        try { owner = JSON.parse(fs.readFileSync(this.lockPath, 'utf8')); } catch {}
-        if (owner && pidAlive(owner.pid)) {
-          const duplicate = new Error(`another host connector is already running (pid ${owner.pid})`);
-          duplicate.code = 'HOST_ALREADY_RUNNING';
-          throw duplicate;
-        }
-        try { fs.rmSync(this.lockPath, { force: true }); } catch {}
-      }
-    }
-    const stale = new Error('could not acquire host connector lock');
-    stale.code = 'HOST_LOCK_FAILED';
-    throw stale;
-  }
-
-  releaseLock() {
-    const owned = this.lockFd !== null;
-    if (this.lockFd !== null) {
-      try { fs.closeSync(this.lockFd); } catch {}
-      this.lockFd = null;
-    }
-    if (!owned) return;
-    try {
-      const owner = JSON.parse(fs.readFileSync(this.lockPath, 'utf8'));
-      if (owner.pid !== process.pid) return;
-    } catch {}
-    try { fs.rmSync(this.lockPath, { force: true }); } catch {}
-  }
-
-  start() {
-    if (!this.hostToken) {
-      throw new Error('RELAY_HOST_TOKEN is required');
-    }
-    this.acquireLock();
-    this.stopping = false;
-    this.connect();
-    // Off unless the user switched it on: Herdr is theirs to start.
-    if (this.config.herdr?.autoStart) {
-      this.startHerdr().catch((error) => {
-        process.stderr.write(`herdr-remote host connector: could not start Herdr: ${error.message}\n`);
-      });
-    }
-  }
-
-  stop() {
-    this.stopping = true;
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-    this.stopKeepalive();
-    this.stopAgentStatus();
-    this.reconnectTimer = null;
-    this.heartbeatTimer = null;
-    sendJson(this.ws, { type: 'host_shutdown' });
-    this.destroySessions();
-    closeSocket(this.ws, 'host_shutdown');
-    this.ws = null;
-    this.ready = false;
-    this.clientCount = 0;
-    this.legacyHeartbeat = false;
-    this.releaseLock();
-  }
-
-  connect() {
-    if (this.stopping || (this.ws && [WebSocket.OPEN, WebSocket.CONNECTING].includes(this.ws.readyState))) return;
-    this.stopKeepalive();
-    let ws;
-    try {
-      ws = new WebSocket(this.relayUrl);
-    } catch (error) {
-      this.scheduleReconnect(error);
-      return;
-    }
-    this.ws = ws;
-    ws.isAlive = true;
-    ws.on('open', () => {
-      // Disable Nagle's algorithm to prevent small frames from stalling ~40ms when delayed ACK is active.
-      try { ws._socket?.setNoDelay(true); } catch {}
-      ws.isAlive = true;
-      this.ready = false;
-      this.authFailure = false;
-      sendJson(ws, {
-        type: 'host_hello',
-        protocol: PROTOCOL_VERSION,
-        hostId: this.hostId,
-        token: this.hostToken,
-        password: this.relayPassword || null,
-        hostname: os.hostname(),
-        platform: process.platform,
-        arch: process.arch,
-        terminalPalette: this.terminalPalette || null,
-        terminalFont: publicTerminalFont(this.terminalFont),
-        capabilities: ['host_handoff', 'idle_heartbeat', 'binary_frame_v2'],
-      });
-      // The relay sends host_ready with the current browser count. No business
-      // heartbeat is started until that message says somebody is watching.
-    });
-    ws.on('pong', () => { ws.isAlive = true; });
-    ws.on('message', (raw, isBinary) => this.handleMessage(raw, isBinary));
-    ws.on('close', (code, rawReason) => {
-      // A replacement socket may be live while an older socket is still
-      // delivering its close event. Never let that stale event destroy the new
-      // session or clear its heartbeat timer.
-      if (this.ws !== ws) return;
-      this.ws = null;
-      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-      this.stopKeepalive();
-      // Nothing to report to, so stop asking Herdr. A reconnect brings the
-      // watcher back with the relay's next client count.
-      this.stopAgentStatus();
-      this.ready = false;
-      this.clientCount = 0;
-      this.legacyHeartbeat = false;
-      this.destroySessions();
-
-      // Another connector has claimed this workstation. Reconnecting would just
-      // displace it in turn, and each swap drops every attached browser, so
-      // stand down instead of fighting for the slot.
-      const reason = rawReason ? rawReason.toString() : '';
-      if (reason === 'host_replaced') {
-        this.stopping = true;
-        process.stderr.write('herdr-remote host connector: another instance took over this workstation; exiting\n');
-        this.stop();
-        process.exit(EXIT_REPLACED);
-      }
-      if (this.authFailure) {
-        this.stopping = true;
-        process.stderr.write('herdr-remote host connector: authentication failed; update relay credentials and restart the service\n');
-        this.releaseLock();
-        process.exit(EXIT_AUTH_FAILED);
-      }
-      this.scheduleReconnect();
-    });
-    ws.on('error', (error) => {
-      process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
-    });
-  }
-
-  scheduleReconnect(error = null) {
-    if (this.stopping || this.reconnectTimer) return;
-    if (error) process.stderr.write(`herdr-remote host connector: ${error.message}\n`);
-    const delay = Math.min(30000, 500 * (1.5 ** this.reconnectAttempts) + Math.floor(Math.random() * 250));
-    this.reconnectAttempts += 1;
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.connect();
-    }, delay);
-  }
-
-  handleMessage(raw, isBinary) {
-    if (isBinary) {
-      let frame;
-      try {
-        frame = unpackStreamFrame(raw);
-      } catch (error) {
-        process.stderr.write(`herdr-remote host connector: invalid relay frame: ${error.message}\n`);
-        return;
-      }
-      if (frame.type === 'input') {
-        const streamId = frame.version === 2 ? this.streamIndexToId.get(frame.streamIndex) : frame.streamId;
-        if (streamId) this.sessions.get(streamId)?.pty.write(frame.payload);
-      }
-      return;
-    }
-    let message;
-    try { message = JSON.parse(raw.toString('utf8')); } catch { return; }
-    // A relay-level error (no clientId) is a rejected handshake — a wrong relay
-    // password, or a host token the relay does not recognise. Without this the
-    // connection just closed silently and reconnected forever, leaving the user
-    // with an empty log and no idea what was wrong.
-    if (message.type === 'error' && !message.clientId) {
-      this.authFailure = ['relay_password_required', 'host_auth_failed', 'invalid_host_credentials'].includes(message.code);
-      process.stderr.write(`herdr-remote host connector: relay rejected the connection: ${message.message || message.code}\n`);
-      return;
-    }
-    if (message.type === 'host_ready') {
-      this.ready = true;
-      this.reconnectAttempts = 0;
-      this.startKeepalive();
-      if (Object.hasOwn(message, 'clientCount')) {
-        this.legacyHeartbeat = false;
-        this.setClientCount(message.clientCount);
-      } else {
-        // An older relay does not know client_count. Keep its historical
-        // telemetry behavior so rolling upgrades do not silently lose status.
-        this.legacyHeartbeat = true;
-        this.sendHeartbeat(true);
-        this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
-      }
-      return;
-    }
-    if (message.type === 'client_count') {
-      this.setClientCount(message.clientCount);
-      return;
-    }
-    if (message.type === 'session_start') return this.startSession(message);
-    if (message.type === 'herdr_start') return this.handleHerdrStart(message);
-    if (message.type === 'session_stop') this.stopSession(message.clientId || message.streamId);
-    else if (message.type === 'resize') this.resizeSession(message);
-    else if (message.type === 'paste_file') this.handlePasteFile(message);
-    else if (message.type === 'host_font_chunk_request') this.handleFontChunkRequest(message);
-    else if (message.type === 'host_font_subset_request') this.handleFontSubsetRequest(message);
-    else if (message.type === 'host_font_refresh') this.handleFontRefresh();
-  }
-
-  /**
-   * A service started at boot runs before anything has seen a terminal, so it
-   * starts with no font. The first `herdr-remote start` from a terminal (or
-   * from Herdr's plugin hook) writes one down; the next window to open picks
-   * it up here instead of waiting for a restart.
-   */
-  pickUpTerminalFont() {
-    if (this.terminalFont) return;
-    let next = null;
-    try {
-      next = this.loadTerminalFont();
-    } catch {
-      return;
-    }
-    if (!next) return;
-    this.terminalFont = next;
-    sendJson(this.ws, { type: 'terminal_font', terminalFont: publicTerminalFont(next) });
-  }
-
-  /** One slice of a terminal font file, for the window that asked for it. */
-  handleFontChunkRequest(message) {
-    const streamId = message.clientId || message.streamId;
-    const chunk = this.subsetChunk(message.sha256, message.index)
-      || readFontChunk(this.terminalFont, message.sha256, message.index);
-    if (!chunk) {
-      sendJson(this.ws, {
-        type: 'error',
-        clientId: streamId,
-        code: 'host_font_unavailable',
-        message: 'The terminal font changed or is no longer on this workstation',
-      });
-      return;
-    }
-    sendJson(this.ws, {
-      type: 'host_font_chunk',
-      clientId: streamId,
-      sha256: message.sha256,
-      index: message.index,
-      total: chunk.total,
-      dataBase64: chunk.data.toString('base64'),
-    });
-  }
-
-  /** A slice of a cut font still held for the browser that asked for it. */
-  subsetChunk(sha256, index) {
-    const data = this.fontSubsets.get(sha256);
-    if (!data) return null;
-    const total = Math.ceil(data.length / TERMINAL_FONT_CHUNK_BYTES);
-    if (!Number.isInteger(index) || index < 0 || index >= total) return null;
-    const start = index * TERMINAL_FONT_CHUNK_BYTES;
-    return { data: data.subarray(start, start + TERMINAL_FONT_CHUNK_BYTES), total };
-  }
-
-  /**
-   * The characters a window is about to draw, cut out of a large font (CJK).
-   * A small result travels in the answer itself; a large one (the common
-   * characters fetched up front) is held here and pulled in slices.
-   */
-  handleFontSubsetRequest(message) {
-    const streamId = message.clientId || message.streamId;
-    const source = this.terminalFont?.subsets?.find((candidate) => candidate.sha256 === message.sha256);
-    const fail = (code, text) => sendJson(this.ws, { type: 'error', clientId: streamId, code, message: text });
-    if (!source) {
-      fail('host_font_unavailable', 'The terminal font changed or is no longer on this workstation');
-      return;
-    }
-    let stat;
-    try { stat = fs.statSync(source.path); } catch {}
-    if (!stat || stat.size !== source.bytes || stat.mtimeMs !== source.mtimeMs) {
-      fail('host_font_unavailable', 'The terminal font changed or is no longer on this workstation');
-      return;
-    }
-    const codepoints = [...new Set(Array.from(String(message.text || ''), (char) => char.codePointAt(0)))];
-    let data;
-    try {
-      data = this.fontSubsetter.subset(source, codepoints);
-    } catch (error) {
-      fail('host_font_subset_failed', error.message || 'The font could not be subset');
-      return;
-    }
-    const subsetSha = crypto.createHash('sha256').update(data).digest('hex');
-    const answer = {
-      type: 'host_font_subset_ready',
-      clientId: streamId,
-      requestId: message.requestId,
-      sha256: source.sha256,
-      subsetSha,
-      bytes: data.length,
-    };
-    if (data.length <= TERMINAL_FONT_CHUNK_BYTES) {
-      answer.dataBase64 = data.toString('base64');
-    } else {
-      this.fontSubsets.delete(subsetSha);
-      this.fontSubsets.set(subsetSha, data);
-      let held = [...this.fontSubsets.values()].reduce((sum, item) => sum + item.length, 0);
-      for (const [key, item] of this.fontSubsets) {
-        if (held <= FONT_SUBSET_CACHE_BYTES || key === subsetSha) break;
-        this.fontSubsets.delete(key);
-        held -= item.length;
-      }
-    }
-    sendJson(this.ws, answer);
-  }
-
-  /**
-   * Read the terminal's font settings again, at a browser's request. Every
-   * window of this workstation hears the answer, since they all draw with it.
-   */
-  handleFontRefresh() {
-    try {
-      const next = this.loadTerminalFont({ refresh: true });
-      if (next) this.terminalFont = next;
-    } catch (error) {
-      process.stderr.write(`herdr-remote host connector: could not read the terminal font: ${error.message}\n`);
-    }
-    sendJson(this.ws, { type: 'terminal_font', terminalFont: publicTerminalFont(this.terminalFont) });
-  }
-
-  /**
-   * Confirm Herdr is really there before the name reaches `pty.spawn`.
-   *
-   * node-pty resolves the command with `execvp(3)` inside the forked child, so
-   * a missing binary is not a spawn error anyone can catch: the child writes
-   * "execvp(3) failed.: No such file or directory" into the PTY and exits. The
-   * `session_exit` that follows makes the relay drop the browser's socket, the
-   * browser reconnects into the same broken start, and that is the reconnect
-   * loop of issue #1. Refusing to start keeps the socket up and puts the actual
-   * reason in front of the user.
-   *
-   * Re-resolved per session rather than cached from the constructor: a service
-   * that started before Herdr was installed should pick it up without a restart.
-   */
-  ensureHerdrCommand() {
-    const resolved = verifyHerdrCommand(this.herdrCommand, this.herdrLookup);
-    if (resolved.found) {
-      this.herdrCommand = resolved.command;
-      this.warnIfHerdrOutdated();
-      return null;
-    }
-    return herdrNotFoundMessage(this.herdrLookup);
-  }
-
-  /**
-   * Say once that the installed Herdr is older than this release expects.
-   *
-   * Never a refusal to start. An older Herdr still runs — it just misbehaves in
-   * ways a browser window notices — and the comment on `startSession` explains
-   * what a refused start does to a reconnecting browser.
-   */
-  warnIfHerdrOutdated() {
-    if (this.herdrVersionWarned) return;
-    const installed = this.readHerdrVersion({ command: this.herdrCommand });
-    if (installed.supported) {
-      // A version we could not read is checked again on the next session: the
-      // install may simply not have been finished writing.
-      if (installed.version) this.herdrVersionWarned = true;
-      return;
-    }
-    this.herdrVersionWarned = true;
-    process.stderr.write(`herdr-remote host connector: ${herdrOutdatedMessage(installed.version)}\n`);
-  }
-
-  startSession(message) {
-    const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
-    if (!streamId) return undefined;
-    this.stopSession(streamId);
-    // A window opening is when a person is looking; that is when to ask.
-    this.reportUpdateStatus();
-    this.pickUpTerminalFont();
-    const missingHerdr = this.ensureHerdrCommand();
-    if (missingHerdr) {
-      process.stderr.write(`herdr-remote host connector: ${missingHerdr}\n`);
-      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_not_found', message: missingHerdr });
-      return undefined;
-    }
-    const socketInfo = inspectSocket(this.socketPath);
-    if (!socketInfo.ok && !socketInfo.missing) {
-      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_socket_unavailable', message: socketInfo.reason });
-      return undefined;
-    }
-    if (!socketInfo.ok) {
-      this.waitForHerdr(streamId, message);
-      return undefined;
-    }
-    // The socket file alone proves nothing: a `herdr` client pointed at a dead
-    // one starts a server of its own, inside this process's service, where the
-    // next restart of herdr-remote would kill it. Only a server that accepts a
-    // connection gets a client.
-    const pending = { message };
-    this.probingStarts.set(streamId, pending);
-    return this.probeHerdr(this.socketPath).then((probe) => {
-      // Stopped, or started again, while the answer was in flight.
-      if (this.probingStarts.get(streamId) !== pending) return;
-      this.probingStarts.delete(streamId);
-      if (probe.state === 'running') this.spawnSession(pending.message);
-      else if (probe.state === 'stopped') this.waitForHerdr(streamId, pending.message);
-      else sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_socket_unavailable', message: probe.reason });
-    });
-  }
-
-  /**
-   * Tell every window whether this workstation's herdr-remote is behind the
-   * newest release. Asked at most once a minute however many windows open;
-   * the relay keeps the last answer for windows that open in between. A failed
-   * check says nothing: offline is not news.
-   */
-  reportUpdateStatus({ now = Date.now() } = {}) {
-    if (!this.checkUpdate || this.updateCheck) return this.updateCheck;
-    if (now - this.updateCheckedAt < UPDATE_RECHECK_MS) return null;
-    this.updateCheckedAt = now;
-    this.updateCheck = Promise.resolve()
-      .then(() => this.checkUpdate())
-      .then((result) => {
-        if (!result?.ok || !result.latest) return;
-        const running = this.runningVersion;
-        const installed = this.readInstalledVersion() || running;
-        sendJson(this.ws, {
-          type: 'update_status',
-          current: running,
-          installed,
-          latest: result.latest,
-          updateAvailable: compareVersions(result.latest, running) > 0,
-          // Updated on disk, still running the old code: a restart finishes it.
-          restartPending: compareVersions(installed, running) > 0,
-        });
-      })
-      .catch(() => {})
-      .finally(() => { this.updateCheck = null; });
-    return this.updateCheck;
-  }
-
-  /**
-   * Hold a window's session until Herdr runs, and ask the browser whether it
-   * should be started. Nothing starts until somebody says yes.
-   */
-  waitForHerdr(streamId, message) {
-    this.waitingForHerdr.set(streamId, message);
-    sendJson(this.ws, {
-      type: 'error',
-      clientId: streamId,
-      code: 'herdr_not_running',
-      message: `Herdr is not running on this workstation (${this.socketPath}).`,
-    });
-  }
-
-  /**
-   * Start this workstation's Herdr server, once, however many windows or
-   * callers ask at the same time.
-   */
-  startHerdr() {
-    if (!this.herdrLaunch) {
-      this.herdrLaunch = Promise.resolve()
-        .then(() => {
-          const missing = this.ensureHerdrCommand();
-          if (missing) throw new Error(missing);
-          return this.ensureHerdr({
-            command: this.herdrCommand,
-            args: this.herdrArgs,
-            socketPath: this.socketPath,
-            cwd: this.cwd,
-            logPath: this.herdrLogPath,
-          });
-        })
-        .finally(() => { this.herdrLaunch = null; });
-    }
-    return this.herdrLaunch;
-  }
-
-  /**
-   * A browser said yes. The relay only ever routes this from a window paired
-   * to *this* workstation, so what starts is this user's own Herdr, at the
-   * socket this connector is configured for — never one named by the message.
-   * Once it runs, every window waiting on it gets its session.
-   */
-  async handleHerdrStart(message) {
-    const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
-    try {
-      const result = await this.startHerdr();
-      if (result.started) process.stderr.write('herdr-remote host connector: started Herdr at a browser\'s request\n');
-    } catch (error) {
-      process.stderr.write(`herdr-remote host connector: could not start Herdr: ${error.message}\n`);
-      if (streamId) {
-        sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_start_failed', message: error.message });
-      }
-      return;
-    }
-    const waiting = [...this.waitingForHerdr.values()];
-    this.waitingForHerdr.clear();
-    for (const held of waiting) this.spawnSession(held);
-  }
-
-  /** Start the PTY for a window once Herdr is known to be running. */
-  spawnSession(message) {
-    const streamId = typeof message.streamId === 'string' ? message.streamId : message.clientId;
-    const streamIndex = typeof message.streamIndex === 'number' ? message.streamIndex : null;
-    const pty = new this.PtySession({
-      command: this.herdrCommand,
-      args: this.herdrArgs,
-      cwd: this.cwd,
-      socketPath: this.socketPath,
-    });
-    const session = {
-      id: streamId,
-      streamIndex,
-      pty,
-      cols: Number(message.cols) || PtySession.DEFAULT_COLS,
-      rows: Number(message.rows) || PtySession.DEFAULT_ROWS,
-      createdAt: new Date().toISOString(),
-      startedAtMs: Date.now(),
-      clientId: streamId,
-      pendingOutput: [],
-      flushImmediate: null,
-    };
-    const flushOutput = () => {
-      if (session.flushImmediate) {
-        clearImmediate(session.flushImmediate);
-        session.flushImmediate = null;
-      }
-      if (session.pendingOutput.length === 0) return;
-      const chunks = session.pendingOutput;
-      session.pendingOutput = [];
-      if (this.ws?.readyState === WebSocket.OPEN) {
-        const payload = Buffer.concat(chunks);
-        const frame = typeof session.streamIndex === 'number'
-          ? packStreamFrameV2(FRAME_TYPE_OUTPUT, session.streamIndex, payload)
-          : packStreamFrame('output', streamId, payload);
-        this.ws.send(frame);
-      }
-    };
-    try {
-      pty.start({
-        cols: session.cols,
-        rows: session.rows,
-        onData: (data) => {
-          const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
-          if (chunk.length === 0) return;
-          session.pendingOutput.push(chunk);
-          if (!session.flushImmediate) {
-            // Coalesce burst output from the same tick into a single frame to reduce
-            // packet overhead without introducing timer latency.
-            session.flushImmediate = setImmediate(flushOutput);
-          }
-        },
-        onExit: ({ exitCode }) => {
-          if (this.sessions.get(streamId) !== session) return;
-          this.sessions.delete(streamId);
-          if (typeof session.streamIndex === 'number') {
-            this.streamIndexToId.delete(session.streamIndex);
-          }
-          if (session.flushImmediate) {
-            clearImmediate(session.flushImmediate);
-            session.flushImmediate = null;
-          }
-          session.pendingOutput = [];
-          this.reportSessionExit(session, exitCode);
-          this.sendHeartbeat();
-        },
-      });
-    } catch (error) {
-      if (session.flushImmediate) {
-        clearImmediate(session.flushImmediate);
-        session.flushImmediate = null;
-      }
-      session.pendingOutput = [];
-      sendJson(this.ws, { type: 'error', clientId: streamId, code: 'pty_start_failed', message: error.message });
-      pty.kill();
-      return;
-    }
-    this.sessions.set(streamId, session);
-    if (typeof streamIndex === 'number') {
-      this.streamIndexToId.set(streamIndex, streamId);
-    }
-    sendJson(this.ws, { type: 'session_ready', clientId: streamId });
-    this.sendHeartbeat();
-  }
-
-  /**
-   * Tell the relay how a session ended.
-   *
-   * `session_exit` is the honest answer for a session that ran, and the relay
-   * closes the browser's socket on it so the window can start a fresh one. That
-   * is also what turns a start that keeps failing into a reconnect loop: exit,
-   * close, reconnect, exit. Once a few starts in a row have died immediately
-   * with a non-zero code the failure is systemic, not a session ending, so it is
-   * reported as an error — which the relay forwards without dropping the socket,
-   * leaving the user with a message instead of a spinner.
-   */
-  reportSessionExit(session, exitCode) {
-    const streamId = session.id;
-    const lifetimeMs = Date.now() - session.startedAtMs;
-    const failedFast = exitCode !== 0 && lifetimeMs < HostConnector.FAST_FAILURE_MS;
-    this.fastFailures = failedFast ? this.fastFailures + 1 : 0;
-    if (this.fastFailures < HostConnector.FAST_FAILURE_LIMIT) {
-      sendJson(this.ws, { type: 'session_exit', clientId: streamId, code: exitCode });
-      return;
-    }
-    const message = `"${this.herdrCommand}" exited immediately with code ${exitCode} on ${this.fastFailures} attempts in a row. `
-      + 'Check that it runs from a terminal, and see the host connector log for what it printed.';
-    process.stderr.write(`herdr-remote host connector: ${message}\n`);
-    sendJson(this.ws, { type: 'error', clientId: streamId, code: 'herdr_start_failed', message });
-  }
-
-  stopSession(streamId) {
-    this.waitingForHerdr.delete(streamId);
-    this.probingStarts.delete(streamId);
-    const session = this.sessions.get(streamId);
-    if (!session) return;
-    this.sessions.delete(streamId);
-    if (typeof session.streamIndex === 'number') {
-      this.streamIndexToId.delete(session.streamIndex);
-    }
-    if (session.flushImmediate) {
-      clearImmediate(session.flushImmediate);
-      session.flushImmediate = null;
-    }
-    session.pendingOutput = [];
-    session.pty.kill();
-    this.sendHeartbeat();
-  }
-
-  startKeepalive() {
-    this.stopKeepalive();
-    if (!this.ws || this.stopping) return;
-    this.ws.isAlive = true;
-    const interval = this.config?.cleanup?.heartbeatIntervalMs || 30_000;
-    this.keepaliveTimer = setInterval(() => this.tickKeepalive(), interval);
-  }
-
-  stopKeepalive() {
-    if (this.keepaliveTimer) {
-      clearInterval(this.keepaliveTimer);
-      this.keepaliveTimer = null;
-    }
-  }
-
-  tickKeepalive() {
-    const ws = this.ws;
-    if (!ws || this.stopping) return;
-    if (ws.readyState === WebSocket.CLOSING) {
-      terminateSocket(ws);
-      return;
-    }
-    if (ws.readyState !== WebSocket.OPEN) return;
-
-    if (!ws.isAlive) {
-      terminateSocket(ws);
-      return;
-    }
-
-    ws.isAlive = false;
-    try {
-      if (typeof ws.ping === 'function') ws.ping();
-    } catch {}
-
-    if (this.clientCount <= 0 && !this.legacyHeartbeat) {
-      sendJson(ws, {
-        type: 'heartbeat',
-        load: {},
-        ptys: [],
-      });
-    }
-  }
-
-  setClientCount(value) {
-    const next = Number.isInteger(value) ? Math.max(0, value) : 0;
-    if (next === this.clientCount && (next === 0 || this.heartbeatTimer)) return;
-    const wasActive = this.clientCount > 0;
-    this.clientCount = next;
-    if (next > 0) {
-      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-      this.sendHeartbeat(true);
-      this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
-    } else {
-      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-      if (wasActive) this.sendHeartbeat(true);
-    }
-    // Nobody watching, nothing to ask Herdr about itself.
-    if (next > 0) this.startAgentStatus();
-    else this.stopAgentStatus();
-  }
-
-  /**
-   * Watch what the agents on this workstation are doing.
-   *
-   * A side channel, on its own socket, alive only while a browser is attached.
-   * Herdr's server can be restarted underneath a running herdr-remote — the
-   * PTYs survive it — so every failure here is a retry, never anything a
-   * terminal session notices.
-   *
-   * A long-lived subscription provides fast refreshes on pane and workspace
-   * focus changes; the five-second poll still repairs missed events and a
-   * restarted Herdr server. Both paths only read the side-channel snapshot.
-   */
-  startAgentStatus() {
-    if (this.agentStatusTimer || this.stopping) return;
-    this.agentStatusTimer = setInterval(() => this.readAgentStatus(), AGENT_STATUS_POLL_MS);
-    if (typeof this.agentStatusTimer.unref === 'function') this.agentStatusTimer.unref();
-    try {
-      this.agentStatusSubscription = this.subscribeHerdr(
-        this.socketPath,
-        AGENT_STATUS_SUBSCRIPTIONS,
-        () => this.scheduleAgentStatusRead(),
-      );
-    } catch {
-      // A missing or restarting Herdr server leaves the regular poll in place.
-    }
-    this.readAgentStatus();
-  }
-
-  scheduleAgentStatusRead() {
-    if (!this.agentStatusTimer) return;
-    if (this.agentStatusDebounceTimer) clearTimeout(this.agentStatusDebounceTimer);
-    this.agentStatusDebounceTimer = setTimeout(() => {
-      this.agentStatusDebounceTimer = null;
-      this.readAgentStatus();
-    }, AGENT_STATUS_EVENT_DEBOUNCE_MS);
-    if (typeof this.agentStatusDebounceTimer.unref === 'function') this.agentStatusDebounceTimer.unref();
-  }
-
-  stopAgentStatus() {
-    if (this.agentStatusTimer) {
-      clearInterval(this.agentStatusTimer);
-      this.agentStatusTimer = null;
-    }
-    if (this.agentStatusDebounceTimer) {
-      clearTimeout(this.agentStatusDebounceTimer);
-      this.agentStatusDebounceTimer = null;
-    }
-    if (this.agentStatusSubscription) {
-      this.agentStatusSubscription.close();
-      this.agentStatusSubscription = null;
-    }
-    this.lastAgentSummary = null;
-  }
-
-  /**
-   * Read the summary and forward it if it changed.
-   *
-   * A slow answer must not stack up behind the next tick, and a failed one
-   * leaves the last summary standing rather than blanking the browser's chip:
-   * Herdr's server not running is an ordinary state, not news.
-   */
-  async readAgentStatus() {
-    if (this.agentStatusPending || !this.agentStatusTimer) return;
-    this.agentStatusPending = true;
-    let snapshot;
-    try {
-      const result = await this.requestHerdr(this.socketPath, 'session.snapshot', {});
-      snapshot = result?.snapshot || result;
-    } catch {
-      return;
-    } finally {
-      this.agentStatusPending = false;
-    }
-    // Stopped while the answer was in flight; the browser it was for is gone.
-    if (!this.agentStatusTimer) return;
-    const summary = summarizeAgents(snapshot);
-    if (sameSummary(this.lastAgentSummary, summary)) return;
-    this.lastAgentSummary = summary;
-    sendJson(this.ws, { type: 'agent_status', ...summary });
-  }
-
-  resizeSession(message) {
-    const id = message.clientId || message.streamId;
-    // A window still waiting on Herdr starts at the size it has by then.
-    const held = this.waitingForHerdr.get(id) || this.probingStarts.get(id)?.message;
-    if (held) {
-      if (Number.isInteger(message.cols)) held.cols = message.cols;
-      if (Number.isInteger(message.rows)) held.rows = message.rows;
-    }
-    const session = this.sessions.get(id);
-    if (!session) return;
-    session.cols = Number.isInteger(message.cols) ? Math.min(500, Math.max(2, message.cols)) : session.cols;
-    session.rows = Number.isInteger(message.rows) ? Math.min(500, Math.max(2, message.rows)) : session.rows;
-    session.pty.resize(session.cols, session.rows);
-  }
-
-  handlePasteFile(message) {
-    const streamId = message.clientId || message.streamId;
-    try {
-      const savedPath = savePastedFile({
-        mime: message.mime,
-        dataBase64: message.dataBase64,
-      });
-      sendJson(this.ws, {
-        type: 'paste_file_ready',
-        clientId: streamId,
-        path: savedPath,
-      });
-    } catch (error) {
-      sendJson(this.ws, {
-        type: 'error',
-        clientId: streamId,
-        code: 'paste_file_write_failed',
-        message: error.message || 'Failed to save pasted file',
-      });
-    }
-  }
-
-  destroySessions() {
-    for (const session of this.sessions.values()) {
-      if (session.flushImmediate) {
-        clearImmediate(session.flushImmediate);
-        session.flushImmediate = null;
-      }
-      session.pendingOutput = [];
-      session.pty.kill();
-    }
-    this.sessions.clear();
-    this.streamIndexToId.clear();
-    this.waitingForHerdr.clear();
-    this.probingStarts.clear();
-  }
-
-  sendHeartbeat(force = false) {
-    if (!force && this.clientCount <= 0 && !this.legacyHeartbeat) return;
-    const memory = process.memoryUsage();
-    const load = os.loadavg();
-    sendJson(this.ws, {
-      type: 'heartbeat',
-      load: {
-        load1m: load[0] || 0,
-        load5m: load[1] || 0,
-        load15m: load[2] || 0,
-        rssBytes: memory.rss,
-        heapUsedBytes: memory.heapUsed,
-      },
-      ptys: [...this.sessions.values()].map((session) => ({
-        id: session.id,
-        pid: session.pty.terminal?.pid || null,
-        command: session.pty.command,
-        cols: session.cols,
-        rows: session.rows,
-        cwd: session.pty.cwd,
-        createdAt: session.createdAt,
-        activeClients: 1,
-      })),
-    });
-  }
-}
-
-if (require.main === module) {
-  const connector = new HostConnector();
-  try {
-    connector.start();
-  } catch (error) {
-    process.stderr.write(`herdr-remote host connector failed: ${error.message}\n`);
-    process.exitCode = error.code === 'HOST_ALREADY_RUNNING' ? EXIT_REPLACED : 1;
-  }
-  const stop = () => { connector.stop(); process.exit(0); };
-  process.once('SIGINT', stop);
-  process.once('SIGTERM', stop);
-}
-
-module.exports = { HostConnector, PROTOCOL_VERSION };