@livedesk/client 0.1.200 → 0.1.201

package/bin/livedesk-client.js

@@ -13,7 +13,7 @@ import { formatClientVersionBanner, readClientPackageVersion } from './client-ve
 import { createClientRuntimeServer } from '../src/runtime/client-runtime-server.js';
 import {
     createWindowsProcessTreeTracker,
-    drainOwnedWindowsAgentTree,
+    drainOwnedWindowsAgentTreeUntilStopped,
     drainOwnedUnixAgentTree,
     installAgentTerminationHandlers,
     signalAgentTree
@@ -33,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;
@@ -81,7 +83,7 @@ function requestActiveAgentStop(signal = 'SIGTERM') {
         // 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 = drainOwnedWindowsAgentTree(child);
+            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTreeUntilStopped(child);
         }
         return true;
     }
@@ -213,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.
@@ -247,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';
@@ -255,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;
@@ -267,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;
@@ -347,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;
@@ -393,9 +467,13 @@ function parseLauncherArgs(argv) {
         loginDisabled,
         logout,
         version,
-        manager,
-        pair,
-        deviceId,
+        manager,
+        pair,
+        transport,
+        relay,
+        relayExplicit,
+        requireFast,
+        deviceId,
         slot,
         authPort,
         nodeOnlyFeature,
@@ -573,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') {
@@ -2471,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.');
@@ -2500,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);
@@ -2528,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;
@@ -2912,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 };
@@ -3073,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) {
@@ -3169,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);
@@ -3186,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 };
 }
 
@@ -3316,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;
@@ -3411,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
     };
 }
 
@@ -3462,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) {
@@ -3515,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();
@@ -3531,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;
@@ -3543,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;
@@ -3554,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 {
@@ -3587,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)
                 });
             }
