livedesk 0.1.448 → 0.1.450

package/client/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';
@@ -67,6 +71,11 @@ const FAST_PREFLIGHT_CACHE_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'fast-preflight
 const CLIENT_SLOT_PATH = join(UNIFIED_CLIENT_STATE_DIR, 'device-slot.json');
 const CLIENT_UPDATE_STATE_PATH = process.env.LIVEDESK_CLIENT_UPDATE_STATE_PATH
     || join(UNIFIED_CLIENT_STATE_DIR, 'client-update.json');
+// Migration-only compatibility: releases before 0.1.204 could persist these
+// Client-side model options in startup/update commands. Consume them without
+// forwarding so an upgrade starts normally, but never restores that feature.
+const RETIRED_CLIENT_MODEL_SINGLE_OPTIONS = new Set(['--ai', '--no-ai', '--fake-ai']);
+const RETIRED_CLIENT_MODEL_VALUE_OPTION = '--ai-model';
 let activeAgentProcess = null;
 let roleRestartRequest = null;
 let agentRestartRequest = null;
@@ -301,8 +310,8 @@ Options:
   --version                       Show the agent version.
   --help                          Show this help.
 
-Auto uses C# RemoteFast when supported and falls back to Node for AI assist or
-when a packaged RemoteFast runtime is unavailable.
+Auto uses C# RemoteFast when supported and falls back to Node only when a
+packaged RemoteFast runtime is unavailable.
 Enable Windows auto-start from the connection page when this client signs in.
 `.trimStart());
 }
@@ -394,15 +403,30 @@ export function parseLauncherArgs(argv) {
     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;
     let command = 'connect';
-    let nodeOnlyFeature = false;
-    let fakeThumbnail = false;
+    let fakeThumbnail = false;
     let startupRun = isTruthy(process.env.LIVEDESK_ROLE_TRANSITION);
-    let openBrowserOnStart = !isTruthy(process.env.LIVEDESK_SKIP_BROWSER_OPEN);
-    let updateWaitPid = 0;
-
-    for (let index = 0; index < argv.length; index += 1) {
-        const arg = argv[index];
-        if (arg && !arg.startsWith('-')) {
+    let openBrowserOnStart = !isTruthy(process.env.LIVEDESK_SKIP_BROWSER_OPEN);
+    let updateWaitPid = 0;
+    let retiredModelOptionsDiscarded = 0;
+
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (RETIRED_CLIENT_MODEL_SINGLE_OPTIONS.has(arg)) {
+            retiredModelOptionsDiscarded += 1;
+            continue;
+        }
+        if (arg === RETIRED_CLIENT_MODEL_VALUE_OPTION) {
+            retiredModelOptionsDiscarded += 1;
+            if (index + 1 < argv.length && !String(argv[index + 1] || '').startsWith('-')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (String(arg || '').startsWith(`${RETIRED_CLIENT_MODEL_VALUE_OPTION}=`)) {
+            retiredModelOptionsDiscarded += 1;
+            continue;
+        }
+        if (arg && !arg.startsWith('-')) {
             const lowerArg = arg.toLowerCase();
             const shortcutSlot = normalizeSlotNumber(arg);
             if (lowerArg === 'connect') {
@@ -512,11 +536,8 @@ export function parseLauncherArgs(argv) {
         if (arg === '--version') {
             version = true;
         }
-        if (arg === '--ai' || arg === '--fake-ai' || arg === '--ai-model' || arg === '--no-ai') {
-            nodeOnlyFeature = true;
-        }
-        if (arg === '--fake-thumbnail') {
-            fakeThumbnail = true;
+        if (arg === '--fake-thumbnail') {
+            fakeThumbnail = true;
         }
         forwarded.push(arg);
     }
@@ -539,13 +560,13 @@ export function parseLauncherArgs(argv) {
         deviceId,
         slot,
         authPort,
-        nodeOnlyFeature,
-        fakeThumbnail,
-        startupRun,
-        openBrowserOnStart,
-        updateWaitPid
-    };
-}
+        fakeThumbnail,
+        startupRun,
+        openBrowserOnStart,
+        updateWaitPid,
+        retiredModelOptionsDiscarded
+    };
+}
 
 function normalizePort(value) {
     const port = Number(String(value || '').trim());
@@ -854,13 +875,15 @@ const CLIENT_UPDATE_SINGLE_FLAGS = new Set([
     '--no-open',
     '--exit-on-disconnect',
     '--exit-on-invalid-pair',
-    '--once'
+    '--once',
+    ...RETIRED_CLIENT_MODEL_SINGLE_OPTIONS
 ]);
 const CLIENT_UPDATE_VALUE_FLAGS = new Set([
     '--update-wait-pid',
     // Pairing credentials stay in the inherited private environment and must
     // never be copied onto a replacement process command line.
-    '--pair'
+    '--pair',
+    RETIRED_CLIENT_MODEL_VALUE_OPTION
 ]);
 
 export function buildClientUpdateRestartArgs(prepared = {}) {
@@ -874,6 +897,9 @@ export function buildClientUpdateRestartArgs(prepared = {}) {
         if (arg.startsWith('--pair=')) {
             continue;
         }
+        if (arg.startsWith(`${RETIRED_CLIENT_MODEL_VALUE_OPTION}=`)) {
+            continue;
+        }
         if (CLIENT_UPDATE_VALUE_FLAGS.has(arg)) {
             index += 1;
             continue;
@@ -945,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();
@@ -1109,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]) {
@@ -2618,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);
@@ -2680,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()) {
@@ -2834,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;
             }
@@ -3066,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);
@@ -3229,7 +3329,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) => {
@@ -3328,7 +3429,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...');
@@ -3506,10 +3608,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,
@@ -3518,6 +3626,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) {
@@ -3526,6 +3636,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) {
@@ -3577,34 +3767,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,
@@ -3647,6 +3853,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) {
@@ -3655,6 +3862,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
                 });
@@ -3730,7 +3942,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) {
@@ -3747,8 +3960,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') {
@@ -3770,26 +3984,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}` : '';
@@ -3797,18 +4024,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
                 };
             }
