livedesk 0.1.250 → 0.1.252

package/README.md

@@ -16,10 +16,12 @@ continues to listen on the LAN.
 On startup, the launcher finds stale processes whose command line identifies
 them as a LiveDesk Hub, even if the old Hub is still starting and has not
 finished binding its ports. It also checks the Hub ports (`5179` and `5197`),
-waits for the old process and both ports to be released, and then starts the
-new Hub. An unrelated process is preserved and reported instead of being
-terminated; use `--port`, `--remote-port`, or stop that process manually. Pass
-`--no-clean` to disable the startup cleanup explicitly.
+waits for stale LiveDesk processes to exit, and then starts the new Hub. The
+client endpoint remains fixed at TCP `5197` by default so firewall rules,
+router forwarding, and direct clients keep a stable contract. An unrelated
+process is preserved and reported instead of being terminated; stop it or use
+an explicit `--remote-port` value. Pass `--no-clean` to disable the startup
+cleanup explicitly.
 
 ## Client
 

package/bin/livedesk.js

@@ -37,7 +37,7 @@ Hub options:
   --host <host>  Hub HTTP host. Default: 127.0.0.1
   --port <port>  Hub HTTP port. Default: 5179
   --remote-port <port>
-                 Client connection port. Default: 5197
+                 Client connection port. Default: 5197.
   --no-clean     Do not stop existing processes on the Hub ports.
 
 Common:
@@ -292,7 +292,7 @@ async function stopProcessesOnPorts(ports) {
     const blocked = records.filter(record => record?.PortAvailable !== true || (record?.Port === 0 && record?.ProcessGone !== true));
     if (blocked.length > 0) {
       const summary = blocked.map(record => `${record.Pid}:${record.ProcessName || 'unknown'}@${record.Port}[port-free=${record.PortAvailable === true},process-gone=${record.ProcessGone === true}]`).join(', ');
-      throw new Error(`LiveDesk Hub startup cleanup could not release port/process owner(s): ${summary}. If this is an unrelated process, use --port/--remote-port or stop it manually.`);
+      throw new Error(`LiveDesk Hub startup cleanup could not release port/process owner(s): ${summary}. LiveDesk keeps the configured port fixed; stop that process or choose an explicit --port/--remote-port value.`);
     }
     return;
   }

package/hub/src/remote-hub.js

@@ -4371,21 +4371,20 @@ export function createRemoteHub(options = {}) {
         });
     }
 
-    async function start() {
-        if (!enabled || started) {
-            return getStatus({ includeSecrets: false });
-        }
-
-        await new Promise((resolve, reject) => {
-            server = net.createServer(handleSocket);
-            server.once('error', err => {
+    function listenOnPort(port) {
+        return new Promise((resolve, reject) => {
+            const candidateServer = net.createServer(handleSocket);
+            server = candidateServer;
+            candidateServer.once('error', err => {
                 lastError = err?.message || String(err);
-                server = null;
+                if (server === candidateServer) {
+                    server = null;
+                }
                 reject(err);
             });
-            server.listen(requestedPort, host, () => {
+            candidateServer.listen(port, host, () => {
                 started = true;
-                boundPort = server.address()?.port || requestedPort;
+                boundPort = candidateServer.address()?.port || port;
                 lastError = '';
                 logEvent('remote', `LiveDesk Hub client endpoint listening on tcp://${host}:${boundPort}`, 'success');
                 if (host === '0.0.0.0' || host === '::') {
@@ -4395,6 +4394,27 @@ export function createRemoteHub(options = {}) {
                 resolve();
             });
         });
+    }
+
+    async function start() {
+        if (!enabled || started) {
+            return getStatus({ includeSecrets: false });
+        }
+
+        try {
+            await listenOnPort(requestedPort);
+        } catch (error) {
+            if (error?.code === 'EADDRINUSE') {
+                const conflict = new Error(
+                    `LiveDesk Hub requires client endpoint TCP ${requestedPort}, but that port is already in use. Close the owning process or start Hub with an explicit --remote-port value.`);
+                conflict.code = 'EADDRINUSE';
+                conflict.port = requestedPort;
+                conflict.cause = error;
+                lastError = conflict.message;
+                throw conflict;
+            }
+            throw error;
+        }
 
         return getStatus({ includeSecrets: false });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livedesk",
-  "version": "0.1.250",
+  "version": "0.1.252",
   "description": "LiveDesk Hub and client launcher",
   "type": "module",
   "bin": {