@livedesk/client 0.1.204 → 0.1.206

package/bin/livedesk-client.js

@@ -39,6 +39,9 @@ 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;
+const FRESH_REGISTRY_TIMEOUT_MS = 4000;
+const FRESH_REGISTRY_TIMEOUT_MIN_MS = 25;
+const FRESH_REGISTRY_TIMEOUT_MAX_MS = 10000;
 // Hub-online delivery is an optimization, not a correctness dependency. A
 // browser, proxy, or suspended network can miss the wake event, so registry
 // polling must stay interactive instead of backing off to multi-minute waits.
@@ -49,6 +52,7 @@ const EXIT_INVALID_PAIR_TOKEN = 23;
 const EXIT_CLIENT_UPDATE = 42;
 const SESSION_REFRESH_SKEW_SECONDS = 60;
 const HUB_TARGET_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const HUB_TARGET_CACHE_FUTURE_SKEW_MS = 5 * 60 * 1000;
 const WINDOWS_STARTUP_SCRIPT_NAME = 'LiveDesk Desktop.vbs';
 const WINDOWS_STARTUP_LEGACY_SCRIPT_NAME = 'LiveDesk Client.vbs';
 const WINDOWS_STARTUP_LEGACY_CMD_NAME = 'LiveDesk Client.cmd';
@@ -967,7 +971,9 @@ export function normalizeCachedHubTarget(value, expectedOwnerKey, now = Date.now
         return null;
     }
     const updatedAt = Date.parse(String(cached.updatedAt || ''));