@@ -4233,6 +4462,18 @@ export function buildFastArgs(args, fakeThumbnail, transport = 'auto', relay = '
     const forwarded = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
+        if (RETIRED_CLIENT_MODEL_SINGLE_OPTIONS.has(arg)) {
+            continue;
+        }
+        if (arg === RETIRED_CLIENT_MODEL_VALUE_OPTION) {
+            if (index + 1 < args.length && !String(args[index + 1] || '').startsWith('-')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (String(arg || '').startsWith(`${RETIRED_CLIENT_MODEL_VALUE_OPTION}=`)) {
+            continue;
+        }
         if (arg === '--transport' || arg === '--relay') {
             index += 1;
             continue;
@@ -4241,8 +4482,8 @@ export function buildFastArgs(args, fakeThumbnail, transport = 'auto', relay = '
             forwarded.push('--fake-frame');
             continue;
         }
-        if (arg === '--tasks' || arg === '--no-tasks' || arg === '--no-ai') {
-            continue;
+        if (arg === '--tasks' || arg === '--no-tasks') {
+            continue;
         }
         forwarded.push(arg);
     }
@@ -4446,15 +4687,15 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
     });
 }
 
-function shouldUseFast(parsed) {
-    if (parsed.engine === 'node') {
-        return false;
+function shouldUseFast(parsed) {
+    if (parsed.engine === 'node') {
+        return false;
     }
     if (parsed.engine === 'fast') {
         return true;
     }
-    return !parsed.nodeOnlyFeature;
-}
+    return true;
+}
 
 function shouldTryFast(parsed, runtime) {
     if (parsed.engine === 'fast') {
@@ -4480,6 +4721,12 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
         console.warn('[LiveDesk] @livedesk/client is deprecated. Use the unified livedesk package or LiveDesk Desktop.');
     }
     const parsed = parseLauncherArgs(argv);
+    if (parsed.retiredModelOptionsDiscarded > 0) {
+        console.warn(
+            '[LiveDesk Client] Ignored retired Client model-runtime options. '
+            + 'Approved AI computer commands are handled by the Hub Codex Agent.'
+        );
+    }
     if (parsed.updateWaitPid) {
         await waitForProcessExit(parsed.updateWaitPid);
     }