herdr-remote 0.2.4 → 0.2.6

package/config.example.json

@@ -7,7 +7,11 @@
     "port": 8787,
     "lanHost": "",
     "publicUrl": "",
-    "remoteUrl": ""
+    "remoteUrl": "",
+    "maxHosts": 1024,
+    "maxPendingHandshakes": 1024,
+    "maxBufferedBytesPerClient": 4194304,
+    "hostReconnectGraceMs": 30000
   },
   "herdr": {
     "socketPath": null,

package/dist/tui.mjs

@@ -78,6 +78,10 @@ var require_config = __commonJS({
         remoteUrl: "",
         maxPayloadBytes: 1024 * 1024,
         maxClientsPerHost: 16,
+        maxHosts: 1024,
+        maxPendingHandshakes: 1024,
+        maxBufferedBytesPerClient: 4 * 1024 * 1024,
+        hostReconnectGraceMs: 30 * 1e3,
         allowedOrigins: []
       },
       herdr: {
@@ -203,6 +207,20 @@ var require_config = __commonJS({
       config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 1, 65535);
       config.relay.maxPayloadBytes = parseInteger(config.relay.maxPayloadBytes, DEFAULTS.relay.maxPayloadBytes, 4096, 16 * 1024 * 1024);
       config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+      config.relay.maxHosts = parseInteger(config.relay.maxHosts, DEFAULTS.relay.maxHosts, 1, 1e5);
+      config.relay.maxPendingHandshakes = parseInteger(config.relay.maxPendingHandshakes, DEFAULTS.relay.maxPendingHandshakes, 16, 1e5);
+      config.relay.maxBufferedBytesPerClient = parseInteger(
+        config.relay.maxBufferedBytesPerClient,
+        DEFAULTS.relay.maxBufferedBytesPerClient,
+        64 * 1024,
+        256 * 1024 * 1024
+      );
+      config.relay.hostReconnectGraceMs = parseInteger(
+        config.relay.hostReconnectGraceMs,
+        DEFAULTS.relay.hostReconnectGraceMs,
+        1e3,
+        24 * 60 * 60 * 1e3
+      );
       config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1e3, 24 * 60 * 60 * 1e3);
       config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1e3, 365 * 24 * 60 * 60 * 1e3);
       config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 1e4);
@@ -220,6 +238,10 @@ var require_config = __commonJS({
       if (!Array.isArray(config.herdr.args) || !config.herdr.args.every((arg) => typeof arg === "string")) {
         config.herdr.args = [];
       }
+      if (config.herdr.args.includes("--no-session")) {
+        config.herdr.args = config.herdr.args.filter((arg) => arg !== "--no-session");
+        process.stderr.write("herdr-remote: ignoring removed --no-session argument (removed in Herdr 0.9.0)\n");
+      }
       if (typeof config.herdr.socketPath !== "string" || config.herdr.socketPath.length === 0) {
         config.herdr.socketPath = null;
       }
@@ -238,6 +260,10 @@ var require_config = __commonJS({
       if (env.RELAY_PORT) config.relay.port = env.RELAY_PORT;
       if (env.RELAY_PUBLIC_URL) config.relay.publicUrl = env.RELAY_PUBLIC_URL;
       if (env.RELAY_REMOTE_URL) config.relay.remoteUrl = env.RELAY_REMOTE_URL;
+      if (env.RELAY_MAX_HOSTS) config.relay.maxHosts = env.RELAY_MAX_HOSTS;
+      if (env.RELAY_MAX_PENDING_HANDSHAKES) config.relay.maxPendingHandshakes = env.RELAY_MAX_PENDING_HANDSHAKES;
+      if (env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT) config.relay.maxBufferedBytesPerClient = env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT;
+      if (env.RELAY_HOST_RECONNECT_GRACE_MS) config.relay.hostReconnectGraceMs = env.RELAY_HOST_RECONNECT_GRACE_MS;
       if (env.HERDR_SOCKET_PATH) config.herdr.socketPath = env.HERDR_SOCKET_PATH;
       if (env.HERDR_CWD) config.herdr.cwd = env.HERDR_CWD;
       if (env.HERDR_ARGS_JSON) {
@@ -547,6 +573,7 @@ var require_en = __commonJS({
       "error.invalidKeepalive": "Unknown keep-alive manager.",
       "error.unknownField": "Unknown setting.",
       "error.remoteUrlRequired": "Relay URL is required for self-hosted relay mode.",
+      "error.removedHerdrArg": "Herdr 0.9.0 removed --no-session; remove it from the extra arguments.",
       "error.saveFailed": "Could not save configuration: {message}",
       "hint.navigate": "\u2191\u2193 move",
       "hint.select": "\u21B5 select",
@@ -771,6 +798,7 @@ var require_zh = __commonJS({
       "error.invalidKeepalive": "\u672A\u77E5\u7684\u4FDD\u6D3B\u7BA1\u7406\u65B9\u5F0F\u3002",
       "error.unknownField": "\u672A\u77E5\u7684\u8BBE\u7F6E\u9879\u3002",
       "error.remoteUrlRequired": "\u81EA\u5EFA Relay \u6A21\u5F0F\u987B\u586B\u5199 Relay \u5730\u5740\u3002",
+      "error.removedHerdrArg": "Herdr 0.9.0 \u5DF2\u79FB\u9664 --no-session\uFF0C\u8BF7\u4ECE\u9644\u52A0\u53C2\u6570\u4E2D\u79FB\u9664\u3002",
       "error.saveFailed": "\u4FDD\u5B58\u914D\u7F6E\u5931\u8D25\uFF1A{message}",
       "hint.navigate": "\u2191\u2193 \u79FB\u52A8",
       "hint.select": "\u21B5 \u9009\u62E9",
@@ -1104,7 +1132,11 @@ var require_settings_model = __commonJS({
           break;
         }
         case "herdrArgs": {
-          next.herdr.args = value ? value.split(/\s+/).filter(Boolean) : [];
+          const args = value ? value.split(/\s+/).filter(Boolean) : [];
+          if (args.includes("--no-session")) {
+            return { draft, errorKey: "error.removedHerdrArg" };
+          }
+          next.herdr.args = args;
           break;
         }
         case "language": {
@@ -1550,7 +1582,11 @@ var require_service = __commonJS({
             RELAY_PASSWORD: state.hostToken,
             RELAY_AUTH_STATE_FILE: relayAuthStatePath(),
             RELAY_ALLOWED_ORIGINS: (config.relay.allowedOrigins || []).join(","),
-            RELAY_MAX_CLIENTS_PER_HOST: String(config.relay.maxClientsPerHost)
+            RELAY_MAX_CLIENTS_PER_HOST: String(config.relay.maxClientsPerHost),
+            RELAY_MAX_HOSTS: String(config.relay.maxHosts),
+            RELAY_MAX_PENDING_HANDSHAKES: String(config.relay.maxPendingHandshakes),
+            RELAY_MAX_BUFFERED_BYTES_PER_CLIENT: String(config.relay.maxBufferedBytesPerClient),
+            RELAY_HOST_RECONNECT_GRACE_MS: String(config.relay.hostReconnectGraceMs)
           }
         });
       }
@@ -1733,18 +1769,26 @@ var require_service = __commonJS({
       throw lastError || new Error("relay did not become ready");
     }
     async function waitForHost(config, { attempts = 30, delayMs = 100 } = {}) {
-      let lastHealth = null;
+      const state = ensureRuntime2();
+      const statusEndpoint = `${resolveAdminOrigin2(config)}/api/status`;
+      let lastStatus = null;
       for (let attempt = 0; attempt < attempts; attempt += 1) {
         try {
-          lastHealth = await requestJson2(healthUrl(config), { timeout: 800 });
-          if (lastHealth.hosts > 0) return lastHealth;
+          lastStatus = await requestJson2(statusEndpoint, {
+            timeout: 800,
+            headers: {
+              "X-Herdr-Host-Id": state.hostId,
+              "X-Herdr-Host-Token": state.hostToken
+            }
+          });
+          if (lastStatus.hosts?.some((host) => host.id === state.hostId)) return lastStatus;
         } catch (error2) {
-          lastHealth = { ok: false, message: error2.message };
+          lastStatus = { ok: false, message: error2.message };
         }
         await new Promise((resolve) => setTimeout(resolve, delayMs));
       }
-      const error = new Error(lastHealth?.message || "the Herdr host connector did not register with the relay");
-      error.health = lastHealth;
+      const error = new Error(lastStatus?.message || "the Herdr host connector did not register with the relay");
+      error.health = lastStatus;
       throw error;
     }
     async function statusServices() {
@@ -2827,12 +2871,26 @@ function relayStartCommand(config, password) {
   return parts.join(" ");
 }
 async function probeRelay(config) {
+  const origin = (0, import_config.resolveAdminOrigin)(config);
+  let health;
   try {
-    const health = await (0, import_service.requestJson)(`${(0, import_config.resolveAdminOrigin)(config)}/healthz`, { timeout: 4e3 });
-    return { ok: true, version: health.version, hosts: health.hosts };
+    health = await (0, import_service.requestJson)(`${origin}/healthz`, { timeout: 4e3 });
   } catch (error) {
     return { ok: false, message: error.message };
   }
+  try {
+    const runtime = (0, import_service.ensureRuntime)();
+    const status = await (0, import_service.requestJson)(`${origin}/api/status`, {
+      timeout: 4e3,
+      headers: {
+        "X-Herdr-Host-Id": runtime.hostId,
+        "X-Herdr-Host-Token": runtime.hostToken
+      }
+    });
+    return { ok: true, version: String(health.version || status.version || ""), hosts: Array.isArray(status.hosts) ? status.hosts.length : 0 };
+  } catch {
+    return { ok: true, version: String(health.version || ""), hosts: void 0 };
+  }
 }
 function formatUptime(seconds, t) {
   if (!Number.isFinite(seconds)) return t("common.unknown");
@@ -3831,7 +3889,7 @@ function About({ ctx }) {
         children: updateLabel
       }
     ) }),
-    /* @__PURE__ */ jsx10(Row, { label: t("about.version"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: "0.2.4" }) }),
+    /* @__PURE__ */ jsx10(Row, { label: t("about.version"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: "0.2.6" }) }),
     /* @__PURE__ */ jsx10(Row, { label: t("about.configPath"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: (0, import_config.configPath)() }) }),
     /* @__PURE__ */ jsx10(Row, { label: t("about.statePath"), children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: (0, import_config.stateDir)() }) }),
     /* @__PURE__ */ jsx10(Box9, { marginTop: 1, children: /* @__PURE__ */ jsx10(Text9, { color: theme.muted, children: t("about.docs") }) }),

package/herdr-plugin.toml

@@ -1,7 +1,7 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.3"
-min_herdr_version = "0.8.2"
+version = "0.2.6"
+min_herdr_version = "0.9.0"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos"]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "repository": {

package/src/config.js

@@ -64,6 +64,10 @@ const DEFAULTS = {
     remoteUrl: '',
     maxPayloadBytes: 1024 * 1024,
     maxClientsPerHost: 16,
+    maxHosts: 1024,
+    maxPendingHandshakes: 1024,
+    maxBufferedBytesPerClient: 4 * 1024 * 1024,
+    hostReconnectGraceMs: 30 * 1000,
     allowedOrigins: [],
   },
   herdr: {
@@ -230,6 +234,20 @@ function validate(config) {
   config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 1, 65535);
   config.relay.maxPayloadBytes = parseInteger(config.relay.maxPayloadBytes, DEFAULTS.relay.maxPayloadBytes, 4096, 16 * 1024 * 1024);
   config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+  config.relay.maxHosts = parseInteger(config.relay.maxHosts, DEFAULTS.relay.maxHosts, 1, 100000);
+  config.relay.maxPendingHandshakes = parseInteger(config.relay.maxPendingHandshakes, DEFAULTS.relay.maxPendingHandshakes, 16, 100000);
+  config.relay.maxBufferedBytesPerClient = parseInteger(
+    config.relay.maxBufferedBytesPerClient,
+    DEFAULTS.relay.maxBufferedBytesPerClient,
+    64 * 1024,
+    256 * 1024 * 1024,
+  );
+  config.relay.hostReconnectGraceMs = parseInteger(
+    config.relay.hostReconnectGraceMs,
+    DEFAULTS.relay.hostReconnectGraceMs,
+    1000,
+    24 * 60 * 60 * 1000,
+  );
   config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1000, 24 * 60 * 60 * 1000);
   config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1000, 365 * 24 * 60 * 60 * 1000);
   config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 10000);
@@ -255,6 +273,12 @@ function validate(config) {
   if (!Array.isArray(config.herdr.args) || !config.herdr.args.every((arg) => typeof arg === 'string')) {
     config.herdr.args = [];
   }
+  // Herdr 0.9.0 removed --no-session; retaining it in saved configs causes
+  // session creation to fail. Filter it out if present.
+  if (config.herdr.args.includes('--no-session')) {
+    config.herdr.args = config.herdr.args.filter((arg) => arg !== '--no-session');
+    process.stderr.write('herdr-remote: ignoring removed --no-session argument (removed in Herdr 0.9.0)\n');
+  }
   if (typeof config.herdr.socketPath !== 'string' || config.herdr.socketPath.length === 0) {
     config.herdr.socketPath = null;
   }
@@ -277,6 +301,10 @@ function applyEnvironment(config) {
   if (env.RELAY_PORT) config.relay.port = env.RELAY_PORT;
   if (env.RELAY_PUBLIC_URL) config.relay.publicUrl = env.RELAY_PUBLIC_URL;
   if (env.RELAY_REMOTE_URL) config.relay.remoteUrl = env.RELAY_REMOTE_URL;
+  if (env.RELAY_MAX_HOSTS) config.relay.maxHosts = env.RELAY_MAX_HOSTS;
+  if (env.RELAY_MAX_PENDING_HANDSHAKES) config.relay.maxPendingHandshakes = env.RELAY_MAX_PENDING_HANDSHAKES;
+  if (env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT) config.relay.maxBufferedBytesPerClient = env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT;
+  if (env.RELAY_HOST_RECONNECT_GRACE_MS) config.relay.hostReconnectGraceMs = env.RELAY_HOST_RECONNECT_GRACE_MS;
   if (env.HERDR_SOCKET_PATH) config.herdr.socketPath = env.HERDR_SOCKET_PATH;
   if (env.HERDR_CWD) config.herdr.cwd = env.HERDR_CWD;
   if (env.HERDR_ARGS_JSON) {

package/src/exit-codes.js

@@ -10,5 +10,7 @@
  * one exit the supervisor must respect rather than recover from.
  */
 const EXIT_REPLACED = 12;
+/** Credentials need operator intervention; a supervisor must not loop. */
+const EXIT_AUTH_FAILED = 13;
 
-module.exports = { EXIT_REPLACED };
+module.exports = { EXIT_REPLACED, EXIT_AUTH_FAILED };

package/src/host-connector.js

@@ -1,9 +1,12 @@
 '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 } = require('./config');
+const { loadConfig, hostWebSocketUrl, resolveHostRelayUrl, stateDir } = require('./config');
+const { ensureDir } = require('./state');
 const { resolveSocketPath, inspectSocket } = require('./socket-discovery');
 const { PtySession } = require('./pty-session');
 const { resolveHerdrCommand } = require('./herdr-command');
@@ -11,7 +14,7 @@ const { resolveHerdrCommand } = require('./herdr-command');
 // generated from one definition.
 const { packStreamFrame, unpackStreamFrame, PROTOCOL_VERSION } = require('herdr-remote-relay/protocol');
 const { resolveHostPalette } = require('./terminal-palette');
-const { EXIT_REPLACED } = require('./exit-codes');
+const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
 
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
@@ -21,9 +24,19 @@ function sendJson(ws, payload) {
   if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(payload));
 }
 
-function closeSocket(ws) {
+function closeSocket(ws, reason = 'host connector stopping') {
   if (!ws || ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) return;
-  try { ws.close(1000, 'host connector stopping'); } catch {}
+  try { ws.close(1000, reason); } 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 {
@@ -55,13 +68,62 @@ class HostConnector {
     this.reconnectTimer = null;
     this.heartbeatTimer = 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;
+  }
+
+  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();
   }
@@ -72,9 +134,14 @@ class HostConnector {
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     this.reconnectTimer = null;
     this.heartbeatTimer = null;
+    sendJson(this.ws, { type: 'host_shutdown' });
     this.destroySessions();
-    closeSocket(this.ws);
+    closeSocket(this.ws, 'host_shutdown');
     this.ws = null;
+    this.ready = false;
+    this.clientCount = 0;
+    this.legacyHeartbeat = false;
+    this.releaseLock();
   }
 
   connect() {
@@ -89,8 +156,9 @@ class HostConnector {
     this.ws = ws;
     ws.isAlive = true;
     ws.on('open', () => {
-      this.reconnectAttempts = 0;
       ws.isAlive = true;
+      this.ready = false;
+      this.authFailure = false;
       sendJson(ws, {
         type: 'host_hello',
         protocol: PROTOCOL_VERSION,
@@ -101,16 +169,24 @@ class HostConnector {
         platform: process.platform,
         arch: process.arch,
         terminalPalette: this.terminalPalette || null,
+        capabilities: ['host_handoff', 'idle_heartbeat'],
       });
-      this.sendHeartbeat();
-      this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.cleanup.heartbeatIntervalMs);
+      // 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) => {
-      if (this.ws === ws) this.ws = null;
+      // 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.ready = false;
+      this.clientCount = 0;
+      this.legacyHeartbeat = false;
       this.destroySessions();
 
       // Another connector has claimed this workstation. Reconnecting would just
@@ -123,6 +199,12 @@ class HostConnector {
         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) => {
@@ -160,9 +242,29 @@ class HostConnector {
     // 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;
+      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') this.startSession(message);
     else if (message.type === 'session_stop') this.stopSession(message.clientId || message.streamId);
     else if (message.type === 'resize') this.resizeSession(message);
@@ -224,6 +326,22 @@ class HostConnector {
     this.sendHeartbeat();
   }
 
+  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);
+    }
+  }
+
   resizeSession(message) {
     const id = message.clientId || message.streamId;
     const session = this.sessions.get(id);
@@ -238,7 +356,8 @@ class HostConnector {
     this.sessions.clear();
   }
 
-  sendHeartbeat() {
+  sendHeartbeat(force = false) {
+    if (!force && this.clientCount <= 0 && !this.legacyHeartbeat) return;
     const memory = process.memoryUsage();
     const load = os.loadavg();
     sendJson(this.ws, {
@@ -270,7 +389,7 @@ if (require.main === module) {
     connector.start();
   } catch (error) {
     process.stderr.write(`herdr-remote host connector failed: ${error.message}\n`);
-    process.exitCode = 1;
+    process.exitCode = error.code === 'HOST_ALREADY_RUNNING' ? EXIT_REPLACED : 1;
   }
   const stop = () => { connector.stop(); process.exit(0); };
   process.once('SIGINT', stop);

package/src/i18n/en.js

@@ -206,6 +206,7 @@ module.exports = {
   'error.invalidKeepalive': 'Unknown keep-alive manager.',
   'error.unknownField': 'Unknown setting.',
   'error.remoteUrlRequired': 'Relay URL is required for self-hosted relay mode.',
+  'error.removedHerdrArg': 'Herdr 0.9.0 removed --no-session; remove it from the extra arguments.',
   'error.saveFailed': 'Could not save configuration: {message}',
 
   'hint.navigate': '↑↓ move',

package/src/i18n/zh.js

@@ -205,6 +205,7 @@ module.exports = {
   'error.invalidKeepalive': '未知的保活管理方式。',
   'error.unknownField': '未知的设置项。',
   'error.remoteUrlRequired': '自建 Relay 模式须填写 Relay 地址。',
+  'error.removedHerdrArg': 'Herdr 0.9.0 已移除 --no-session，请从附加参数中移除。',
   'error.saveFailed': '保存配置失败：{message}',
 
   'hint.navigate': '↑↓ 移动',

package/src/service.js

@@ -166,6 +166,10 @@ function serviceSpecs(config = loadConfig(), state = ensureRuntime()) {
         RELAY_AUTH_STATE_FILE: relayAuthStatePath(),
         RELAY_ALLOWED_ORIGINS: (config.relay.allowedOrigins || []).join(','),
         RELAY_MAX_CLIENTS_PER_HOST: String(config.relay.maxClientsPerHost),
+        RELAY_MAX_HOSTS: String(config.relay.maxHosts),
+        RELAY_MAX_PENDING_HANDSHAKES: String(config.relay.maxPendingHandshakes),
+        RELAY_MAX_BUFFERED_BYTES_PER_CLIENT: String(config.relay.maxBufferedBytesPerClient),
+        RELAY_HOST_RECONNECT_GRACE_MS: String(config.relay.hostReconnectGraceMs),
       },
     });
   }
@@ -377,18 +381,26 @@ async function waitForRelay(config, { attempts = 20, delayMs = 100 } = {}) {
 }
 
 async function waitForHost(config, { attempts = 30, delayMs = 100 } = {}) {
-  let lastHealth = null;
+  const state = ensureRuntime();
+  const statusEndpoint = `${resolveAdminOrigin(config)}/api/status`;
+  let lastStatus = null;
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
-      lastHealth = await requestJson(healthUrl(config), { timeout: 800 });
-      if (lastHealth.hosts > 0) return lastHealth;
+      lastStatus = await requestJson(statusEndpoint, {
+        timeout: 800,
+        headers: {
+          'X-Herdr-Host-Id': state.hostId,
+          'X-Herdr-Host-Token': state.hostToken,
+        },
+      });
+      if (lastStatus.hosts?.some((host) => host.id === state.hostId)) return lastStatus;
     } catch (error) {
-      lastHealth = { ok: false, message: error.message };
+      lastStatus = { ok: false, message: error.message };
     }
     await new Promise((resolve) => setTimeout(resolve, delayMs));
   }
-  const error = new Error(lastHealth?.message || 'the Herdr host connector did not register with the relay');
-  error.health = lastHealth;
+  const error = new Error(lastStatus?.message || 'the Herdr host connector did not register with the relay');
+  error.health = lastStatus;
   throw error;
 }
 

package/src/settings-model.js

@@ -204,7 +204,11 @@ function setField(draft, id, rawValue) {
       break;
     }
     case 'herdrArgs': {
-      next.herdr.args = value ? value.split(/\s+/).filter(Boolean) : [];
+      const args = value ? value.split(/\s+/).filter(Boolean) : [];
+      if (args.includes('--no-session')) {
+        return { draft, errorKey: 'error.removedHerdrArg' };
+      }
+      next.herdr.args = args;
       break;
     }
     case 'language': {

package/src/supervisor.js

@@ -5,7 +5,7 @@ const { spawn } = require('node:child_process');
 const { PACKAGE_ROOT, loadConfig, runtimeStatePath, stateDir } = require('./config');
 const { ensureDir, readJson, writeJsonAtomic } = require('./state');
 const { baseEnvironment, ensureRuntime, logPath, managedPids, pidAlive, recordManagedPid, serviceSpecs } = require('./service');
-const { EXIT_REPLACED } = require('./exit-codes');
+const { EXIT_REPLACED, EXIT_AUTH_FAILED } = require('./exit-codes');
 
 const MIN_BACKOFF_MS = 500;
 const MAX_BACKOFF_MS = 30_000;
@@ -132,6 +132,14 @@ class Supervisor {
         });
         return;
       }
+      if (code === EXIT_AUTH_FAILED) {
+        this.emit({
+          type: 'fatal',
+          name,
+          message: `${name} stopped: relay authentication failed. Update credentials before restarting it.`,
+        });
+        return;
+      }
       if (uptimeMs >= HEALTHY_UPTIME_MS) entry.backoffMs = MIN_BACKOFF_MS;
       this.emit({
         type: 'exited',