@livedesk/client 0.1.214 → 0.1.216

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

@@ -1,13 +1,20 @@
 import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statfsSync, writeFileSync } from 'node:fs';
-import { dirname, join, parse, resolve } from 'node:path';
+import { accessSync, chmodSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statfsSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, join, parse, posix, resolve } from 'node:path';
 import os from 'node:os';
 import { createRuntimeManager, normalizeRuntimeAuthSession, runtimeRoleError, RuntimeState } from '../../../runtime-core/src/index.js';
 
-const DEFAULT_HOST = '127.0.0.1';
-const DEFAULT_PORT = 5179;
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 5179;
+const CLIENT_RUNTIME_BIND_TIMEOUT_MS = 10_000;
+const CLIENT_DIAGNOSTIC_COMMAND_FORCE_KILL_MS = 150;
+const CLIENT_DIAGNOSTIC_COMMAND_DRAIN_MS = 750;
+const CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS = 1_500;
+const CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS = 15_000;
+const CLIENT_DIAGNOSTIC_PROBE_NEGATIVE_TTL_MS = 60_000;
+const CLIENT_DIAGNOSTIC_HARDWARE_TTL_MS = 300_000;
 const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
 const SUPABASE_URL = process.env.LIVEDESK_SUPABASE_URL || 'https://otbyfkjxrkngvjziawki.supabase.co';
 const SUPABASE_PUBLISHABLE_KEY = process.env.LIVEDESK_SUPABASE_PUBLISHABLE_KEY || 'sb_publishable_NpUs0RDJH2YnllsqTKO6TQ_1jTdSsNQ';
@@ -165,6 +172,12 @@ function readCpuTotals() {
 }
 
 function finiteNumber(value) {
+  if (value === null
+    || value === undefined
+    || typeof value === 'boolean'
+    || (typeof value === 'string' && value.trim() === '')) {
+    return null;
+  }
   const number = Number(value);
   return Number.isFinite(number) && number >= 0 ? number : null;
 }
@@ -175,15 +188,406 @@ function percentFromRatio(value) {
   return Math.round(Math.max(0, Math.min(100, number)) * 10) / 10;
 }
 
