@livedesk/client 0.1.199 → 0.1.201

package/bin/livedesk-client.js

@@ -11,7 +11,13 @@ import net from 'node:net';
 import os from 'node:os';
 import { formatClientVersionBanner, readClientPackageVersion } from './client-version.js';
 import { createClientRuntimeServer } from '../src/runtime/client-runtime-server.js';
-import { installAgentTerminationHandlers } from '../src/runtime/agent-process-lifecycle.js';
+import {
+    createWindowsProcessTreeTracker,
+    drainOwnedWindowsAgentTreeUntilStopped,
+    drainOwnedUnixAgentTree,
+    installAgentTerminationHandlers,
+    signalAgentTree
+} from '../src/runtime/agent-process-lifecycle.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
 import {
     inspectLinuxVideoAcceleration,
@@ -27,6 +33,8 @@ const nodeAgentPath = join(__dirname, 'livedesk-client-node.js');
 const FAST_PREFLIGHT_TIMEOUT_MS = 5000;
 const DEFAULT_MANAGER = '127.0.0.1:5197';
 const DEFAULT_HUB_CLIENT_PORT = 5197;
+const DEFAULT_RELAY_HOST = 'www.gnsoftech.com';
+const DEFAULT_RELAY_PORT = 5199;
 const DEFAULT_AUTH_CALLBACK_HOST = '127.0.0.1';
 const DEFAULT_AUTH_CALLBACK_PORT = 5179;
 const ENDPOINT_PROBE_TIMEOUT_MS = 900;
@@ -67,6 +75,22 @@ let networkChangeMonitor = null;
 const sessionRefreshesInFlight = new WeakMap();
 installAgentTerminationHandlers({ getAgentProcess: () => activeAgentProcess });
 
+function requestActiveAgentStop(signal = 'SIGTERM') {
+    const child = activeAgentProcess;
+    if (!child) return false;
+    if (process.platform === 'win32') {
+        // Internal reconnect/slot/role restarts use the same immutable
+        // PID+CreationDate tree contract as unexpected exit and terminal
+        // shutdown. Store the shared proof promise so no replacement can race.
+        if (!child.livedeskTreeStopPromise) {
+            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTreeUntilStopped(child);
+        }
+        return true;
+    }
+    signalAgentTree(child, signal);
+    return true;
+}
+
 export function requestLocalDiscoveryWake(reason = 'local-trigger') {
     const previous = discoveryWakeController;
     discoveryWakeController = new AbortController();
@@ -191,9 +215,12 @@ Default flow:
 Options:
   --slot <number>                 Screen wall slot number for this computer.
   --name <name>                   Friendly device name. Default: OS hostname.
-  --engine auto|fast|csharp|node  Select agent engine. Default: auto.
-  --fast                          Force C# RemoteFast frame.binary engine.
-  --node                          Force the legacy Node agent.
+  --engine auto|fast|csharp|node  Select agent engine. Default: auto.
+  --fast                          Force C# RemoteFast frame.binary engine.
+  --node                          Force the legacy Node agent.
+  --transport auto|tcp|ws|udp-p2p
+                                  Direct-first connection policy. Default: auto.
+  --relay <host:port>             Encrypted fallback relay. Default: www.gnsoftech.com:5199.
   --control                       Enable RemoteFast keyboard/mouse control.
   --no-control                    Disable RemoteFast keyboard/mouse control.
   --thumbnail                     Enable thumbnail capture when supported.
@@ -225,7 +252,7 @@ function isTruthy(value) {
     return /^(1|true|yes|on)$/i.test(String(value || '').trim());
 }
 
-function normalizeEngine(value) {
+function normalizeEngine(value) {
     const engine = String(value || 'auto').trim().toLowerCase();
     if (engine === 'c#' || engine === 'csharp' || engine === 'fast') {
         return 'fast';
@@ -233,11 +260,54 @@ function normalizeEngine(value) {
     if (engine === 'js' || engine === 'node' || engine === 'legacy') {
         return 'node';
     }
-    return 'auto';
-}
-
-function parseLauncherArgs(argv) {
-    const forwarded = [];
+    return 'auto';
+}
+
+function normalizeClientTransport(value) {
+    const transport = String(value || 'auto').trim().toLowerCase();
+    if (transport === 'legacy') return 'tcp';
+    if (transport === 'wss') return 'ws';
+    if (transport === 'udp-relay') return 'udp-p2p';
+    return ['auto', 'tcp', 'ws', 'udp-p2p'].includes(transport)
+        ? transport
+        : 'tcp';
+}
+
+export function parseClientTransportOption(value) {
+    const transport = String(value || '').trim().toLowerCase();
+    if (!['auto', 'tcp', 'legacy', 'ws', 'wss', 'udp-p2p', 'udp-relay'].includes(transport)) {
+        throw new Error(`Unsupported LiveDesk Client transport: ${value || '(missing)'}`);
+    }
+    return normalizeClientTransport(transport);
+}
+
+function transportAllowsRelay(transport) {
+    return transport === 'auto' || transport === 'udp-p2p';
+}
+
+export function resolveClientRelayEndpoint(env = process.env) {
+    const explicit = String(
+        env.LIVEDESK_CLIENT_RELAY
+        || env.LIVEDESK_RELAY_ENDPOINT
+        || ''
+    ).trim().replace(/^tcp:\/\//i, '');
+    if (parseManagerEndpoint(explicit)) {
+        return explicit;
+    }
+    const host = String(
+        env.LIVEDESK_RELAY_HOST
+        || env.LIVEDESK_UDP_RENDEZVOUS_HOST
+        || DEFAULT_RELAY_HOST
+    ).trim();
+    const port = normalizePort(
+        env.LIVEDESK_RELAY_PORT
+        || env.LIVEDESK_UDP_RENDEZVOUS_PORT
+    ) || DEFAULT_RELAY_PORT;
+    return host ? `${host}:${port}` : '';
+}
+
+export function parseLauncherArgs(argv) {
+    const forwarded = [];
     let engine = normalizeEngine(process.env.LIVEDESK_CLIENT_ENGINE || process.env.MINDEXEC_REMOTE_ENGINE);
     let help = false;
     let loginRequested = false;
@@ -245,7 +315,18 @@ function parseLauncherArgs(argv) {
     let logout = false;
     let version = false;
     let manager = process.env.LIVEDESK_CLIENT_MANAGER || process.env.MINDEXEC_REMOTE_MANAGER || '';
-    let pair = process.env.LIVEDESK_CLIENT_PAIR_TOKEN || process.env.MINDEXEC_REMOTE_PAIR_TOKEN || '';
+    let pair = process.env.LIVEDESK_CLIENT_PAIR_TOKEN || process.env.MINDEXEC_REMOTE_PAIR_TOKEN || '';
+    let transport = normalizeClientTransport(
+        process.env.LIVEDESK_CLIENT_TRANSPORT || process.env.MINDEXEC_REMOTE_TRANSPORT);
+    let relay = resolveClientRelayEndpoint();
+    const requireFast = isTruthy(process.env.LIVEDESK_CLIENT_REQUIRE_FAST);
+    let relayExplicit = Boolean(String(
+        process.env.LIVEDESK_CLIENT_RELAY
+        || process.env.LIVEDESK_RELAY_ENDPOINT
+        || process.env.LIVEDESK_RELAY_HOST
+        || process.env.LIVEDESK_UDP_RENDEZVOUS_HOST
+        || ''
+    ).trim());
     let deviceId = String(process.env.LIVEDESK_DEVICE_ID || '').trim();
     let slot = process.env.LIVEDESK_CLIENT_SLOT || process.env.MINDEXEC_REMOTE_SLOT || '';
     let authPort = normalizePort(process.env.LIVEDESK_CLIENT_RUNTIME_PORT || process.env.LIVEDESK_CLIENT_AUTH_PORT) || DEFAULT_AUTH_CALLBACK_PORT;
@@ -325,13 +406,28 @@ function parseLauncherArgs(argv) {
             index += 1;
             continue;
         }
-        if (arg === '--pair') {
-            pair = argv[index + 1] || pair;
-            forwarded.push(arg, argv[index + 1]);
-            index += 1;
-            continue;
-        }
-        if (arg === '--device-id') {
+        if (arg === '--pair') {
+            pair = argv[index + 1] || pair;
+            forwarded.push(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === '--transport') {
+            transport = parseClientTransportOption(argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === '--relay') {
+            const candidate = String(argv[index + 1] || '').trim().replace(/^tcp:\/\//i, '');
+            if (!parseManagerEndpoint(candidate)) {
+                throw new Error(`Invalid LiveDesk relay endpoint: ${argv[index + 1] || '(missing)'}`);
+            }
+            relay = candidate;
+            relayExplicit = true;
+            index += 1;
+            continue;
+        }
+        if (arg === '--device-id') {
             deviceId = argv[index + 1] || deviceId;
             forwarded.push(arg, argv[index + 1]);
             index += 1;
@@ -371,9 +467,13 @@ function parseLauncherArgs(argv) {
         loginDisabled,
         logout,
         version,
-        manager,
-        pair,
-        deviceId,
+        manager,
+        pair,
+        transport,
+        relay,
+        relayExplicit,
+        requireFast,
+        deviceId,
         slot,
         authPort,
         nodeOnlyFeature,
@@ -551,13 +651,19 @@ function buildStartupClientArgs(parsed) {
     if (slot) {
         args.push(slot);
     }
-    if (parsed.engine === 'fast') {
-        args.push('--fast');
-    } else if (parsed.engine === 'node') {
-        args.push('--node');
-    }
-
-    const forwarded = Array.isArray(parsed.forwarded) ? parsed.forwarded : [];
+    if (parsed.engine === 'fast') {
+        args.push('--fast');
+    } else if (parsed.engine === 'node') {
+        args.push('--node');
+    }
+    if (parsed.transport && parsed.transport !== 'auto') {
+        args.push('--transport', parsed.transport);
+    }
+    if (parsed.relayExplicit && parsed.relay) {
+        args.push('--relay', parsed.relay);
+    }
+
+    const forwarded = Array.isArray(parsed.forwarded) ? parsed.forwarded : [];
     for (let index = 0; index < forwarded.length; index += 1) {
         const arg = forwarded[index];
         if (!arg || arg === 'connect') {
@@ -2449,7 +2555,7 @@ function readRequestBody(req, maxBytes = 4096) {
     });
 }
 
-async function resolveManagerFromPin(supabase, pin) {
+async function resolveManagerFromPin(supabase, pin, options = {}) {
     const normalizedPin = normalizePairingPin(pin);
     if (!normalizedPin) {
         throw new Error('Enter a 6-digit LiveDesk PIN.');
@@ -2478,16 +2584,20 @@ async function resolveManagerFromPin(supabase, pin) {
     if (endpointCandidates.length === 0) {
         throw new Error('The PIN matched a Hub record without a reachable address.');
     }
-    const manager = await chooseReachableEndpoint(endpointCandidates, { requireReachable: true });
-    if (!manager) {
-        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
-    }
-
+    const target = await chooseManagerConnectionTarget(endpointCandidates, {
+        allowRelayFallback: options.allowRelayFallback === true
+    });
+    if (!target) {
+        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
+    }
+
     const resolved = {
-        manager,
+        manager: target.manager,
         pair: result.pair_token,
         hubDeviceId: String(result.node_id || '').trim(),
         endpointCandidates,
+        directReachable: target.directReachable,
+        connectionTransport: target.connectionTransport,
         discoverySource: 'supabase'
     };
     writeCachedHubTarget(cacheOwnerKey, resolved);
@@ -2506,7 +2616,9 @@ async function waitForManagerFromSavedPin(supabase, pin, options = {}) {
         }
         attempts += 1;
         try {
-            return await resolveManagerFromPin(supabase, pin);
+            return await resolveManagerFromPin(supabase, pin, {
+                allowRelayFallback: options.allowRelayFallback === true
+            });
         } catch (err) {
             if (shouldStop()) {
                 return null;
@@ -2783,7 +2895,7 @@ async function startConnectionChoiceServer(supabase, options = {}) {
                     res.end(JSON.stringify({ ok: true, restarting: true, role: 'hub', roleVersion: nextRoleVersion }));
                     setTimeout(() => {
                         try {
-                            activeAgentProcess?.kill();
+                            requestActiveAgentStop();
                         } catch {
                         }
                         try {
@@ -2890,7 +3002,9 @@ async function startConnectionChoiceServer(supabase, options = {}) {
                 pendingStartup = normalizeStartupChoice(startupValue, pendingStartup);
                 pin = normalizePairingPin(pin);
                 try {
-                    const resolved = await resolveManagerFromPin(supabase, pin);
+                    const resolved = await resolveManagerFromPin(supabase, pin, {
+                        allowRelayFallback: options.allowRelayFallback === true
+                    });
                     writeSavedPin(pin);
                     applyStartupPreference(pendingStartup, startupArgs);
                     const choice = { type: 'pin', ...resolved };
@@ -3051,7 +3165,9 @@ async function chooseClientConnection(supabase, options = {}) {
             },
             resolvePin: pin => {
                 if (!supabase) throw new Error('supabase-session-required');
-                return resolveManagerFromPin(supabase, pin);
+                return resolveManagerFromPin(supabase, pin, {
+                    allowRelayFallback: options.allowRelayFallback === true
+                });
             },
             changeRole: async (role, snapshot) => {
                 if (!supabase) {
@@ -3080,7 +3196,7 @@ async function chooseClientConnection(supabase, options = {}) {
                 writeLocalRoleCache(role, options.deviceId, roleVersion);
                 roleRestartRequest = { role, requestedAt: new Date().toISOString() };
                 requestLocalDiscoveryWake('role-change');
-                try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop observes the role request */ }
+                try { requestActiveAgentStop(); } catch { /* the lifecycle loop observes the role request */ }
                 return { ok: true, restarting: true, role, roleVersion };
             },
             videoAcceleration: linuxVideoAccelerationStatus,
@@ -3098,7 +3214,7 @@ async function chooseClientConnection(supabase, options = {}) {
                     requestedAt: new Date().toISOString()
                 };
                 requestLocalDiscoveryWake('linux-video-acceleration-ready');
-                try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the new ffmpeg preference */ }
+                try { requestActiveAgentStop(); } catch { /* the lifecycle loop restarts with the new ffmpeg preference */ }
             },
             assignSlot: async request => {
                 const result = await requestHubSlotAssignment(request);
@@ -3113,20 +3229,20 @@ async function chooseClientConnection(supabase, options = {}) {
                 };
                 requestLocalDiscoveryWake('slot-updated');
                 setTimeout(() => {
-                    try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the saved slot */ }
+                    try { requestActiveAgentStop(); } catch { /* the lifecycle loop restarts with the saved slot */ }
                 }, 150);
                 return { ...result, slotNumber, saved: true, restarting: true };
             },
             onRestart: () => process.kill(process.pid, 'SIGTERM'),
             onShutdown: () => process.kill(process.pid, 'SIGTERM'),
-            onDisconnect: () => activeAgentProcess?.kill(),
+            onDisconnect: () => requestActiveAgentStop(),
             // Ending the current Agent causes the unified lifecycle loop to
             // discard its old manager/pair token and start Supabase discovery
             // again.  Leaving this empty made the Reconnect button a success
             // response with no actual transport work.
             onReconnect: () => {
                 requestLocalDiscoveryWake('manual-reconnect');
-                activeAgentProcess?.kill();
+                requestActiveAgentStop();
             }
         });
         await connectionPage.start();
@@ -3147,9 +3263,10 @@ async function chooseClientConnection(supabase, options = {}) {
         deviceId: options.deviceId,
         slot: options.slot,
         startupArgs: options.startupArgs,
-        savedSession: options.savedSession,
-        savedPin: options.savedPin
-    });
+        savedSession: options.savedSession,
+        savedPin: options.savedPin,
+        allowRelayFallback: options.allowRelayFallback === true
+    });
     if (options.openBrowser !== false) {
         console.log('Opening LiveDesk connection page...');
         openBrowser(connectionPage.url);
@@ -3164,11 +3281,11 @@ function parseManagerEndpoint(value) {
     if (separator <= 0) {
         return null;
     }
-    const host = text.slice(0, separator).replace(/^\[/, '').replace(/\]$/, '').trim();
-    const port = Number(text.slice(separator + 1));
-    if (!host || !Number.isFinite(port)) {
-        return null;
-    }
+    const host = text.slice(0, separator).replace(/^\[/, '').replace(/\]$/, '').trim();
+    const port = Number(text.slice(separator + 1));
+    if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
+        return null;
+    }
     return { host, port };
 }
 
@@ -3294,6 +3411,37 @@ export async function chooseReachableEndpoint(candidates, options = {}) {
     });
 }
 
+export async function chooseManagerConnectionTarget(candidates, options = {}) {
+    const endpoints = [...new Set((Array.isArray(candidates) ? candidates : [])
+        .map(value => String(value || '').trim())
+        .filter(Boolean))];
+    if (endpoints.length === 0) return null;
+
+    const manager = await chooseReachableEndpoint(endpoints, {
+        requireReachable: true,
+        probeEndpoint: options.probeEndpoint
+    });
+    if (manager) {
+        return {
+            manager,
+            directReachable: true,
+            connectionTransport: 'direct-tcp'
+        };
+    }
+    if (options.allowRelayFallback !== true) {
+        return null;
+    }
+    return {
+        // The account/PIN response is the authority for this retry candidate.
+        // RemoteFast gives it one bounded direct attempt, then uses the
+        // pair-token-authenticated encrypted relay rather than keeping the
+        // launcher in an indefinite TCP reachability loop.
+        manager: endpoints[0],
+        directReachable: false,
+        connectionTransport: 'relay-fallback'
+    };
+}
+
 export async function resolveManagerFromCachedTarget(ownerKey, options = {}) {
     const cached = options.cachedTarget || readCachedHubTarget(ownerKey);
     if (!cached) return null;
@@ -3389,15 +3537,19 @@ async function resolveManagerFromSupabase(supabase, options = {}) {
     if (endpointCandidates.length === 0) {
         throw new Error('The LiveDesk Hub record does not contain a reachable local address.');
     }
-    const manager = await chooseReachableEndpoint(endpointCandidates, { requireReachable: options.requireReachable === true });
-    if (!manager) {
-        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
-    }
-    return {
-        manager,
-        pair: data.pair_token,
-        hubDeviceId: String(data.node_id || '').trim(),
-        endpointCandidates
+    const target = await chooseManagerConnectionTarget(endpointCandidates, {
+        allowRelayFallback: options.allowRelayFallback === true
+    });
+    if (!target) {
+        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
+    }
+    return {
+        manager: target.manager,
+        pair: data.pair_token,
+        hubDeviceId: String(data.node_id || '').trim(),
+        endpointCandidates,
+        directReachable: target.directReachable,
+        connectionTransport: target.connectionTransport
     };
 }
 
@@ -3440,7 +3592,9 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
             }
             attempts += 1;
             try {
-                return await resolveManagerFromSupabase(supabase, { requireReachable: true });
+                return await resolveManagerFromSupabase(supabase, {
+                    allowRelayFallback: options.allowRelayFallback === true
+                });
             } catch (err) {
                 const message = formatDiscoveryError(err);
                 if (message !== lastMessage || attempts === 1 || attempts % 6 === 0) {
@@ -3493,6 +3647,9 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
     let pair = parsed.pair;
     let connectionPage = null;
     let discoverySource = '';
+    let connectionTransport = '';
+    let directReachable = false;
+    const allowRelayFallback = transportAllowsRelay(parsed.transport);
 
     if (shouldLogin) {
         const supabase = await createSupabaseClient();
@@ -3509,7 +3666,9 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
         if ((parsed.startupRun || existingConnectionPage) && savedSession?.access_token) {
             choice = { type: 'google', session: savedSession };
         } else if ((parsed.startupRun || existingConnectionPage) && savedPin) {
-            const resolved = await waitForManagerFromSavedPin(supabase, savedPin);
+            const resolved = await waitForManagerFromSavedPin(supabase, savedPin, {
+                allowRelayFallback
+            });
             choice = { type: 'pin', ...resolved };
         } else if (existingConnectionPage && previousChoice) {
             choice = previousChoice;
@@ -3521,10 +3680,11 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 deviceId: parsed.deviceId,
                 engine: parsed.engine,
                 slot: parsed.slot,
-                startupArgs,
-                savedSession,
-                savedPin,
-                openBrowser: parsed.openBrowserOnStart
+                startupArgs,
+                savedSession,
+                savedPin,
+                allowRelayFallback,
+                openBrowser: parsed.openBrowserOnStart
             });
         }
         connectionPage = existingConnectionPage || choice.connectionPage || null;
@@ -3532,19 +3692,27 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
             manager = choice.manager;
             pair = choice.pair;
             discoverySource = choice.discoverySource || 'supabase';
+            connectionTransport = choice.connectionTransport || 'direct-tcp';
+            directReachable = choice.directReachable !== false;
             connectionPage?.update({
                 endpointCandidates: choice.endpointCandidates || [],
                 manager,
                 assignedHubId: choice.hubDeviceId || '',
-                message: `Connected to LiveDesk Hub at ${manager}.`
-            });
-            console.log('Connected by LiveDesk PIN.');
+                message: connectionTransport === 'relay-fallback'
+                    ? `LiveDesk Hub found at ${manager}; starting encrypted relay fallback.`
+                    : `Connected to LiveDesk Hub at ${manager}.`
+            });
+            console.log(connectionTransport === 'relay-fallback'
+                ? 'LiveDesk PIN accepted. Direct TCP is unavailable; starting encrypted relay fallback.'
+                : 'Connected by LiveDesk PIN.');
         } else {
             const cacheOwnerKey = hubCacheOwnerForSession(choice.session);
             let resolved = await resolveManagerFromCachedTarget(cacheOwnerKey);
             let session = choice.session;
             discoverySource = resolved ? 'cache' : 'supabase';
             if (resolved) {
+                connectionTransport = resolved.connectionTransport || 'direct-tcp';
+                directReachable = resolved.directReachable !== false;
                 writeSavedSessionToFile(session);
                 console.log(`Found cached LiveDesk Hub at ${resolved.manager}; skipped registry discovery.`);
             } else {
@@ -3565,6 +3733,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
             console.log(`Signed in to LiveDesk${email}.`);
             if (!resolved) {
                 resolved = await waitForManagerFromSupabase(supabase, {
+                    allowRelayFallback,
                     shouldStop: () => Boolean(roleRestartRequest?.role)
                 });
             }
@@ -3593,15 +3762,21 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 }
             }
             manager = resolved.manager;
-            pair = resolved.pair;
+            pair = resolved.pair;
+            connectionTransport = resolved.connectionTransport || 'direct-tcp';
+            directReachable = resolved.directReachable !== false;
             connectionPage?.update({
                 endpointCandidates: resolved.endpointCandidates || [],
                 manager,
                 assignedHubId: resolved.hubDeviceId || '',
-                message: `Connected to LiveDesk Hub at ${manager}.`
-            });
-        }
-        console.log(`Found LiveDesk Hub at ${manager}.`);
+                message: connectionTransport === 'relay-fallback'
+                    ? `LiveDesk Hub found at ${manager}; starting encrypted relay fallback.`
+                    : `Connected to LiveDesk Hub at ${manager}.`
+            });
+        }
+        console.log(connectionTransport === 'relay-fallback'
+            ? `Found LiveDesk Hub record at ${manager}; direct TCP did not answer, so RemoteFast will use the encrypted rendezvous relay.`
+            : `Found LiveDesk Hub at ${manager}.`);
     }
     // Exact-package updates preserve the already paired Hub endpoint and pass
     // --no-login so the replacement cannot block on browser auth. The unified
@@ -3647,12 +3822,16 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
         forwarded = appendForwardedFlag(forwarded, '--exit-on-invalid-pair');
     }
     return {
-        ...parsed,
-        manager,
-        pair,
-        slot,
+        ...parsed,
+        manager,
+        pair,
+        transport: parsed.transport,
+        relay: parsed.relay,
+        slot,
         connectionPage,
         forwarded,
+        connectionTransport: connectionTransport || 'direct-tcp',
+        directReachable: connectionTransport === 'relay-fallback' ? false : (directReachable || !shouldLogin),
         discoverySource,
         rediscoverOnDisconnect: shouldLogin,
         rediscoverOnInvalidPair: shouldLogin
@@ -3872,7 +4051,9 @@ function buildClientAgentEnvironment(prepared) {
     env.LIVEDESK_CLIENT_SLOT = String(prepared?.slot || env.LIVEDESK_CLIENT_SLOT || '');
     env.LIVEDESK_DEVICE_ID = String(prepared?.deviceId || env.LIVEDESK_DEVICE_ID || '');
     env.LIVEDESK_CLIENT_ENGINE = String(prepared?.engine || env.LIVEDESK_CLIENT_ENGINE || 'auto');
-    env.LIVEDESK_CLIENT_TRANSPORT = String(env.LIVEDESK_CLIENT_TRANSPORT || 'auto');
+    env.LIVEDESK_CLIENT_TRANSPORT = String(prepared?.transport || env.LIVEDESK_CLIENT_TRANSPORT || 'auto');
+    env.LIVEDESK_CLIENT_RELAY = String(prepared?.relay || env.LIVEDESK_CLIENT_RELAY || '');
+    env.LIVEDESK_CLIENT_REQUIRE_FAST = requiresFastTransport(prepared) ? '1' : '0';
     env.LIVEDESK_UDP_ENABLED = String(env.LIVEDESK_UDP_ENABLED || '1');
     env.LIVEDESK_CLIENT_UPDATE_STATE_PATH = CLIENT_UPDATE_STATE_PATH;
     env.LIVEDESK_CLIENT_UPDATE_ARGS_BASE64 = Buffer
@@ -3985,23 +4166,35 @@ function prepareFastExecutable(executable) {
     }
 }
 
-function buildFastArgs(args, fakeThumbnail) {
-    const forwarded = [];
-    for (const arg of args) {
-        if (arg === '--fake-thumbnail') {
-            forwarded.push('--fake-frame');
-            continue;
+export function buildFastArgs(args, fakeThumbnail, transport = 'auto', relay = '') {
+    const forwarded = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--transport' || arg === '--relay') {
+            index += 1;
+            continue;
+        }
+        if (arg === '--fake-thumbnail') {
+            forwarded.push('--fake-frame');
+            continue;
         }
         if (arg === '--tasks' || arg === '--no-tasks' || arg === '--no-ai') {
             continue;
         }
         forwarded.push(arg);
     }
-    if (fakeThumbnail && !forwarded.includes('--fake-frame')) {
-        forwarded.push('--fake-frame');
-    }
-    return forwarded;
-}
+    if (fakeThumbnail && !forwarded.includes('--fake-frame')) {
+        forwarded.push('--fake-frame');
+    }
+    let launchArgs = upsertForwardedOption(
+        forwarded,
+        '--transport',
+        normalizeClientTransport(transport));
+    if (transportAllowsRelay(normalizeClientTransport(transport))) {
+        launchArgs = upsertForwardedOption(launchArgs, '--relay', relay);
+    }
+    return launchArgs;
+}
 
 function redactAgentArgs(args = []) {
     const redacted = [];
@@ -4103,6 +4296,7 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
         restartVerified: false
     });
     const ownsProcessGroup = process.platform !== 'win32';
+    const agentSpawnedAtMs = Date.now();
     const child = spawn(command, args, {
         env,
         stdio: 'inherit',
@@ -4113,24 +4307,78 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
         windowsHide: true
     });
     child.livedeskOwnsProcessGroup = ownsProcessGroup;
+    child.livedeskWindowsTreeTracker = createWindowsProcessTreeTracker(child, {
+        spawnedAtMs: agentSpawnedAtMs
+    });
     activeAgentProcess = child;
     if (typeof onStart === 'function') {
         onStart(child);
     }
 
-    return new Promise(resolve => {
-        child.once('error', error => {
-            console.error(`Failed to launch ${command}: ${error.message}`);
-            resolve({ code: 1, signal: null });
-        });
-        child.once('exit', (code, signal) => {
-            if (activeAgentProcess === child) {
-                activeAgentProcess = null;
-            }
-            resolve({ code: code ?? 0, signal });
-        });
-    });
-}
+    return new Promise(resolve => {
+        let settling = false;
+        child.once('error', error => {
+            if (settling) return;
+            settling = true;
+            child.livedeskWindowsTreeTracker?.stop?.();
+            if (activeAgentProcess === child) {
+                activeAgentProcess = null;
+            }
+            console.error(`Failed to launch ${command}: ${error.message}`);
+            resolve({ code: 1, signal: null });
+        });
+        child.once('exit', (code, signal) => {
+            if (settling) return;
+            settling = true;
+            child.livedeskWindowsTreeTracker?.markRootExited?.();
+            // The Unix Agent is a dedicated process-group leader. Its exit
+            // event proves only that the leader stopped; SCK/FFmpeg capture
+            // descendants can still own that PGID. Keep active ownership and
+            // do not let the lifecycle loop launch a replacement until the
+            // complete group has drained.
+            void (async () => {
+                try {
+                    if (process.platform === 'win32') {
+                        if (!child.livedeskTreeStopPromise) {
+                            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTreeUntilStopped(child);
+                        }
+                        const windowsTreeStop = await child.livedeskTreeStopPromise;
+                        if (windowsTreeStop?.ok === false) {
+                            throw new Error(
+                                `exact Windows Agent tree drain failed: `
+                                + `${windowsTreeStop.error?.message || 'bounded immutable-tree cleanup failed'}`
+                            );
+                        }
+                    }
+                    await drainOwnedUnixAgentTree(child);
+                } catch (error) {
+                    console.error(
+                        `[LiveDesk Client] Could not drain exited Agent tree pid=${child.pid || 'unknown'}: `
+                        + `${error?.message || error}`
+                    );
+                    // Block this lifecycle iteration from spawning a
+                    // replacement, but settle explicitly so the launcher
+                    // terminates instead of hanging forever.
+                    child.livedeskWindowsTreeTracker?.stop?.();
+                    if (activeAgentProcess === child) {
+                        activeAgentProcess = null;
+                    }
+                    resolve({
+                        code: 1,
+                        signal: null,
+                        lifecycleFailure: String(error?.message || error)
+                    });
+                    return;
+                }
+                child.livedeskWindowsTreeTracker?.stop?.();
+                if (activeAgentProcess === child) {
+                    activeAgentProcess = null;
+                }
+                resolve({ code: code ?? 0, signal });
+            })();
+        });
+    });
+}
 
 function shouldUseFast(parsed) {
     if (parsed.engine === 'node') {
@@ -4142,12 +4390,20 @@ function shouldUseFast(parsed) {
     return !parsed.nodeOnlyFeature;
 }
 
-function shouldTryFast(parsed, runtime) {
+function shouldTryFast(parsed, runtime) {
     if (parsed.engine === 'fast') {
         return true;
     }
     return shouldUseFast(parsed) && !!runtime;
-}
+}
+
+export function requiresFastTransport(prepared = {}) {
+    return prepared.requireFast === true
+        || prepared.connectionTransport === 'relay-fallback'
+        || prepared.transport === 'udp-p2p'
+        || prepared.transport === 'ws'
+        || prepared.relayExplicit === true;
+}
 
 export async function runClientRuntime(argv = process.argv.slice(2)) {
     startNetworkChangeMonitor();
@@ -4201,9 +4457,16 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
             await spawnUnifiedRoleRestart(roleRestartBeforeAgent.role);
             connectionPage?.close?.();
             process.exit(0);
-        }
+        }
         const fastRuntime = getFastRuntime();
-        const useFast = shouldTryFast(prepared, fastRuntime);
+        const fastRequired = requiresFastTransport(prepared);
+        if (fastRequired && prepared.engine === 'node') {
+            throw new Error(
+                'The legacy Node engine cannot use WebSocket, UDP P2P, or encrypted relay transport. '
+                + 'Use --engine fast, or use --transport tcp while the Hub is directly reachable.'
+            );
+        }
+        const useFast = fastRequired || shouldTryFast(prepared, fastRuntime);
         const agentLaunchStartedAt = Date.now();
         const updateAgentDashboard = (patch = {}) => {
             prepared.connectionPage?.update({
@@ -4217,11 +4480,15 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                     ? `LiveDesk client agent is running with ${patch.engine || 'agent'} mode.`
                     : 'LiveDesk client agent is launching.'
             });
-        };
-        let result;
-        if (useFast) {
-            const fastArgs = buildFastArgs(prepared.forwarded, prepared.fakeThumbnail);
-            const fastLaunch = resolveFastLaunch(fastRuntime);
+        };
+        let result;
+        if (useFast) {
+            const fastArgs = buildFastArgs(
+                prepared.forwarded,
+                prepared.fakeThumbnail,
+                prepared.transport,
+                prepared.relay);
+            const fastLaunch = resolveFastLaunch(fastRuntime);
             if (fastLaunch.ok) {
                 const launchArgs = [...fastLaunch.argsPrefix, ...fastArgs];
                 updateAgentDashboard({
@@ -4242,10 +4509,15 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                         state: 'running'
                     });
                 });
-            } else if (prepared.engine === 'fast') {
-                console.error(`C# RemoteFast is unavailable: ${fastLaunch.reason}. Use --engine node to run the legacy Node agent.`);
-                prepared.connectionPage?.close?.();
-                process.exit(2);
+            } else if (prepared.engine === 'fast' || fastRequired) {
+                console.error(
+                    `C# RemoteFast is unavailable: ${fastLaunch.reason}. `
+                    + (fastRequired
+                        ? 'The requested P2P, WebSocket, or encrypted relay transport requires the packaged RemoteFast runtime; the legacy Node agent was not started.'
+                        : 'Use --engine node to run the legacy Node agent.')
+                );
+                prepared.connectionPage?.close?.();
+                process.exit(2);
             } else {
                 console.warn(`C# RemoteFast is unavailable (${fastLaunch.reason}). Falling back to the Node remote agent.`);
                 const launchArgs = [nodeAgentPath, ...prepared.forwarded];
@@ -4286,9 +4558,36 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                     pid: child.pid,
                     startedAt: new Date().toISOString(),
                     state: 'running'
-                });
-            });
-        }
+                });
+            });
+        }
+        // Contract: once the owned Agent exits, the local runtime must stop
+        // advertising its old PID before any restart or Hub rediscovery.
+        // Keeping a dead PID makes status diagnostics lie and causes manual
+        // reconnect to target a process that no longer exists.
+        prepared.connectionPage?.update({
+            agent: {
+                requestedEngine: prepared.engine,
+                state: 'stopped',
+                pid: 0,
+                stoppedAt: new Date().toISOString(),
+                exitCode: Number.isInteger(result?.code) ? result.code : null,
+                exitSignal: result?.signal || ''
+            }
+        });
+        if (result?.lifecycleFailure) {
+            prepared.connectionPage?.update({
+                agent: {
+                    requestedEngine: prepared.engine,
+                    state: 'failed',
+                    pid: 0,
+                    error: result.lifecycleFailure
+                },
+                message: 'LiveDesk stopped because the previous Windows capture tree could not be drained safely.'
+            });
+            connectionPage?.close?.();
+            throw new Error(result.lifecycleFailure);
+        }
         const requestedRoleRestart = connectionPage?.getRoleRestartRequest?.();
         if (requestedRoleRestart?.role) {
             if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
@@ -4302,7 +4601,8 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
             connectionPage?.update({
                 agent: {
                     requestedEngine: prepared.engine,
-                    state: 'reconnecting'
+                    state: 'reconnecting',
+                    pid: 0
                 },
                 message: restart.reason === 'slot-updated'
                     ? `Slot ${String(restart.slotNumber || prepared.slot || '').padStart(3, '0')} saved. Restarting the LiveDesk Agent.`
@@ -4331,10 +4631,11 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                 ? 'LiveDesk Hub pair token changed. Refreshing Hub discovery now.'
                 : 'LiveDesk Hub connection ended. Looking for the current Hub now.');
             connectionPage?.update({
-                agent: {
-                    requestedEngine: prepared.engine,
-                    state: 'reconnecting'
-                },
+                agent: {
+                    requestedEngine: prepared.engine,
+                    state: 'reconnecting',
+                    pid: 0
+                },
                 manager: '',
                 message: 'The previous Hub is unavailable. LiveDesk is finding the current Hub automatically.'
             });