-    if (!Number.isFinite(updatedAt) || now - updatedAt > HUB_TARGET_CACHE_MAX_AGE_MS) {
+    if (!Number.isFinite(updatedAt)
+        || updatedAt > now + HUB_TARGET_CACHE_FUTURE_SKEW_MS
+        || now - updatedAt > HUB_TARGET_CACHE_MAX_AGE_MS) {
         return null;
     }
     const pair = String(cached.pair || '').trim();
@@ -1131,13 +1137,63 @@ function isTransientNetworkError(error) {
     return /fetch failed|network|dns|socket|connection|timeout|getaddrinfo/i.test(getNestedErrorMessage(error));
 }
 
-function formatDiscoveryError(error) {
-    if (isTransientNetworkError(error)) {
-        const code = getNestedErrorCode(error);
-        return `Network is not ready yet${code ? ` (${code})` : ''}. Waiting for DNS/Wi-Fi after sleep.`;
-    }
-    return error instanceof Error ? error.message : String(error);
-}
+function formatDiscoveryError(error) {
+    if (isTransientNetworkError(error)) {
+        const code = getNestedErrorCode(error);
+        return `Network is not ready yet${code ? ` (${code})` : ''}. Waiting for DNS/Wi-Fi after sleep.`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+
+function createHubDiscoveryError(code, message, cause = null) {
+    const error = new Error(message);
+    error.code = String(code || '').trim();
+    if (cause) {
+        error.cause = cause;
+    }
+    return error;
+}
+
+export function canUseCachedRelayAfterRegistryError(error) {
+    const code = getNestedErrorCode(error).toLowerCase();
+    if ([
+        'hub-registry-missing',
+        'hub-registry-expired',
+        'hub-registry-timeout',
+        'pin-not-found',
+        'pin-expired',
+        'resolver-unavailable'
+    ].includes(code)) {
+        return true;
+    }
+    // Semantic registry failures must never be reclassified as network errors
+    // merely because their message mentions a "connection token".
+    if (code.startsWith('hub-registry-')
+        || code.startsWith('pin-registry-')
+        || ['invalid-pin', 'rate-limited', 'request-too-large'].includes(code)) {
+        return false;
+    }
+    return isTransientNetworkError(error);
+}
+
+async function normalizePinResolverInvocationError(error) {
+    if (isTransientNetworkError(error)) {
+        return error;
+    }
+    const response = error?.context;
+    const status = Number(response?.status || 0);
+    let reason = '';
+    try {
+        const payload = await response?.clone?.().json?.();
+        reason = String(payload?.reason || '').trim().toLowerCase();
+    } catch {
+        // HTTP status still gives a conservative semantic classification below.
+    }
+    if (!reason && status === 404) reason = 'pin-not-found';
+    if (!reason && status === 503) reason = 'resolver-unavailable';
+    if (!reason) return error;
+    return createHubDiscoveryError(reason, reason, error);
+}
 
 async function recoverRotatedSession(supabase, previousSession) {
     for (const delayMs of [100, 250, 500]) {
@@ -2640,54 +2696,72 @@ function readRequestBody(req, maxBytes = 4096) {
     });
 }
 
-async function resolveManagerFromPin(supabase, pin, options = {}) {
+export async function resolveManagerFromPin(supabase, pin, options = {}) {
     const normalizedPin = normalizePairingPin(pin);
     if (!normalizedPin) {
         throw new Error('Enter a 6-digit LiveDesk PIN.');
     }
     const cacheOwnerKey = hubCacheOwnerForPin(normalizedPin);
-    const cachedTarget = await resolveManagerFromCachedTarget(cacheOwnerKey);
-    if (cachedTarget) {
-        console.log(`Found cached LiveDesk Hub at ${cachedTarget.manager}.`);
-        return cachedTarget;
-    }
-
-    const { data, error } = await supabase.functions.invoke('livedesk-resolve-remote-host', {
-        body: { pin: normalizedPin }
-    });
-    if (error) {
-        throw error;
-    }
-    const result = Array.isArray(data) ? data[0] : data;
-    if (!result?.ok) {
-        throw new Error(result?.reason || 'pin-not-found');
-    }
-    if (!result.pair_token) {
-        throw new Error('The PIN matched a Hub record without a private connection token.');
-    }
-    const endpointCandidates = normalizeEndpointCandidates(result);
-    if (endpointCandidates.length === 0) {
-        throw new Error('The PIN matched a Hub record without a reachable address.');
-    }
-    const target = await chooseManagerConnectionTarget(endpointCandidates, {
-        allowRelayFallback: options.allowRelayFallback === true
+    const resolved = await resolveManagerWithCachedRecovery(cacheOwnerKey, {
+        allowRelayFallback: options.allowRelayFallback === true,
+        relayEndpoint: options.relayEndpoint,
+        probeEndpoint: options.probeEndpoint,
+        resolveFreshTarget: async () => {
+            const { data, error } = await supabase.functions.invoke('livedesk-resolve-remote-host', {
+                body: { pin: normalizedPin }
+            });
+            if (error) {
+                throw await normalizePinResolverInvocationError(error);
+            }
+            const result = Array.isArray(data) ? data[0] : data;
+            if (!result?.ok) {
+                const reason = String(result?.reason || 'pin-not-found').trim().toLowerCase();
+                throw createHubDiscoveryError(reason, reason);
+            }
+            if (!result.pair_token) {
+                throw createHubDiscoveryError(
+                    'pin-registry-pair-token-missing',
+                    'The PIN matched a Hub record without a private connection token.'
+                );
+            }
+            const endpointCandidates = normalizeEndpointCandidates(result);
+            if (endpointCandidates.length === 0) {
+                throw createHubDiscoveryError(
+                    'pin-registry-endpoints-missing',
+                    'The PIN matched a Hub record without a reachable address.'
+                );
+            }
+            const target = await chooseManagerConnectionTarget(endpointCandidates, {
+                allowRelayFallback: options.allowRelayFallback === true,
+                probeEndpoint: options.probeEndpoint
+            });
+            if (!target) {
+                throw createHubDiscoveryError(
+                    'pin-direct-unreachable',
+                    `No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`
+                );
+            }
+            return {
+                manager: target.manager,
+                pair: result.pair_token,
+                hubDeviceId: String(result.node_id || '').trim(),
+                endpointCandidates,
+                directReachable: target.directReachable,
+                connectionTransport: target.connectionTransport,
+                discoverySource: 'supabase'
+            };
+        }
     });
-    if (!target) {
-        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
+    if (resolved.discoverySource === 'supabase') {
+        writeCachedHubTarget(cacheOwnerKey, resolved);
     }
-
-    const resolved = {
-        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);
+    console.log(resolved.connectionTransport === 'relay-fallback' && resolved.discoverySource === 'cache'
+        ? 'Fresh PIN registry lookup was unavailable; using the saved PIN-bound identity for the bounded encrypted relay path.'
+        : resolved.discoverySource === 'cache'
+            ? `Fresh PIN registry lookup was unavailable; using the responding saved direct Hub endpoint ${resolved.manager}.`
+            : `Found current PIN-bound LiveDesk Hub at ${resolved.manager}.`);
     return resolved;
-}
+}
 
 async function waitForManagerFromSavedPin(supabase, pin, options = {}) {
     const configuredIntervalMs = Number(options.intervalMs || 0);
@@ -2702,7 +2776,8 @@ async function waitForManagerFromSavedPin(supabase, pin, options = {}) {
         attempts += 1;
         try {
             return await resolveManagerFromPin(supabase, pin, {
-                allowRelayFallback: options.allowRelayFallback === true
+                allowRelayFallback: options.allowRelayFallback === true,
+                relayEndpoint: options.relayEndpoint
             });
         } catch (err) {
             if (shouldStop()) {
@@ -2856,9 +2931,11 @@ async function startConnectionChoiceServer(supabase, options = {}) {
         }
         dashboardState.message = 'Saved LiveDesk PIN found. Waiting for the Hub to become reachable.';
         try {
-            const resolved = await waitForManagerFromSavedPin(supabase, savedPin, {
-                shouldStop: () => completed || dashboardState.loggedOut
-            });
+            const resolved = await waitForManagerFromSavedPin(supabase, savedPin, {
+                allowRelayFallback: options.allowRelayFallback === true,
+                relayEndpoint: options.relayEndpoint,
+                shouldStop: () => completed || dashboardState.loggedOut
+            });
             if (!resolved) {
                 return;
             }
@@ -3088,7 +3165,8 @@ async function startConnectionChoiceServer(supabase, options = {}) {
                 pin = normalizePairingPin(pin);
                 try {
                     const resolved = await resolveManagerFromPin(supabase, pin, {
-                        allowRelayFallback: options.allowRelayFallback === true
+                        allowRelayFallback: options.allowRelayFallback === true,
+                        relayEndpoint: options.relayEndpoint
                     });
                     writeSavedPin(pin);
                     applyStartupPreference(pendingStartup, startupArgs);
@@ -3223,6 +3301,8 @@ async function chooseClientConnection(supabase, options = {}) {
             deviceId: options.deviceId,
             engine: options.engine,
             slot: options.slot,
+            assignedHubId: process.env.LIVEDESK_ASSIGNED_HUB_ID,
+            roleVersion: process.env.LIVEDESK_ROLE_VERSION,
             savedSession: options.savedSession,
             initialChoice: options.initialChoice,
             initialChoiceMessage: options.initialChoiceMessage,
@@ -3251,7 +3331,8 @@ async function chooseClientConnection(supabase, options = {}) {
             resolvePin: pin => {
                 if (!supabase) throw new Error('supabase-session-required');
                 return resolveManagerFromPin(supabase, pin, {
-                    allowRelayFallback: options.allowRelayFallback === true
+                    allowRelayFallback: options.allowRelayFallback === true,
+                    relayEndpoint: options.relayEndpoint
                 });
             },
             changeRole: async (role, snapshot) => {
@@ -3350,7 +3431,8 @@ async function chooseClientConnection(supabase, options = {}) {
         startupArgs: options.startupArgs,
         savedSession: options.savedSession,
         savedPin: options.savedPin,
-        allowRelayFallback: options.allowRelayFallback === true
+        allowRelayFallback: options.allowRelayFallback === true,
+        relayEndpoint: options.relayEndpoint
     });
     if (options.openBrowser !== false) {
         console.log('Opening LiveDesk connection page...');
@@ -3528,10 +3610,16 @@ export async function chooseManagerConnectionTarget(candidates, options = {}) {
 }
 
 export async function resolveManagerFromCachedTarget(ownerKey, options = {}) {
-    const cached = options.cachedTarget || readCachedHubTarget(ownerKey);
+    const cached = Object.prototype.hasOwnProperty.call(options, 'cachedTarget')
+        ? normalizeCachedHubTarget(options.cachedTarget, ownerKey, options.now)
+        : readCachedHubTarget(ownerKey);
     if (!cached) return null;
-    const manager = await chooseReachableEndpoint(cached.endpointCandidates, { requireReachable: true });
-    if (!manager) return null;
+    const target = await chooseManagerConnectionTarget(cached.endpointCandidates, {
+        allowRelayFallback: false,
+        probeEndpoint: options.probeEndpoint
+    });
+    if (!target) return null;
+    const manager = target.manager;
     const resolved = {
         manager,
         pair: cached.pair,
@@ -3540,6 +3628,8 @@ export async function resolveManagerFromCachedTarget(ownerKey, options = {}) {
             manager,
             ...cached.endpointCandidates.filter(endpoint => endpoint !== manager)
         ],
+        directReachable: target.directReachable,
+        connectionTransport: target.connectionTransport,
         discoverySource: 'cache'
     };
     if (options.persist !== false) {
@@ -3548,6 +3638,86 @@ export async function resolveManagerFromCachedTarget(ownerKey, options = {}) {
     return resolved;
 }
 
+export function resolveManagerFromCachedRelayFallback(ownerKey, options = {}) {
+    if (options.allowRelayFallback !== true) return null;
+    const cached = Object.prototype.hasOwnProperty.call(options, 'cachedTarget')
+        ? normalizeCachedHubTarget(options.cachedTarget, ownerKey, options.now)
+        : readCachedHubTarget(ownerKey);
+    if (!cached) return null;
+    const normalizedOwner = String(cached.ownerKey || '');
+    const accountIdentityComplete = normalizedOwner.startsWith('user:')
+        && normalizedOwner.length > 'user:'.length
+        && Boolean(cached.hubDeviceId);
+    // The public PIN resolver intentionally does not expose node_id. Its
+    // previous signed pair/endpoints remain bound to the exact saved six-digit
+    // PIN owner in the private, finite-lifetime cache.
+    const pinIdentityComplete = /^pin:[0-9]{6}$/.test(normalizedOwner);
+    const relayEndpoint = String(options.relayEndpoint || '').trim().replace(/^tcp:\/\//i, '');
+    if ((!accountIdentityComplete && !pinIdentityComplete) || !parseManagerEndpoint(relayEndpoint)) {
+        return null;
+    }
+    return {
+        manager: cached.endpointCandidates[0],
+        pair: cached.pair,
+        hubDeviceId: cached.hubDeviceId,
+        endpointCandidates: [...cached.endpointCandidates],
+        directReachable: false,
+        connectionTransport: 'relay-fallback',
+        discoverySource: 'cache'
+    };
+}
+
+export async function resolveManagerWithCachedRecovery(ownerKey, options = {}) {
+    const cached = Object.prototype.hasOwnProperty.call(options, 'cachedTarget')
+        ? normalizeCachedHubTarget(options.cachedTarget, ownerKey, options.now)
+        : readCachedHubTarget(ownerKey);
+    try {
+        if (typeof options.resolveFreshTarget !== 'function') {
+            throw createHubDiscoveryError('fresh-registry-resolver-required', 'Fresh Hub registry resolver is required.');
+        }
+        const configuredFreshTimeoutMs = Number(options.freshTimeoutMs);
+        const freshTimeoutMs = Number.isFinite(configuredFreshTimeoutMs)
+            ? Math.max(FRESH_REGISTRY_TIMEOUT_MIN_MS, Math.min(FRESH_REGISTRY_TIMEOUT_MAX_MS, configuredFreshTimeoutMs))
+            : FRESH_REGISTRY_TIMEOUT_MS;
+        let timeoutHandle = null;
+        const fresh = await Promise.race([
+            Promise.resolve().then(() => options.resolveFreshTarget()),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(createHubDiscoveryError(
+                    'hub-registry-timeout',
+                    `Fresh LiveDesk Hub registry lookup exceeded ${freshTimeoutMs}ms.`
+                )), freshTimeoutMs);
+            })
+        ]).finally(() => clearTimeout(timeoutHandle));
+        if (!fresh?.manager || !fresh?.pair) {
+            throw createHubDiscoveryError('fresh-registry-target-invalid', 'Fresh Hub registry target is incomplete.');
+        }
+        return {
+            ...fresh,
+            discoverySource: fresh.discoverySource || 'supabase'
+        };
+    } catch (error) {
+        if (canUseCachedRelayAfterRegistryError(error)) {
+            const direct = await resolveManagerFromCachedTarget(ownerKey, {
+                cachedTarget: cached,
+                probeEndpoint: options.probeEndpoint,
+                // A TCP listener is not pair-token authentication. Only a
+                // fresh signed registry result may extend cache trust.
+                persist: false
+            });
+            if (direct) return direct;
+            const relay = resolveManagerFromCachedRelayFallback(ownerKey, {
+                cachedTarget: cached,
+                allowRelayFallback: options.allowRelayFallback === true,
+                relayEndpoint: options.relayEndpoint,
+                now: options.now
+            });
+            if (relay) return relay;
+        }
+        throw error;
+    }
+}
+
 export function getDiscoveryRetryDelay(attempt, configuredIntervalMs = 0, random = Math.random) {
     const configured = Number(configuredIntervalMs);
     if (Number.isFinite(configured) && configured > 0) {
@@ -3599,34 +3769,50 @@ function normalizeEndpointCandidates(target) {
     return [...new Set(rawCandidates.map(value => String(value || '').trim()).filter(Boolean))];
 }
 
-async function resolveManagerFromSupabase(supabase, options = {}) {
+export async function resolveManagerFromSupabase(supabase, options = {}) {
     await refreshSessionIfNeeded(supabase);
     const { data, error } = await supabase
         .from('livedesk_remote_host_targets')
         .select('node_id, endpoint, endpoint_candidates, pair_token, active, expires_at, updated_at, manager_version')
         .eq('product_key', 'livedesk')
         .maybeSingle();
-    if (error) {
-        throw error;
-    }
-    if (!data?.active) {
-        throw new Error('No active LiveDesk Hub was found for this Google account. Start LiveDesk Hub on the screen wall computer and sign in there first.');
-    }
-    if (data.expires_at && Date.parse(data.expires_at) <= Date.now()) {
-        throw new Error('The LiveDesk Hub record is expired. Open the Hub screen again while signed in.');
-    }
-    if (!data.pair_token) {
-        throw new Error('The LiveDesk Hub record is missing its private connection token.');
-    }
-    const endpointCandidates = normalizeEndpointCandidates(data);
-    if (endpointCandidates.length === 0) {
-        throw new Error('The LiveDesk Hub record does not contain a reachable local address.');
-    }
+    if (error) {
+        throw error;
+    }
+    if (!data?.active) {
+        throw createHubDiscoveryError(
+            'hub-registry-missing',
+            'No active LiveDesk Hub was found for this Google account. Start LiveDesk Hub on the screen wall computer and sign in there first.'
+        );
+    }
+    if (data.expires_at && Date.parse(data.expires_at) <= Date.now()) {
+        throw createHubDiscoveryError(
+            'hub-registry-expired',
+            'The LiveDesk Hub record is expired. Open the Hub screen again while signed in.'
+        );
+    }
+    if (!data.pair_token) {
+        throw createHubDiscoveryError(
+            'hub-registry-pair-token-missing',
+            'The LiveDesk Hub record is missing its private connection token.'
+        );
+    }
+    const endpointCandidates = normalizeEndpointCandidates(data);
+    if (endpointCandidates.length === 0) {
+        throw createHubDiscoveryError(
+            'hub-registry-endpoints-missing',
+            'The LiveDesk Hub record does not contain a reachable local address.'
+        );
+    }
     const target = await chooseManagerConnectionTarget(endpointCandidates, {
-        allowRelayFallback: options.allowRelayFallback === true
+        allowRelayFallback: options.allowRelayFallback === true,
+        probeEndpoint: options.probeEndpoint
     });
     if (!target) {
-        throw new Error(`No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`);
+        throw createHubDiscoveryError(
+            'hub-direct-unreachable',
+            `No reachable LiveDesk Hub endpoint yet. Checked ${endpointCandidates.join(', ')}.`
+        );
     }
     return {
         manager: target.manager,
@@ -3669,6 +3855,7 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
     let attempts = 0;
     let lastMessage = '';
     let wakeListener = null;
+    let initialError = options.initialError || null;
     console.log('Waiting for a LiveDesk Hub. LiveDesk is listening for Hub-online events with adaptive registry retries as a fallback.');
     try {
         while (true) {
@@ -3677,6 +3864,11 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
             }
             attempts += 1;
             try {
+                if (initialError) {
+                    const error = initialError;
+                    initialError = null;
+                    throw error;
+                }
                 return await resolveManagerFromSupabase(supabase, {
                     allowRelayFallback: options.allowRelayFallback === true
                 });
@@ -3752,7 +3944,8 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
             choice = { type: 'google', session: savedSession };
         } else if ((parsed.startupRun || existingConnectionPage) && savedPin) {
             const resolved = await waitForManagerFromSavedPin(supabase, savedPin, {
-                allowRelayFallback
+                allowRelayFallback,
+                relayEndpoint: parsed.relay
             });
             choice = { type: 'pin', ...resolved };
         } else if (existingConnectionPage && previousChoice) {
@@ -3769,8 +3962,9 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 savedSession,
                 savedPin,
                 allowRelayFallback,
+                relayEndpoint: parsed.relay,
                 openBrowser: parsed.openBrowserOnStart
-            });
+            });
         }
         connectionPage = existingConnectionPage || choice.connectionPage || null;
         if (choice.type === 'pin') {
@@ -3792,26 +3986,39 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 : '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;
+            let initialDiscoveryError = null;
+            let resolved = null;
+            try {
+                resolved = await resolveManagerWithCachedRecovery(cacheOwnerKey, {
+                    allowRelayFallback,
+                    relayEndpoint: parsed.relay,
+                    resolveFreshTarget: async () => {
+                        // The signed registry is authoritative for Hub replacement
+                        // and pair-token rotation. Cache direct/relay recovery is
+                        // considered only after this one current lookup reports
+                        // an explicitly recoverable availability failure.
+                        try {
+                            session = await activateSupabaseSession(supabase, choice.session);
+                        } catch (error) {
+                            if (!isRefreshTokenAlreadyUsedError(error)) throw error;
+                            session = readSavedSessionFromFile() || choice.session;
+                            console.warn('[LiveDesk Client] Another auth owner rotated the refresh token. Keeping the runtime alive while the saved session catches up.');
+                        }
+                        return await resolveManagerFromSupabase(supabase, {
+                            allowRelayFallback
+                        });
+                    }
+                });
+            } catch (error) {
+                initialDiscoveryError = error;
+            }
+            discoverySource = resolved?.discoverySource || 'supabase';
+            if (resolved?.discoverySource === 'cache') {
                 writeSavedSessionToFile(session);
-                console.log(`Found cached LiveDesk Hub at ${resolved.manager}; skipped registry discovery.`);
-            } else {
-                // The browser and local runtime are separate auth owners.
-                // Activate the accepted browser session only when registry
-                // discovery is needed; a reachable account-bound cache can
-                // start the Agent without a Supabase round trip.
-                try {
-                    session = await activateSupabaseSession(supabase, choice.session);
-                } catch (error) {
-                    if (!isRefreshTokenAlreadyUsedError(error)) throw error;
-                    session = readSavedSessionFromFile() || choice.session;
-                    console.warn('[LiveDesk Client] Another auth owner rotated the refresh token. Keeping the runtime alive while the saved session catches up.');
-                }
+                console.log(resolved.connectionTransport === 'relay-fallback'
+                    ? `Fresh Hub registry lookup was unavailable; using saved account-bound Hub identity ${resolved.hubDeviceId} for the bounded encrypted relay path.`
+                    : `Fresh Hub registry lookup was unavailable; using the responding saved direct Hub endpoint ${resolved.manager}.`);
             }
             choice.session = session;
             const email = session?.user?.email ? ` as ${session.user.email}` : '';
@@ -3819,18 +4026,20 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
             if (!resolved) {
                 resolved = await waitForManagerFromSupabase(supabase, {
                     allowRelayFallback,
+                    initialError: initialDiscoveryError,
                     shouldStop: () => Boolean(roleRestartRequest?.role)
                 });
+                discoverySource = 'supabase';
             }
             if (!resolved && roleRestartRequest?.role) {
-                return {
-                    ...parsed,
-                    manager,
-                    pair,
-                    slot: normalizeSlotNumber(parsed.slot),
-                    connectionPage,
-                    forwarded,
-                    rediscoverOnDisconnect: shouldLogin,
+                return {
+                    ...parsed,
+                    manager,
+                    pair,
+                    slot: normalizeSlotNumber(parsed.slot),
+                    connectionPage,
+                    forwarded,
+                    rediscoverOnDisconnect: shouldLogin,
                     rediscoverOnInvalidPair: shouldLogin
                 };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.204",
+  "version": "0.1.206",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -40,10 +40,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.411",
-    "@livedesk/fast-osx-arm64": "0.1.411",
-    "@livedesk/fast-osx-x64": "0.1.411",
-    "@livedesk/fast-win-x64": "0.1.411"
+    "@livedesk/fast-linux-x64": "0.1.412",
+    "@livedesk/fast-osx-arm64": "0.1.412",
+    "@livedesk/fast-osx-x64": "0.1.412",
+    "@livedesk/fast-win-x64": "0.1.412"
   },
   "publishConfig": {
     "access": "public"

package/src/runtime/client-runtime-server.js

@@ -150,6 +150,11 @@ function normalizeSlotNumber(value) {
     : 0;
 }
 
+function normalizeRoleVersion(value) {
+  const roleVersion = Number(String(value ?? '').trim());
+  return Number.isInteger(roleVersion) && roleVersion >= 0 ? roleVersion : 0;
+}
+
 function readCpuTotals() {
   return os.cpus().reduce((totals, cpu) => {
     const times = Object.values(cpu.times || {}).map(Number);
@@ -655,9 +660,9 @@ export function createClientRuntimeServer(options = {}) {
     manager: '',
     pairToken: '',
     slotNumber: normalizeSlotNumber(options.slot),
-    assignedHubId: '',
+    assignedHubId: normalizeString(options.assignedHubId ?? process.env.LIVEDESK_ASSIGNED_HUB_ID, 160),
     endpointCandidates: [],
-    roleVersion: 0,
+    roleVersion: normalizeRoleVersion(options.roleVersion ?? process.env.LIVEDESK_ROLE_VERSION),
     connectedAt: '',
     message: 'Sign in with Google or enter a Hub PIN to start this Client.',
     startup: false,
@@ -788,6 +793,12 @@ export function createClientRuntimeServer(options = {}) {
           name: accountProfile.name || state.auth.name,
           avatarUrl: accountProfile.avatarUrl || state.auth.avatarUrl
         };
+        state.lastError = '';
+        if (state.message.startsWith('Client authentication needs attention:')) {
+          state.message = state.agent.state === 'running'
+            ? 'Connected to the LiveDesk Hub.'
+            : normalizeString(message, 1000) || 'Client credentials accepted. Finding the Hub.';
+        }
       }
       return;
     }
@@ -795,7 +806,9 @@ export function createClientRuntimeServer(options = {}) {
     loggedOut = false;
     state.connectedAt = new Date().toISOString();
     state.manager = normalizeString(choice?.manager, 256);
-    state.assignedHubId = normalizeString(choice?.hubDeviceId, 160);
+    if (Object.prototype.hasOwnProperty.call(choice || {}, 'hubDeviceId')) {
+      state.assignedHubId = normalizeString(choice?.hubDeviceId, 160);
+    }
     state.endpointCandidates = Array.isArray(choice?.endpointCandidates)
       ? choice.endpointCandidates.map(value => normalizeString(value, 256)).filter(Boolean)
       : [];
@@ -1337,7 +1350,9 @@ export function createClientRuntimeServer(options = {}) {
       if (patch.manager) state.manager = normalizeString(patch.manager, 256);
       if (patch.pairToken) state.pairToken = normalizeString(patch.pairToken, 256);
       if (normalizeSlotNumber(patch.slotNumber)) state.slotNumber = normalizeSlotNumber(patch.slotNumber);
-      if (patch.assignedHubId) state.assignedHubId = normalizeString(patch.assignedHubId, 160);
+      if (Object.prototype.hasOwnProperty.call(patch, 'assignedHubId')) {
+        state.assignedHubId = normalizeString(patch.assignedHubId, 160);
+      }
       if (patch.message) state.message = normalizeString(patch.message, 1000);
       if (Number.isInteger(patch.roleVersion)) state.roleVersion = patch.roleVersion;
       if (Array.isArray(patch.endpointCandidates)) state.endpointCandidates = patch.endpointCandidates;