-function captureCommand(command, args, timeout = 3500) {
-  return new Promise(resolveOutput => {
-    execFile(command, args, {
-      encoding: 'utf8',
-      maxBuffer: 512 * 1024,
-      timeout,
-      windowsHide: true
-    }, (error, stdout) => resolveOutput(error ? '' : String(stdout || '')));
+function destroyChildRedirectedIo(child) {
+  for (const stream of [child?.stdin, child?.stdout, child?.stderr]) {
+    try { stream?.destroy(); } catch { /* an exact owned stream already closed */ }
+  }
+}
+
+function sanitizeDiagnosticCommandName(value) {
+  return normalizeString(value, 200) || 'unknown-diagnostic-command';
+}
+
+function defaultDiagnosticMonotonicNow() {
+  return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
+/**
+ * Contract:
+ * - A probe is idle until an explicit diagnostic request calls read().
+ * - Every successful, unavailable, empty, or failed result is retained for at
+ *   least 15 monotonic seconds measured from refresh completion.
+ * - Concurrent readers share one refresh promise. A failed tool therefore
+ *   cannot respawn once per status heartbeat.
+ */
+export function createClientDiagnosticProbeCache(options = {}) {
+  if (typeof options.refresh !== 'function') {
+    throw new TypeError('client-diagnostic-probe-refresh-required');
+  }
+  const probeId = normalizeString(options.probeId, 80) || 'client-diagnostic-probe';
+  const monotonicNow = typeof options.monotonicNow === 'function'
+    ? options.monotonicNow
+    : defaultDiagnosticMonotonicNow;
+  const ttlMs = Math.max(
+    CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS,
+    Number(options.ttlMs) || CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS
+  );
+  const negativeTtlMs = Math.max(
+    CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS,
+    Number(options.negativeTtlMs) || CLIENT_DIAGNOSTIC_PROBE_NEGATIVE_TTL_MS
+  );
+  const fallbackValue = options.fallbackValue;
+  let initialized = false;
+  let sampledAtMonotonicMs = 0;
+  let generation = 0;
+  let refreshCount = 0;
+  let cacheHitCount = 0;
+  let sharedReadCount = 0;
+  let record = {
+    ok: false,
+    value: fallbackValue,
+    error: 'not-requested'
+  };
+  let inFlight = null;
+
+  const snapshot = () => {
+    const now = Number(monotonicNow());
+    const ageMs = initialized && Number.isFinite(now)
+      ? Math.max(0, now - sampledAtMonotonicMs)
+      : null;
+    return {
+      probeId,
+      initialized,
+      inFlight: Boolean(inFlight),
+      ok: initialized ? record.ok === true : false,
+      error: initialized ? normalizeString(record.error, 160) : 'not-requested',
+      ttlMs,
+      negativeTtlMs,
+      ageMs,
+      generation,
+      refreshCount,
+      cacheHitCount,
+      sharedReadCount
+    };
+  };
+
+  const read = () => {
+    const now = Number(monotonicNow());
+    const activeTtlMs = record.ok === true ? ttlMs : negativeTtlMs;
+    if (initialized
+        && Number.isFinite(now)
+        && Math.max(0, now - sampledAtMonotonicMs) < activeTtlMs) {
+      cacheHitCount += 1;
+      return Promise.resolve({
+        ...record,
+        cached: true,
+        shared: false,
+        generation
+      });
+    }
+    if (inFlight) {
+      sharedReadCount += 1;
+      return inFlight.then(result => ({ ...result, shared: true }));
+    }
+
+    inFlight = (async () => {
+      let next;
+      try {
+        const candidate = await options.refresh();
+        next = candidate && typeof candidate === 'object'
+          ? {
+              ok: candidate.ok === true,
+              value: candidate.value === undefined ? fallbackValue : candidate.value,
+              error: candidate.ok === true ? '' : normalizeString(candidate.error, 160) || 'probe-unavailable'
+            }
+          : {
+              ok: false,
+              value: fallbackValue,
+              error: 'probe-invalid-result'
+            };
+      } catch (error) {
+        next = {
+          ok: false,
+          value: fallbackValue,
+          error: normalizeString(error?.message || error, 160) || 'probe-failed'
+        };
+      }
+      record = next;
+      initialized = true;
+      generation += 1;
+      refreshCount += 1;
+      sampledAtMonotonicMs = Number(monotonicNow());
+      return {
+        ...record,
+        cached: false,
+        shared: false,
+        generation
+      };
+    })().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  };
+
+  return {
+    read,
+    getSnapshot: snapshot
+  };
+}
+
+function isExecutablePath(path) {
+  try {
+    accessSync(path, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveNvidiaSmiCommand(options = {}) {
+  const platform = normalizeString(options.platform || process.platform, 20);
+  const executablePath = normalizeString(
+    options.explicitPath ?? process.env.LIVEDESK_NVIDIA_SMI_PATH,
+    1000
+  );
+  const executableCheck = typeof options.isExecutable === 'function'
+    ? options.isExecutable
+    : isExecutablePath;
+  if (platform === 'win32') {
+    return executablePath || 'nvidia-smi.exe';
+  }
+
+  const pathValue = String(options.pathValue ?? process.env.PATH ?? '');
+  const pathDelimiter = normalizeString(options.pathDelimiter, 4) || delimiter;
+  const joinExecutablePath = platform === 'win32' ? join : posix.join;
+  const candidates = [
+    executablePath,
+    ...pathValue
+      .split(pathDelimiter)
+      .map(directory => directory.trim())
+      .filter(Boolean)
+      .map(directory => joinExecutablePath(directory, 'nvidia-smi')),
+    ...(platform === 'linux' ? ['/usr/bin/nvidia-smi', '/usr/local/bin/nvidia-smi'] : [])
+  ].filter(Boolean);
+  for (const candidate of [...new Set(candidates)]) {
+    try {
+      if (executableCheck(candidate) === true) return candidate;
+    } catch {
+      // An unreadable PATH entry is negative probe evidence.
+    }
+  }
+  return '';
+}
+
+/**
+ * Contract:
+ * - Owns only ChildProcess objects spawned through this instance.
+ * - Identity is ownerId + commandId + the immutable ChildProcess handle; a PID
+ *   is diagnostic evidence and is never rediscovered to authorize termination.
+ * - A command deadline and owner close both abort, terminate, drain redirected
+ *   stdio, and wait for the exact child's terminal `close` event.
+ * - Concurrent identical probes share the same command/output/terminal owner.
+ * - Output, close, and active-ledger retention are bounded independently so an
+ *   inherited pipe can never keep the Client event loop alive without evidence.
+ */
+export function createClientDiagnosticCommandOwner(options = {}) {
+  const execFileImpl = typeof options.execFileImpl === 'function' ? options.execFileImpl : execFile;
+  const ownerId = normalizeString(options.ownerId, 160)
+    || `client-diagnostics-${process.pid}-${randomBytes(8).toString('hex')}`;
+  const forceKillDelayMs = Math.max(
+    10,
+    Number(options.forceKillDelayMs) || CLIENT_DIAGNOSTIC_COMMAND_FORCE_KILL_MS
+  );
+  const commandDrainMs = Math.max(
+    forceKillDelayMs + 10,
+    Number(options.commandDrainMs) || CLIENT_DIAGNOSTIC_COMMAND_DRAIN_MS
+  );
+  const active = new Map();
+  const activeByKey = new Map();
+  let commandSequence = 0;
+  let spawnedCount = 0;
+  let joinedCount = 0;
+  let timedOutCount = 0;
+  let sharedRequestCount = 0;
+  let closePromise = null;
+  let closed = false;
+
+  const snapshotRecord = record => ({
+    ownerId,
+    commandId: record.commandId,
+    pid: record.pid,
+    command: record.command,
+    startedAt: record.startedAt,
+    terminationReason: record.terminationReason || ''
+  });
+
+  const getSnapshot = () => ({
+    ownerId,
+    closed,
+    spawnedCount,
+    joinedCount,
+    timedOutCount,
+    sharedRequestCount,
+    activeCount: active.size,
+    redirectedStreamCount: [...active.values()].reduce(
+      (count, record) => count + [record.child?.stdin, record.child?.stdout, record.child?.stderr]
+        .filter(stream => stream && !stream.destroyed).length,
+      0
+    ),
+    active: [...active.values()].map(snapshotRecord)
   });
+
+  const settleOutput = (record, output = '') => {
+    if (record.outputSettled) return;
+    record.outputSettled = true;
+    record.resolveOutput(String(output || ''));
+  };
+
+  const markTerminal = record => {
+    if (record.terminal) return;
+    record.terminal = true;
+    clearTimeout(record.commandTimer);
+    clearTimeout(record.forceKillTimer);
+    clearTimeout(record.outputDrainTimer);
+    destroyChildRedirectedIo(record.child);
+    active.delete(record.commandId);
+    if (activeByKey.get(record.commandKey) === record) {
+      activeByKey.delete(record.commandKey);
+    }
+    joinedCount += 1;
+    settleOutput(record, record.error ? '' : record.stdout);
+    record.resolveTerminal();
+  };
+
+  const terminateOwnedRecord = (record, reason) => {
+    if (!record || record.terminal || record.terminationRequested) return;
+    record.terminationRequested = true;
+    record.terminationReason = normalizeString(reason, 80) || 'diagnostic-owner-close';
+    if (record.terminationReason === 'command-timeout') timedOutCount += 1;
+    clearTimeout(record.commandTimer);
+    try { record.abortController.abort(new Error(record.terminationReason)); } catch { /* already aborted */ }
+    try { record.child?.kill('SIGTERM'); } catch { /* exact child already exited */ }
+    record.forceKillTimer = setTimeout(() => {
+      if (record.terminal) return;
+      try { record.child?.kill('SIGKILL'); } catch { /* exact child already exited */ }
+      // An inherited writer can keep execFile's callback pending even after the
+      // root exits. Closing our exact pipe ends the Client-side handle owner.
+      destroyChildRedirectedIo(record.child);
+    }, forceKillDelayMs);
+    record.forceKillTimer.unref?.();
+    record.outputDrainTimer = setTimeout(() => {
+      if (record.terminal) return;
+      settleOutput(record, '');
+      destroyChildRedirectedIo(record.child);
+      record.child?.unref?.();
+    }, commandDrainMs);
+    record.outputDrainTimer.unref?.();
+  };
+
+  const capture = (command, args = [], timeout = 3500) => {
+    if (closed) return Promise.resolve('');
+    const normalizedArgs = Array.isArray(args) ? args : [];
+    const commandKey = JSON.stringify([
+      String(command || ''),
+      ...normalizedArgs.map(value => String(value ?? ''))
+    ]);
+    const sharedRecord = activeByKey.get(commandKey);
+    if (sharedRecord) {
+      sharedRequestCount += 1;
+      return sharedRecord.outputPromise;
+    }
+    const commandId = `${ownerId}:${++commandSequence}`;
+    const abortController = new AbortController();
+    let resolveOutput;
+    let resolveTerminal;
+    const outputPromise = new Promise(resolve => { resolveOutput = resolve; });
+    const terminalPromise = new Promise(resolve => { resolveTerminal = resolve; });
+    const record = {
+      ownerId,
+      commandId,
+      commandKey,
+      command: sanitizeDiagnosticCommandName(command),
+      pid: 0,
+      startedAt: new Date().toISOString(),
+      child: null,
+      abortController,
+      resolveOutput,
+      resolveTerminal,
+      outputPromise,
+      terminalPromise,
+      stdout: '',
+      error: null,
+      outputSettled: false,
+      terminal: false,
+      terminationRequested: false,
+      terminationReason: '',
+      commandTimer: null,
+      forceKillTimer: null,
+      outputDrainTimer: null
+    };
+    active.set(commandId, record);
+    activeByKey.set(commandKey, record);
+
+    try {
+      record.child = execFileImpl(command, normalizedArgs, {
+        encoding: 'utf8',
+        maxBuffer: 512 * 1024,
+        windowsHide: true,
+        signal: abortController.signal
+      }, (error, stdout) => {
+        record.error = error || null;
+        record.stdout = error ? '' : String(stdout || '');
+        settleOutput(record, record.stdout);
+      });
+      record.pid = Number(record.child?.pid || 0);
+      spawnedCount += 1;
+      record.child.once('close', () => markTerminal(record));
+      record.child.once('error', error => {
+        record.error = record.error || error;
+      });
+      const commandTimeoutMs = Math.max(10, Number(timeout) || 3500);
+      record.commandTimer = setTimeout(
+        () => terminateOwnedRecord(record, 'command-timeout'),
+        commandTimeoutMs
+      );
+      record.commandTimer.unref?.();
+    } catch (error) {
+      record.error = error;
+      settleOutput(record, '');
+      markTerminal(record);
+    }
+
+    return outputPromise;
+  };
+
+  const close = (timeoutMs = CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS) => {
+    if (closePromise) return closePromise;
+    closed = true;
+    const boundedTimeoutMs = Math.max(100, Number(timeoutMs) || CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS);
+    closePromise = (async () => {
+      const records = [...active.values()];
+      for (const record of records) terminateOwnedRecord(record, 'diagnostic-owner-close');
+      if (records.length > 0) {
+        let deadlineTimer;
+        await Promise.race([
+          Promise.allSettled(records.map(record => record.terminalPromise)),
+          new Promise(resolve => {
+            deadlineTimer = setTimeout(resolve, boundedTimeoutMs);
+          })
+        ]);
+        clearTimeout(deadlineTimer);
+      }
+      for (const record of active.values()) {
+        settleOutput(record, '');
+        try { record.child?.kill('SIGKILL'); } catch { /* exact child already exited */ }
+        destroyChildRedirectedIo(record.child);
+        record.child?.unref?.();
+      }
+      const snapshot = getSnapshot();
+      return {
+        ok: snapshot.activeCount === 0 && snapshot.redirectedStreamCount === 0,
+        ...snapshot
+      };
+    })();
+    return closePromise;
+  };
+
+  return {
+    ownerId,
+    capture,
+    close,
+    getSnapshot
+  };
 }
 
 export function parseNvidiaSmiOutput(output) {
@@ -274,17 +678,30 @@ function activeNetworkInterfaces() {
   return interfaces;
 }
 
-async function readNetworkTotals() {
-  if (process.platform === 'win32') {
-    return parseWindowsNetworkOutput(await captureCommand('netstat.exe', ['-e'], 2500));
+async function readNetworkTotalsProbe(commandOwner, platform = process.platform) {
+  if (platform === 'win32') {
+    const output = await commandOwner.capture('netstat.exe', ['-e'], 2500);
+    return String(output || '').trim()
+      ? { ok: true, value: parseWindowsNetworkOutput(output) }
+      : { ok: false, value: { receivedBytes: 0, sentBytes: 0 }, error: 'netstat-unavailable' };
   }
-  if (process.platform === 'darwin') {
-    return parseMacNetworkOutput(await captureCommand('netstat', ['-ibn'], 2500));
+  if (platform === 'darwin') {
+    const output = await commandOwner.capture('netstat', ['-ibn'], 2500);
+    return String(output || '').trim()
+      ? { ok: true, value: parseMacNetworkOutput(output) }
+      : { ok: false, value: { receivedBytes: 0, sentBytes: 0 }, error: 'netstat-unavailable' };
   }
   try {
-    return parseLinuxNetworkOutput(readFileSync('/proc/net/dev', 'utf8'));
+    return {
+      ok: true,
+      value: parseLinuxNetworkOutput(readFileSync('/proc/net/dev', 'utf8'))
+    };
   } catch {
-    return { receivedBytes: 0, sentBytes: 0 };
+    return {
+      ok: false,
+      value: { receivedBytes: 0, sentBytes: 0 },
+      error: 'network-counters-unavailable'
+    };
   }
 }
 
@@ -300,6 +717,53 @@ function normalizeGpu(value) {
   };
 }
 
+export function normalizeGpuIdentityName(value) {
+  return normalizeString(value, 160)
+    .normalize('NFKC')
+    .replace(/\((?:r|tm)\)/giu, '')
+    .replace(/[®™]/gu, '')
+    .toLocaleLowerCase('en-US')
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim();
+}
+
+export function mergeGpuSnapshots(platformGpus = [], telemetryGpus = []) {
+  const merged = [];
+  const indexesByIdentity = new Map();
+  for (const value of Array.isArray(platformGpus) ? platformGpus : []) {
+    const gpu = normalizeGpu(value);
+    const identity = normalizeGpuIdentityName(gpu?.name);
+    if (!gpu || !identity) continue;
+    const index = merged.length;
+    merged.push(gpu);
+    const indexes = indexesByIdentity.get(identity) || [];
+    indexes.push(index);
+    indexesByIdentity.set(identity, indexes);
+  }
+
+  const matchedIndexes = new Set();
+  for (const value of Array.isArray(telemetryGpus) ? telemetryGpus : []) {
+    const gpu = normalizeGpu(value);
+    const identity = normalizeGpuIdentityName(gpu?.name);
+    if (!gpu || !identity) continue;
+    const existingIndex = (indexesByIdentity.get(identity) || [])
+      .find(index => !matchedIndexes.has(index));
+    if (existingIndex === undefined) {
+      merged.push(gpu);
+      continue;
+    }
+    matchedIndexes.add(existingIndex);
+    const existing = merged[existingIndex];
+    merged[existingIndex] = {
+      ...existing,
+      usagePercent: gpu.usagePercent ?? existing.usagePercent,
+      memoryTotalBytes: gpu.memoryTotalBytes ?? existing.memoryTotalBytes,
+      memoryUsedBytes: gpu.memoryUsedBytes ?? existing.memoryUsedBytes
+    };
+  }
+  return merged;
+}
+
 function normalizeDisk(value) {
   if (!value || typeof value !== 'object') return null;
   const mount = normalizeString(value.mount, 80);
@@ -391,7 +855,7 @@ export function readMacDiskSnapshots(options = {}) {
   return disks;
 }
 
-async function readWindowsHardwareSnapshot() {
+async function readWindowsHardwareSnapshot(commandOwner) {
   const script = [
     '$ErrorActionPreference="Stop"',
     '$OutputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new($false)',
@@ -400,7 +864,7 @@ async function readWindowsHardwareSnapshot() {
     '$disks=@(Get-CimInstance Win32_LogicalDisk -Filter "DriveType=3" | Where-Object { $physicalDriveIds -contains $_.DeviceID } | Sort-Object DeviceID | ForEach-Object { [pscustomobject]@{ name=[string]$_.VolumeName; mount=[string]$_.DeviceID; totalBytes=[double]$_.Size; freeBytes=[double]$_.FreeSpace } })',
     '[pscustomobject]@{ gpus=$gpus; disks=$disks } | ConvertTo-Json -Compress -Depth 5'
   ].join('; ');
-  return parseWindowsHardwareOutput(await captureCommand('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], 5000));
+  return parseWindowsHardwareOutput(await commandOwner.capture('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], 5000));
 }
 
 function parseMacGpuOutput(output) {
@@ -414,34 +878,45 @@ function parseMacGpuOutput(output) {
   }
 }
 
-async function collectHardwareSnapshot() {
-  const nvidiaPromise = collectNvidiaGpuSnapshot();
-
-  let platformSnapshot = { gpus: [], disks: [] };
-  if (process.platform === 'win32') {
-    platformSnapshot = await readWindowsHardwareSnapshot();
-  } else {
-    const disk = process.platform === 'darwin' ? null : readRootDiskSnapshot();
-    const gpus = process.platform === 'darwin'
-      ? parseMacGpuOutput(await captureCommand('system_profiler', ['SPDisplaysDataType', '-json'], 5000))
-      : [];
-    platformSnapshot = { gpus, disks: process.platform === 'darwin' ? readMacDiskSnapshots() : disk ? [disk] : [] };
+async function collectPlatformHardwareProbe(commandOwner, platform = process.platform) {
+  if (platform === 'win32') {
+    const snapshot = await readWindowsHardwareSnapshot(commandOwner);
+    return snapshot.gpus.length > 0 || snapshot.disks.length > 0
+      ? { ok: true, value: snapshot }
+      : { ok: false, value: snapshot, error: 'windows-hardware-unavailable' };
   }
-
-  const nvidiaGpus = await nvidiaPromise;
+  if (platform === 'darwin') {
+    const output = await commandOwner.capture('system_profiler', ['SPDisplaysDataType', '-json'], 5000);
+    const snapshot = {
+      gpus: parseMacGpuOutput(output),
+      disks: readMacDiskSnapshots()
+    };
+    return String(output || '').trim()
+      ? { ok: true, value: snapshot }
+      : { ok: false, value: snapshot, error: 'system-profiler-unavailable' };
+  }
+  const disk = readRootDiskSnapshot();
   return {
-    gpus: nvidiaGpus.length > 0 ? nvidiaGpus : platformSnapshot.gpus,
-    disks: platformSnapshot.disks,
-    collectedAt: new Date().toISOString()
+    ok: Boolean(disk),
+    value: { gpus: [], disks: disk ? [disk] : [] },
+    error: disk ? '' : 'root-disk-unavailable'
   };
 }
 
-async function collectNvidiaGpuSnapshot() {
-  return parseNvidiaSmiOutput(await captureCommand(
-    process.platform === 'win32' ? 'nvidia-smi.exe' : 'nvidia-smi',
+async function collectNvidiaGpuProbe(commandOwner, platform = process.platform) {
+  const command = resolveNvidiaSmiCommand({ platform });
+  if (!command) {
+    return { ok: false, value: [], error: 'nvidia-smi-unavailable' };
+  }
+  const output = await commandOwner.capture(
+    command,
     ['--query-gpu=name,utilization.gpu,memory.total,memory.used', '--format=csv,noheader,nounits'],
     3000
-  ));
+  );
+  const gpus = parseNvidiaSmiOutput(output);
+  return gpus.length > 0
+    ? { ok: true, value: gpus }
+    : { ok: false, value: [], error: 'nvidia-smi-empty-or-failed' };
 }
 
 function normalizeOrigin(value) {
@@ -641,19 +1116,76 @@ export function createClientRuntimeServer(options = {}) {
   const deviceId = normalizeString(options.deviceId || process.env.LIVEDESK_DEVICE_ID, 160);
   const deviceName = normalizeString(options.deviceName || os.hostname(), 160) || os.hostname();
   const appVersion = normalizeString(options.appVersion || process.env.LIVEDESK_NPM_LAUNCHER_VERSION, 80) || 'dev';
-  const savedSession = options.savedSession?.refresh_token ? options.savedSession : readSavedSession();
+  const savedSession = options.loadSavedSession === false
+    ? null
+    : options.savedSession?.refresh_token
+      ? options.savedSession
+      : readSavedSession();
   const savedSessionPersisted = Boolean(savedSession?.refresh_token);
   const savedAccountProfile = readClientAccountProfile(savedSession);
+  const diagnosticPlatform = normalizeString(options.diagnosticPlatform || process.platform, 20);
+  const diagnosticMonotonicNow = typeof options.diagnosticMonotonicNow === 'function'
+    ? options.diagnosticMonotonicNow
+    : defaultDiagnosticMonotonicNow;
+  const diagnosticProbeTtlMs = Math.max(
+    CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS,
+    Number(options.diagnosticProbeTtlMs) || CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS
+  );
   let previousCpuTotals = readCpuTotals();
-  let hardwareSnapshot = { gpus: [], disks: [], collectedAt: '', collecting: true };
+  let hardwareSnapshot = {
+    gpus: [],
+    disks: [],
+    collectedAt: '',
+    collecting: false,
+    lastError: options.diagnosticsEnabled === false ? 'diagnostics-disabled' : 'not-requested'
+  };
   let networkSnapshot = { interfaces: activeNetworkInterfaces(), receivedBytes: 0, sentBytes: 0, receiveBytesPerSecond: 0, sendBytesPerSecond: 0, sampledAt: '' };
   let previousNetworkTotals = null;
-  let hardwareRefreshInFlight = false;
-  let gpuRefreshInFlight = false;
-  let networkRefreshInFlight = false;
-  let hardwareRefreshTimer;
-  let gpuRefreshTimer;
-  let networkRefreshTimer;
+  let lastDiagnosticRequestAt = '';
+  let lastDiagnosticCompletedAt = '';
+  let diagnosticRefreshInFlight = null;
+  let closed = false;
+  let runtimeClosePromise = null;
+  const diagnosticCommandOwner = options.diagnosticCommandOwner
+    || createClientDiagnosticCommandOwner();
+  if (typeof diagnosticCommandOwner.capture !== 'function'
+      || typeof diagnosticCommandOwner.close !== 'function'
+      || typeof diagnosticCommandOwner.getSnapshot !== 'function') {
+    throw new TypeError('invalid-client-diagnostic-command-owner');
+  }
+  const diagnosticTasks = new Set();
+  const trackDiagnosticTask = operation => {
+    if (closed) return Promise.resolve();
+    const task = Promise.resolve()
+      .then(operation)
+      .finally(() => diagnosticTasks.delete(task));
+    diagnosticTasks.add(task);
+    return task;
+  };
+  const hardwareProbeCache = createClientDiagnosticProbeCache({
+    probeId: 'platform-hardware',
+    ttlMs: Math.max(CLIENT_DIAGNOSTIC_HARDWARE_TTL_MS, diagnosticProbeTtlMs),
+    negativeTtlMs: CLIENT_DIAGNOSTIC_PROBE_NEGATIVE_TTL_MS,
+    monotonicNow: diagnosticMonotonicNow,
+    fallbackValue: { gpus: [], disks: [] },
+    refresh: () => collectPlatformHardwareProbe(diagnosticCommandOwner, diagnosticPlatform)
+  });
+  const nvidiaProbeCache = createClientDiagnosticProbeCache({
+    probeId: 'nvidia-gpu',
+    ttlMs: diagnosticProbeTtlMs,
+    negativeTtlMs: CLIENT_DIAGNOSTIC_PROBE_NEGATIVE_TTL_MS,
+    monotonicNow: diagnosticMonotonicNow,
+    fallbackValue: [],
+    refresh: () => collectNvidiaGpuProbe(diagnosticCommandOwner, diagnosticPlatform)
+  });
+  const networkProbeCache = createClientDiagnosticProbeCache({
+    probeId: 'network-totals',
+    ttlMs: diagnosticProbeTtlMs,
+    negativeTtlMs: CLIENT_DIAGNOSTIC_PROBE_NEGATIVE_TTL_MS,
+    monotonicNow: diagnosticMonotonicNow,
+    fallbackValue: { receivedBytes: 0, sentBytes: 0 },
+    refresh: () => readNetworkTotalsProbe(diagnosticCommandOwner, diagnosticPlatform)
+  });
   const csrfToken = randomBytes(32).toString('hex');
   const state = {
     route: '/computer',
@@ -703,72 +1235,81 @@ export function createClientRuntimeServer(options = {}) {
   });
   runtime.emit('runtime.waiting-auth', { role: 'client' });
 
-  const refreshHardwareSnapshot = async () => {
-    if (hardwareRefreshInFlight) return;
-    hardwareRefreshInFlight = true;
+  const requestDiagnosticRefresh = () => {
+    if (closed || options.diagnosticsEnabled === false) return Promise.resolve();
+    if (diagnosticRefreshInFlight) return diagnosticRefreshInFlight;
+    lastDiagnosticRequestAt = new Date().toISOString();
     hardwareSnapshot = { ...hardwareSnapshot, collecting: true };
-    try {
-      hardwareSnapshot = { ...await collectHardwareSnapshot(), collecting: false };
-      runtime.emit('client.system.hardware', {
-        gpuCount: hardwareSnapshot.gpus.length,
-        diskCount: hardwareSnapshot.disks.length
-      });
-    } catch (error) {
+    diagnosticRefreshInFlight = trackDiagnosticTask(async () => {
+      const [platformResult, nvidiaResult, networkResult] = await Promise.all([
+        hardwareProbeCache.read(),
+        nvidiaProbeCache.read(),
+        networkProbeCache.read()
+      ]);
+      if (closed) return;
+
+      const platformSnapshot = platformResult.value && typeof platformResult.value === 'object'
+        ? platformResult.value
+        : { gpus: [], disks: [] };
+      const nvidiaGpus = Array.isArray(nvidiaResult.value) ? nvidiaResult.value : [];
+      const errors = [platformResult, nvidiaResult, networkResult]
+        .filter(result => result.ok !== true && result.error)
+        .map(result => normalizeString(result.error, 160));
       hardwareSnapshot = {
-        ...hardwareSnapshot,
+        // Preserve the platform adapter inventory on hybrid-GPU computers. The
+        // NVIDIA sampler enriches its matching adapter instead of replacing
+        // every non-NVIDIA display adapter with the telemetry subset.
+        gpus: mergeGpuSnapshots(platformSnapshot.gpus, nvidiaGpus),
+        disks: Array.isArray(platformSnapshot.disks) ? platformSnapshot.disks : [],
+        collectedAt: new Date().toISOString(),
         collecting: false,
-        lastError: normalizeString(error?.message || error, 160)
+        lastError: errors.join(', ')
       };
-    } finally {
-      hardwareRefreshInFlight = false;
-    }
-  };
 
-  const refreshGpuSnapshot = async () => {
-    if (gpuRefreshInFlight) return;
-    gpuRefreshInFlight = true;
-    try {
-      const gpus = await collectNvidiaGpuSnapshot();
-      if (gpus.length > 0) {
-        hardwareSnapshot = { ...hardwareSnapshot, gpus, collectedAt: new Date().toISOString() };
+      const totals = networkResult.value && typeof networkResult.value === 'object'
+        ? networkResult.value
+        : { receivedBytes: 0, sentBytes: 0 };
+      if (networkResult.cached !== true || !networkSnapshot.sampledAt) {
+        const sampledAtMs = Date.now();
+        const elapsedSeconds = previousNetworkTotals
+          ? Math.max(0.25, (sampledAtMs - previousNetworkTotals.sampledAtMs) / 1000)
+          : 0;
+        networkSnapshot = {
+          interfaces: activeNetworkInterfaces(),
+          receivedBytes: totals.receivedBytes,
+          sentBytes: totals.sentBytes,
+          receiveBytesPerSecond: elapsedSeconds > 0
+            ? Math.max(0, (totals.receivedBytes - previousNetworkTotals.receivedBytes) / elapsedSeconds)
+            : 0,
+          sendBytesPerSecond: elapsedSeconds > 0
+            ? Math.max(0, (totals.sentBytes - previousNetworkTotals.sentBytes) / elapsedSeconds)
+            : 0,
+          sampledAt: new Date(sampledAtMs).toISOString()
+        };
+        previousNetworkTotals = { ...totals, sampledAtMs };
       }
-    } finally {
-      gpuRefreshInFlight = false;
-    }
-  };
-
-  const refreshNetworkSnapshot = async () => {
-    if (networkRefreshInFlight) return;
-    networkRefreshInFlight = true;
-    try {
-      const totals = await readNetworkTotals();
-      const sampledAtMs = Date.now();
-      const elapsedSeconds = previousNetworkTotals
-        ? Math.max(0.25, (sampledAtMs - previousNetworkTotals.sampledAtMs) / 1000)
-        : 0;
-      networkSnapshot = {
-        interfaces: activeNetworkInterfaces(),
-        receivedBytes: totals.receivedBytes,
-        sentBytes: totals.sentBytes,
-        receiveBytesPerSecond: elapsedSeconds > 0 ? Math.max(0, (totals.receivedBytes - previousNetworkTotals.receivedBytes) / elapsedSeconds) : 0,
-        sendBytesPerSecond: elapsedSeconds > 0 ? Math.max(0, (totals.sentBytes - previousNetworkTotals.sentBytes) / elapsedSeconds) : 0,
-        sampledAt: new Date(sampledAtMs).toISOString()
-      };
-      previousNetworkTotals = { ...totals, sampledAtMs };
-    } finally {
-      networkRefreshInFlight = false;
-    }
+      lastDiagnosticCompletedAt = new Date().toISOString();
+      runtime.emit('client.system.diagnostics', {
+        gpuCount: hardwareSnapshot.gpus.length,
+        diskCount: hardwareSnapshot.disks.length,
+        platformHardwareGeneration: platformResult.generation,
+        nvidiaGeneration: nvidiaResult.generation,
+        networkGeneration: networkResult.generation
+      });
+    });
+    void diagnosticRefreshInFlight.finally(() => {
+      diagnosticRefreshInFlight = null;
+      if (!closed && hardwareSnapshot.collecting) {
+        hardwareSnapshot = {
+          ...hardwareSnapshot,
+          collecting: false,
+          lastError: hardwareSnapshot.lastError || 'diagnostic-refresh-failed'
+        };
+      }
+    });
+    return diagnosticRefreshInFlight;
   };
 
-  void refreshHardwareSnapshot();
-  void refreshNetworkSnapshot();
-  hardwareRefreshTimer = setInterval(() => { void refreshHardwareSnapshot(); }, 60_000);
-  hardwareRefreshTimer.unref?.();
-  gpuRefreshTimer = setInterval(() => { void refreshGpuSnapshot(); }, 2500);
-  gpuRefreshTimer.unref?.();
-  networkRefreshTimer = setInterval(() => { void refreshNetworkSnapshot(); }, 2000);
-  networkRefreshTimer.unref?.();
-
   const recordAuthAttempt = (result, error = '') => {
     const message = normalizeString(error, 240);
     state.auth = { ...state.auth, lastAttemptAt: new Date().toISOString(), lastResult: normalizeString(result, 80), lastError: message };
@@ -820,6 +1361,7 @@ export function createClientRuntimeServer(options = {}) {
       lastAttemptAt: state.connectedAt,
       lastResult: 'accepted',
       lastError: '',
+      persisted: Boolean(choice?.session?.refresh_token) || state.auth.persisted,
       email: accountProfile.email || state.auth.email,
       name: accountProfile.name || state.auth.name,
       avatarUrl: accountProfile.avatarUrl || state.auth.avatarUrl
@@ -885,7 +1427,17 @@ export function createClientRuntimeServer(options = {}) {
         disks: hardwareSnapshot.disks,
         network: networkSnapshot,
         hardwareCollectedAt: hardwareSnapshot.collectedAt,
-        hardwareCollecting: hardwareSnapshot.collecting
+        hardwareCollecting: hardwareSnapshot.collecting,
+        hardwareLastError: hardwareSnapshot.lastError || '',
+        diagnosticProbes: {
+          requestDriven: true,
+          minimumTtlMs: CLIENT_DIAGNOSTIC_PROBE_MIN_TTL_MS,
+          requestedAt: lastDiagnosticRequestAt,
+          completedAt: lastDiagnosticCompletedAt,
+          platformHardware: hardwareProbeCache.getSnapshot(),
+          nvidiaGpu: nvidiaProbeCache.getSnapshot(),
+          networkTotals: networkProbeCache.getSnapshot()
+        }
       },
       permissions: {
         screenCapture: state.agent.state === 'running',
@@ -954,11 +1506,16 @@ export function createClientRuntimeServer(options = {}) {
       respondJson(200, { ok: true, product: 'LiveDesk', role: 'client', timestamp: new Date().toISOString() });
       return;
     }
-    if (pathname === '/api/runtime' || pathname === '/api/runtime/status' || pathname === '/api/client/status' || pathname === '/api/client/computer' || pathname === '/api/client/system' || pathname === '/api/client/permissions' || pathname === '/api/client/diagnostics') {
+    if (pathname === '/api/client/diagnostics') {
+      await requestDiagnosticRefresh();
       respondJson(200, getState());
-      return;
-    }
-    if (pathname === '/api/runtime/events') {
+      return;
+    }
+    if (pathname === '/api/runtime' || pathname === '/api/runtime/status' || pathname === '/api/client/status' || pathname === '/api/client/computer' || pathname === '/api/client/system' || pathname === '/api/client/permissions') {
+      respondJson(200, getState());
+      return;
+    }
+    if (pathname === '/api/runtime/events') {
       respondJson(200, { ok: true, events: runtime.getEvents() });
       return;
     }
@@ -1295,14 +1852,33 @@ export function createClientRuntimeServer(options = {}) {
 
   const start = () => new Promise((resolveStart, rejectStart) => {
     if (process.env.LIVEDESK_DESKTOP_HOST === '1') clearSavedSession();
+    let settled = false;
     server = createServer((req, res) => {
       void handleRequest(req, res).catch(error => {
         if (!res.headersSent) sendJson(res, 500, { ok: false, error: normalizeString(error?.message || error) }, req.headers.origin, port, trustedWebOrigins);
         else res.end();
-      });
-    });
-    server.once('error', rejectStart);
+      });
+    });
+    const bindTimer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { server.close(); } catch { /* bind never completed */ }
+      rejectStart(new Error(`client-runtime-bind-timeout:${host}:${port}`));
+    }, CLIENT_RUNTIME_BIND_TIMEOUT_MS);
+    bindTimer.unref?.();
+    server.once('error', error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(bindTimer);
+      rejectStart(error);
+    });
     server.listen(port, host, () => {
+      if (settled) {
+        try { server.close(); } catch { /* timed-out bind already owns cleanup */ }
+        return;
+      }
+      settled = true;
+      clearTimeout(bindTimer);
       runtime.emit('runtime.http.started', { host, port });
       if (initialChoice) {
         setImmediate(() => {
@@ -1332,15 +1908,90 @@ export function createClientRuntimeServer(options = {}) {
       }
       resolveStart();
     });
-  });
-
-  return {
+  });
+
+  const closeHttpServer = timeoutMs => new Promise(resolveClose => {
+    if (!server) {
+      resolveClose({ ok: true, listening: false });
+      return;
+    }
+    let settled = false;
+    const finish = ok => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveClose({ ok, listening: Boolean(server?.listening) });
+    };
+    const timer = setTimeout(() => {
+      try { server.closeAllConnections?.(); } catch { /* exact HTTP owner already closed */ }
+      finish(!server.listening);
+    }, Math.max(100, Number(timeoutMs) || CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS));
+    try {
+      server.close(error => finish(!error));
+      server.closeIdleConnections?.();
+    } catch {
+      finish(true);
+    }
+  });
+
+  const closeRuntime = async () => {
+    const closeStartedAt = Date.now();
+    closed = true;
+    runtime.emit('runtime.http.stopping', { port });
+
+    const taskOwners = [...diagnosticTasks];
+    const [diagnosticClose, httpClose] = await Promise.all([
+      diagnosticCommandOwner.close(CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS),
+      closeHttpServer(CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS)
+    ]);
+    if (taskOwners.length > 0) {
+      const remainingCloseMs = Math.max(
+        0,
+        CLIENT_DIAGNOSTIC_CLOSE_TIMEOUT_MS - (Date.now() - closeStartedAt)
+      );
+      if (remainingCloseMs > 0) {
+        await Promise.race([
+          Promise.allSettled(taskOwners),
+          new Promise(resolve => setTimeout(resolve, remainingCloseMs))
+        ]);
+      }
+    }
+    const finalDiagnostics = diagnosticCommandOwner.getSnapshot();
+    const result = {
+      ok: diagnosticClose.ok === true
+        && httpClose.ok === true
+        && diagnosticTasks.size === 0
+        && finalDiagnostics.activeCount === 0
+        && finalDiagnostics.redirectedStreamCount === 0,
+      diagnostics: {
+        ...diagnosticClose,
+        taskCount: diagnosticTasks.size
+      },
+      http: httpClose
+    };
+    runtime.emit(
+      result.ok ? 'client.diagnostics.closed' : 'client.diagnostics.close-timeout',
+      {
+        ownerId: finalDiagnostics.ownerId,
+        activeCount: finalDiagnostics.activeCount,
+        redirectedStreamCount: finalDiagnostics.redirectedStreamCount,
+        taskCount: diagnosticTasks.size
+      }
+    );
+    return result;
+  };
+
+  return {
     runtime,
-    waitForChoice,
-    start,
+    waitForChoice,
+    start,
     get url() { return `http://${host}:${port}/`; },
     getLastChoice() { return lastChoice; },
-    update(patch = {}) {
+    acceptChoice(choice, message) {
+      complete(choice, message);
+      return lastChoice;
+    },
+    update(patch = {}) {
       Object.assign(state, patch);
       if (patch.agent && typeof patch.agent === 'object') {
         state.agent = { ...state.agent, ...patch.agent };
@@ -1358,11 +2009,8 @@ export function createClientRuntimeServer(options = {}) {
       if (Array.isArray(patch.endpointCandidates)) state.endpointCandidates = patch.endpointCandidates;
     },
     close() {
-      runtime.emit('runtime.http.stopping', { port });
-      if (hardwareRefreshTimer) clearInterval(hardwareRefreshTimer);
-      if (gpuRefreshTimer) clearInterval(gpuRefreshTimer);
-      if (networkRefreshTimer) clearInterval(networkRefreshTimer);
-      try { server?.close(); } catch { /* already closed */ }
+      if (!runtimeClosePromise) runtimeClosePromise = closeRuntime();
+      return runtimeClosePromise;
     },
     getRoleRestartRequest() { return options.getRoleRestartRequest?.() || null; }
   };