@@ -3615,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
@@ -3669,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
@@ -3894,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
@@ -4007,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 = [];
@@ -4169,7 +4340,7 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
                 try {
                     if (process.platform === 'win32') {
                         if (!child.livedeskTreeStopPromise) {
-                            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTree(child);
+                            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTreeUntilStopped(child);
                         }
                         const windowsTreeStop = await child.livedeskTreeStopPromise;
                         if (windowsTreeStop?.ok === false) {
@@ -4219,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();
@@ -4278,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({
@@ -4294,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({
@@ -4319,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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.200",
+  "version": "0.1.201",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.407",
-    "@livedesk/fast-osx-arm64": "0.1.407",
-    "@livedesk/fast-osx-x64": "0.1.407",
-    "@livedesk/fast-win-x64": "0.1.407"
+    "@livedesk/fast-linux-x64": "0.1.409",
+    "@livedesk/fast-osx-arm64": "0.1.409",
+    "@livedesk/fast-osx-x64": "0.1.409",
+    "@livedesk/fast-win-x64": "0.1.409"
   },
   "publishConfig": {
     "access": "public"

package/src/runtime/agent-process-lifecycle.js

@@ -384,6 +384,55 @@ export async function drainOwnedWindowsAgentTree(child, {
     return child.livedeskWindowsDrainPromise;
 }
 
+/**
+ * Fail-closed wrapper for lifecycle replacement and terminal shutdown.
+ * A bounded drain attempt can fail because CIM/taskkill is temporarily busy;
+ * that must never let the launcher exit and orphan an owned FFmpeg descendant.
+ */
+export async function drainOwnedWindowsAgentTreeUntilStopped(child, {
+    platform = process.platform,
+    retryForeverMs = 1000,
+    waitImpl = waitMilliseconds,
+    reportTerminationFailure = message => console.error(message),
+    ...drainOptions
+} = {}) {
+    if (platform !== 'win32') return { ok: true, remaining: [] };
+    if (child?.livedeskWindowsDrainUntilStoppedPromise) {
+        return child.livedeskWindowsDrainUntilStoppedPromise;
+    }
+
+    child.livedeskWindowsDrainUntilStoppedPromise = (async () => {
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            // drainOwnedWindowsAgentTree memoizes one bounded proof attempt.
+            // Clear only that completed attempt; the immutable tracker remains
+            // attached to the exact child and is refreshed on every retry.
+            child.livedeskWindowsDrainPromise = null;
+            let result;
+            try {
+                result = await drainOwnedWindowsAgentTree(child, {
+                    platform,
+                    waitImpl,
+                    reportTerminationFailure,
+                    ...drainOptions
+                });
+            } catch (error) {
+                result = { ok: false, error, remaining: [] };
+            }
+            if (result?.ok !== false) {
+                return result;
+            }
+            reportTerminationFailure(
+                `[LiveDesk Client] Exact Windows Agent tree is not drained yet `
+                + `(attempt ${attempt}); the launcher will remain alive and retry.`
+            );
+            await waitImpl(Math.max(100, Number(retryForeverMs) || 1000));
+        }
+    })();
+    return child.livedeskWindowsDrainUntilStoppedPromise;
+}
+
 export function isOwnedUnixProcessGroupAlive(child, platform = process.platform, signalProcess = (pid, signal) => process.kill(pid, signal)) {
     const processId = Number(child?.pid || 0);
     if (platform === 'win32'
@@ -513,7 +562,7 @@ export function installAgentTerminationHandlers({
     shutdownTimeoutMs = 8000,
     platform = process.platform,
     signalProcess = (pid, signal) => process.kill(pid, signal),
-    drainWindowsTree = drainOwnedWindowsAgentTree,
+    drainWindowsTree = drainOwnedWindowsAgentTreeUntilStopped,
     windowsTerminateAttemptLimit = 3,
     windowsTerminateRetryMs = 100,
     unixTerminateRetryMs = 1000,
@@ -553,12 +602,14 @@ export function installAgentTerminationHandlers({
             let poll = null;
             let timeout = null;
             let unixRetryTimer = null;
+            let windowsRetryTimer = null;
             const finish = () => {
                 if (finished) return;
                 finished = true;
                 if (poll) clearInterval(poll);
                 if (timeout) clearTimeout(timeout);
                 if (unixRetryTimer) clearTimeout(unixRetryTimer);
+                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
                 exitProcess(exitCode);
             };
             const processId = Number(child?.pid || 0);
@@ -571,25 +622,37 @@ export function installAgentTerminationHandlers({
                 // restarts and unexpected Agent exits. The promise is stored
                 // on the child so spawnAgent cannot race ahead and launch a
                 // replacement while terminal shutdown is still draining.
-                if (!child.livedeskTreeStopPromise) {
-                    child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
-                        platform,
-                        maxAttempts: windowsTerminateAttemptLimit,
-                        retryMs: windowsTerminateRetryMs,
-                        reportTerminationFailure
-                    }));
-                }
-                child.livedeskTreeStopPromise
-                    .catch(error => ({ ok: false, error }))
-                    .then(result => {
-                        if (result?.ok === false) {
+                const drainUntilStopped = () => {
+                    if (finished) return;
+                    if (!child.livedeskTreeStopPromise) {
+                        child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
+                            platform,
+                            maxAttempts: windowsTerminateAttemptLimit,
+                            retryMs: windowsTerminateRetryMs,
+                            retryForeverMs: windowsTerminateRetryMs,
+                            reportTerminationFailure
+                        }));
+                    }
+                    child.livedeskTreeStopPromise
+                        .catch(error => ({ ok: false, error }))
+                        .then(result => {
+                            if (result?.ok !== false) {
+                                finish();
+                                return;
+                            }
                             reportTerminationFailure(
-                                `[LiveDesk Client] Terminal shutdown preserved an undrained exact Windows Agent tree: `
-                                + `${result.error?.message || 'bounded drain failed'}`
+                                `[LiveDesk Client] Terminal shutdown retained an exact Windows Agent tree: `
+                                + `${result.error?.message || 'bounded drain failed'}. Retrying before exit.`
+                            );
+                            child.livedeskTreeStopPromise = null;
+                            child.livedeskWindowsDrainPromise = null;
+                            windowsRetryTimer = setTimeout(
+                                drainUntilStopped,
+                                Math.max(100, Number(windowsTerminateRetryMs) || 100)
                             );
-                        }
-                        finish();
-                    });
+                        });
+                };
+                drainUntilStopped();
                 return;
             }
             const finishWhenTreeStops = () => {