@livedesk/client 0.1.234 → 0.1.236

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

@@ -1,1046 +1,986 @@
-import { createServer } from 'node:http';
-import { randomBytes } from 'node:crypto';
-import { execFile } from 'node:child_process';
-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 { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+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';
-import { createOsSecretStore, OS_SECRET_REFERENCE } from '../../../runtime-core/src/os-secret-store.js';
-
-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';
-const CLIENT_STATE_DIR = process.env.LIVEDESK_STATE_DIR || (process.env.LIVEDESK_UNIFIED_RUNTIME === '1' ? join(os.homedir(), '.livedesk') : join(os.homedir(), '.livedesk-client'));
-const CLIENT_AUTH_PATH = join(CLIENT_STATE_DIR, 'auth.json');
-const CLIENT_REFRESH_SECRET_STORE = createOsSecretStore({
-  service: 'LiveDesk',
-  account: 'client-refresh-token',
-  dataDir: CLIENT_STATE_DIR
-});
-const DEFAULT_TRUSTED_WEB_ORIGINS = Object.freeze([
-  'https://livedesk.pages.dev',
-  'http://127.0.0.1:5173',
-  'http://localhost:5173',
-  'http://127.0.0.1:4173',
-  'http://localhost:4173'
-]);
-const LIVE_DESK_PAGES_PREVIEW_HOST = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.livedesk\.pages\.dev$/;
-const READ_ONLY_CLIENT_API_PATHS = new Set([
-  '/api/health',
-  '/api/runtime',
-  '/api/runtime/status',
-  '/api/runtime/events',
-  '/api/client/status',
-  '/api/client/computer',
-  '/api/client/system',
-  '/api/client/permissions',
-  '/api/client/diagnostics',
-  '/api/auth/status'
-]);
-
-function normalizeString(value, maxLength = 1024) {
-  return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
-}
-
-function normalizeAccountAvatarUrl(value) {
-  const candidate = normalizeString(value, 2048);
-  if (!candidate) return '';
-  try {
-    const url = new URL(candidate);
-    return url.protocol === 'https:' || url.protocol === 'http:' ? url.toString() : '';
-  } catch {
-    return '';
-  }
-}
-
-function readAccessTokenProfile(accessToken) {
-  const token = normalizeString(accessToken, 8192);
-  const payloadSegment = token.split('.')[1] || '';
-  if (!payloadSegment) return {};
-  try {
-    const payload = JSON.parse(Buffer.from(payloadSegment, 'base64url').toString('utf8'));
-    return payload && typeof payload === 'object' ? payload : {};
-  } catch {
-    return {};
-  }
-}
-
-function readClientAccountProfile(sessionOrUser) {
-  const tokenProfile = readAccessTokenProfile(sessionOrUser?.access_token);
-  const user = sessionOrUser?.user && typeof sessionOrUser.user === 'object'
-    ? sessionOrUser.user
-    : sessionOrUser && typeof sessionOrUser === 'object'
-      ? sessionOrUser
-      : {};
-  const metadata = user.user_metadata && typeof user.user_metadata === 'object'
-    ? user.user_metadata
-    : {};
-  const tokenMetadata = tokenProfile.user_metadata && typeof tokenProfile.user_metadata === 'object'
-    ? tokenProfile.user_metadata
-    : {};
-  const email = normalizeString(user.email || tokenProfile.email, 320);
-  const name = normalizeString(
-    metadata.full_name
-      || metadata.name
-      || metadata.preferred_username
-      || tokenMetadata.full_name
-      || tokenMetadata.name
-      || tokenMetadata.preferred_username
-      || user.name
-      || tokenProfile.name
-      || email
-      || user.id,
-    160
-  );
-  const avatarUrl = normalizeAccountAvatarUrl(
-    metadata.avatar_url
-      || metadata.picture
-      || tokenMetadata.avatar_url
-      || tokenMetadata.picture
-      || user.avatar_url
-      || user.picture
-  );
-  return { email, name, avatarUrl };
-}
-
-function mergeClientAccountProfile(session, sourceUser) {
-  const profile = readClientAccountProfile(sourceUser);
-  const existingUserMetadata = session?.user?.user_metadata && typeof session.user.user_metadata === 'object'
-    ? session.user.user_metadata
-    : {};
-  const userMetadata = {
-    ...existingUserMetadata,
-    ...(profile.name ? { full_name: profile.name } : {}),
-    ...(profile.avatarUrl ? { avatar_url: profile.avatarUrl } : {})
-  };
-  return {
-    ...session,
-    user: {
-      ...(session?.user || {}),
-      ...(Object.keys(userMetadata).length > 0 ? { user_metadata: userMetadata } : {})
-    }
-  };
-}
-
-async function hydrateClientAccountProfile(session) {
-  const accessToken = normalizeString(session?.access_token, 8192);
-  if (!accessToken) return session;
-  try {
-    const response = await fetch(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/user`, {
-      headers: {
-        apikey: SUPABASE_PUBLISHABLE_KEY,
-        Authorization: `Bearer ${accessToken}`,
-        Accept: 'application/json'
-      },
-      signal: AbortSignal.timeout(5_000)
-    });
-    if (!response.ok) return session;
-    const verifiedUser = await response.json().catch(() => null);
-    return verifiedUser ? mergeClientAccountProfile(session, verifiedUser) : session;
-  } catch {
-    return session;
-  }
-}
-
-function normalizePort(value, fallback = DEFAULT_PORT) {
-  const port = Number(value);
-  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : fallback;
-}
-
-function normalizeSlotNumber(value) {
-  const slotNumber = Number(String(value ?? '').trim());
-  return Number.isInteger(slotNumber) && slotNumber >= 1 && slotNumber <= 999
-    ? slotNumber
-    : 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);
-    totals.idle += Number(cpu.times?.idle || 0);
-    totals.total += times.reduce((sum, value) => sum + value, 0);
-    return totals;
-  }, { idle: 0, total: 0 });
-}
-
-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;
-}
-
-function percentFromRatio(value) {
-  const number = finiteNumber(value);
-  if (number === null) return null;
-  return Math.round(Math.max(0, Math.min(100, number)) * 10) / 10;
-}
-
-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) {
-  return String(output || '')
-    .split(/\r?\n/)
-    .map(line => line.trim())
-    .filter(Boolean)
-    .map(line => {
-      const [name = '', usage = '', totalMemoryMiB = '', usedMemoryMiB = ''] = line.split(',').map(value => value.trim());
-      const memoryTotalBytes = finiteNumber(totalMemoryMiB);
-      const memoryUsedBytes = finiteNumber(usedMemoryMiB);
-      return {
-        name: normalizeString(name, 160),
-        usagePercent: percentFromRatio(usage),
-        memoryTotalBytes: memoryTotalBytes === null ? null : Math.round(memoryTotalBytes * 1024 ** 2),
-        memoryUsedBytes: memoryUsedBytes === null ? null : Math.round(memoryUsedBytes * 1024 ** 2)
-      };
-    })
-    .filter(gpu => gpu.name);
-}
-
-function parseCounter(value) {
-  const number = Number(String(value || '').replaceAll(',', ''));
-  return Number.isFinite(number) && number >= 0 ? number : 0;
-}
-
-export function parseWindowsNetworkOutput(output) {
-  for (const line of String(output || '').split(/\r?\n/)) {
-    const match = line.match(/(?:^|\s)(\d[\d,]*)\s+(\d[\d,]*)\s*$/);
-    if (match) return { receivedBytes: parseCounter(match[1]), sentBytes: parseCounter(match[2]) };
-  }
-  return { receivedBytes: 0, sentBytes: 0 };
-}
-
-export function parseMacNetworkOutput(output) {
-  const lines = String(output || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
-  const header = lines.find(line => /\bIbytes\b/i.test(line) && /\bObytes\b/i.test(line));
-  if (!header) return { receivedBytes: 0, sentBytes: 0 };
-  const columns = header.split(/\s+/);
-  const receivedIndex = columns.findIndex(column => column.toLowerCase() === 'ibytes');
-  const sentIndex = columns.findIndex(column => column.toLowerCase() === 'obytes');
-  const byInterface = new Map();
-  for (const line of lines.slice(lines.indexOf(header) + 1)) {
-    const fields = line.split(/\s+/);
-    const name = normalizeString(fields[0], 80);
-    if (!name || name === 'lo0' || fields.length <= Math.max(receivedIndex, sentIndex)) continue;
-    const receivedBytes = parseCounter(fields[receivedIndex]);
-    const sentBytes = parseCounter(fields[sentIndex]);
-    const previous = byInterface.get(name) || { receivedBytes: 0, sentBytes: 0 };
-    byInterface.set(name, {
-      receivedBytes: Math.max(previous.receivedBytes, receivedBytes),
-      sentBytes: Math.max(previous.sentBytes, sentBytes)
-    });
-  }
-  return [...byInterface.values()].reduce((total, current) => ({
-    receivedBytes: total.receivedBytes + current.receivedBytes,
-    sentBytes: total.sentBytes + current.sentBytes
-  }), { receivedBytes: 0, sentBytes: 0 });
-}
-
-export function parseLinuxNetworkOutput(output) {
-  let receivedBytes = 0;
-  let sentBytes = 0;
-  for (const line of String(output || '').split(/\r?\n/)) {
-    const separator = line.indexOf(':');
-    if (separator < 0) continue;
-    const name = line.slice(0, separator).trim();
-    if (!name || name === 'lo') continue;
-    const fields = line.slice(separator + 1).trim().split(/\s+/);
-    receivedBytes += parseCounter(fields[0]);
-    sentBytes += parseCounter(fields[8]);
-  }
-  return { receivedBytes, sentBytes };
-}
-
-function activeNetworkInterfaces() {
-  const interfaces = [];
-  for (const [name, addresses] of Object.entries(os.networkInterfaces())) {
-    for (const address of addresses || []) {
-      if (address.internal) continue;
-      interfaces.push({
-        name: normalizeString(name, 80),
-        address: normalizeString(address.address, 100),
-        family: normalizeString(address.family, 20)
-      });
-    }
-  }
-  return interfaces;
-}
-
-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 (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 {
-      ok: true,
-      value: parseLinuxNetworkOutput(readFileSync('/proc/net/dev', 'utf8'))
-    };
-  } catch {
-    return {
-      ok: false,
-      value: { receivedBytes: 0, sentBytes: 0 },
-      error: 'network-counters-unavailable'
-    };
-  }
-}
-
-function normalizeGpu(value) {
-  if (!value || typeof value !== 'object') return null;
-  const name = normalizeString(value.name, 160);
-  if (!name) return null;
-  return {
-    name,
-    usagePercent: percentFromRatio(value.usagePercent),
-    memoryTotalBytes: finiteNumber(value.memoryTotalBytes),
-    memoryUsedBytes: finiteNumber(value.memoryUsedBytes)
-  };
-}
-
-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);
-  const totalBytes = finiteNumber(value.totalBytes);
-  const freeBytes = finiteNumber(value.freeBytes);
-  if (!mount || totalBytes === null || totalBytes <= 0 || freeBytes === null) return null;
-  const boundedFreeBytes = Math.min(totalBytes, freeBytes);
-  const usedBytes = Math.max(0, totalBytes - boundedFreeBytes);
-  return {
-    name: normalizeString(value.name, 120),
-    mount,
-    totalBytes,
-    freeBytes: boundedFreeBytes,
-    usedBytes,
-    usedPercent: Math.round((usedBytes / totalBytes) * 1000) / 10
-  };
-}
-
-export function parseWindowsHardwareOutput(output) {
-  try {
-    const payload = JSON.parse(String(output || '').trim());
-    const rawGpus = Array.isArray(payload?.gpus) ? payload.gpus : payload?.gpus ? [payload.gpus] : [];
-    const rawDisks = Array.isArray(payload?.disks) ? payload.disks : payload?.disks ? [payload.disks] : [];
-    return {
-      gpus: rawGpus.map(normalizeGpu).filter(Boolean),
-      disks: rawDisks.map(normalizeDisk).filter(Boolean)
-    };
-  } catch {
-    return { gpus: [], disks: [] };
-  }
-}
-
-function readRootDiskSnapshot() {
-  try {
-    const mount = parse(os.homedir()).root || '/';
-    const stats = statfsSync(mount, { bigint: true });
-    return normalizeDisk({
-      name: process.platform === 'darwin' ? 'Macintosh HD' : 'System',
-      mount,
-      totalBytes: Number(stats.bsize * stats.blocks),
-      freeBytes: Number(stats.bsize * stats.bavail)
-    });
-  } catch {
-    return null;
-  }
-}
-
-function readFilesystemDiskSnapshot(mount, name) {
-  try {
-    const stats = statfsSync(mount, { bigint: true });
-    return normalizeDisk({
-      name,
-      mount,
-      totalBytes: Number(stats.bsize * stats.blocks),
-      freeBytes: Number(stats.bsize * stats.bavail)
-    });
-  } catch {
-    return null;
-  }
-}
-
-export function readMacDiskSnapshots(options = {}) {
-  const rootMount = String(options.rootMount || '/');
-  const volumesRoot = String(options.volumesRoot || '/Volumes');
-  const disks = [];
-  const seenPaths = new Set();
-  const addDisk = (mount, name) => {
-    try {
-      const resolvedPath = realpathSync(mount);
-      if (seenPaths.has(resolvedPath)) return;
-      const disk = readFilesystemDiskSnapshot(mount, name);
-      if (!disk) return;
-      seenPaths.add(resolvedPath);
-      disks.push(disk);
-    } catch {
-      // A removable volume may disappear while the snapshot is being read.
-    }
-  };
-
-  addDisk(rootMount, 'Macintosh HD');
-  try {
-    for (const entry of readdirSync(volumesRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-      addDisk(join(volumesRoot, entry.name), entry.name);
-    }
-  } catch {
-    // /Volumes can be unavailable in restricted environments; keep the root disk.
-  }
-  return disks;
-}
-
-async function readWindowsHardwareSnapshot(commandOwner) {
-  const script = [
-    '$ErrorActionPreference="Stop"',
-    '$OutputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new($false)',
-    '$physicalDriveIds=@(Get-CimInstance Win32_DiskDrive | ForEach-Object { Get-CimAssociatedInstance -InputObject $_ -Association Win32_DiskDriveToDiskPartition | ForEach-Object { Get-CimAssociatedInstance -InputObject $_ -Association Win32_LogicalDiskToPartition } } | Select-Object -ExpandProperty DeviceID -Unique)',
-    '$gpus=@(Get-CimInstance Win32_VideoController | Where-Object { $_.Name } | ForEach-Object { [pscustomobject]@{ name=[string]$_.Name; usagePercent=$null; memoryTotalBytes=if ($_.AdapterRAM) { [double]$_.AdapterRAM } else { $null }; memoryUsedBytes=$null } })',
-    '$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 commandOwner.capture('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], 5000));
-}
-
-function parseMacGpuOutput(output) {
-  try {
-    const payload = JSON.parse(String(output || '').trim());
-    return (Array.isArray(payload?.SPDisplaysDataType) ? payload.SPDisplaysDataType : [])
-      .map(item => normalizeGpu({ name: item?.sppci_model || item?._name }))
-      .filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-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' };
-  }
-  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 {
-    ok: Boolean(disk),
-    value: { gpus: [], disks: disk ? [disk] : [] },
-    error: disk ? '' : 'root-disk-unavailable'
-  };
-}
-
-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) {
-  const candidate = normalizeString(value, 300);
-  if (!candidate) return '';
-  try {
-    const parsed = new URL(candidate);
-    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '';
-    return parsed.origin.toLowerCase();
-  } catch {
-    return '';
-  }
-}
-
-function createTrustedWebOrigins(port) {
-  const origins = new Set([
-    ...DEFAULT_TRUSTED_WEB_ORIGINS,
-    `http://127.0.0.1:${port}`,
-    `http://localhost:${port}`
-  ]);
-  for (const value of [process.env.LIVEDESK_WEB_ORIGINS, process.env.LIVEDESK_SITE_URL]) {
-    for (const candidate of String(value || '').split(/[\s,]+/)) {
-      const origin = normalizeOrigin(candidate);
-      if (origin) origins.add(origin);
-    }
-  }
-  return origins;
-}
-
-function readSavedSession() {
-  if (process.env.LIVEDESK_DESKTOP_HOST === '1') return null;
-  try {
+import { createRuntimeManager, normalizeRuntimeAuthSession, runtimeRoleError, RuntimeState } from '../../../runtime-core/src/index.js';
+
+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';
+const CLIENT_STATE_DIR = process.env.LIVEDESK_STATE_DIR || (process.env.LIVEDESK_UNIFIED_RUNTIME === '1' ? join(os.homedir(), '.livedesk') : join(os.homedir(), '.livedesk-client'));
+const CLIENT_AUTH_PATH = join(CLIENT_STATE_DIR, 'auth.json');
+const DEFAULT_TRUSTED_WEB_ORIGINS = Object.freeze([
+  'https://livedesk.pages.dev',
+  'http://127.0.0.1:5173',
+  'http://localhost:5173',
+  'http://127.0.0.1:4173',
+  'http://localhost:4173'
+]);
+const LIVE_DESK_PAGES_PREVIEW_HOST = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.livedesk\.pages\.dev$/;
+const READ_ONLY_CLIENT_API_PATHS = new Set([
+  '/api/health',
+  '/api/runtime',
+  '/api/runtime/status',
+  '/api/runtime/events',
+  '/api/client/status',
+  '/api/client/computer',
+  '/api/client/system',
+  '/api/client/permissions',
+  '/api/client/diagnostics',
+  '/api/auth/status'
+]);
+
+function normalizeString(value, maxLength = 1024) {
+  return String(value ?? '').replace(/[\r\n\t]/g, ' ').trim().slice(0, maxLength);
+}
+
+function normalizeAccountAvatarUrl(value) {
+  const candidate = normalizeString(value, 2048);
+  if (!candidate) return '';
+  try {
+    const url = new URL(candidate);
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url.toString() : '';
+  } catch {
+    return '';
+  }
+}
+
+function readAccessTokenProfile(accessToken) {
+  const token = normalizeString(accessToken, 8192);
+  const payloadSegment = token.split('.')[1] || '';
+  if (!payloadSegment) return {};
+  try {
+    const payload = JSON.parse(Buffer.from(payloadSegment, 'base64url').toString('utf8'));
+    return payload && typeof payload === 'object' ? payload : {};
+  } catch {
+    return {};
+  }
+}
+
+function readClientAccountProfile(sessionOrUser) {
+  const tokenProfile = readAccessTokenProfile(sessionOrUser?.access_token);
+  const user = sessionOrUser?.user && typeof sessionOrUser.user === 'object'
+    ? sessionOrUser.user
+    : sessionOrUser && typeof sessionOrUser === 'object'
+      ? sessionOrUser
+      : {};
+  const metadata = user.user_metadata && typeof user.user_metadata === 'object'
+    ? user.user_metadata
+    : {};
+  const tokenMetadata = tokenProfile.user_metadata && typeof tokenProfile.user_metadata === 'object'
+    ? tokenProfile.user_metadata
+    : {};
+  const email = normalizeString(user.email || tokenProfile.email, 320);
+  const name = normalizeString(
+    metadata.full_name
+      || metadata.name
+      || metadata.preferred_username
+      || tokenMetadata.full_name
+      || tokenMetadata.name
+      || tokenMetadata.preferred_username
+      || user.name
+      || tokenProfile.name
+      || email
+      || user.id,
+    160
+  );
+  const avatarUrl = normalizeAccountAvatarUrl(
+    metadata.avatar_url
+      || metadata.picture
+      || tokenMetadata.avatar_url
+      || tokenMetadata.picture
+      || user.avatar_url
+      || user.picture
+  );
+  return { email, name, avatarUrl };
+}
+
+function mergeClientAccountProfile(session, sourceUser) {
+  const profile = readClientAccountProfile(sourceUser);
+  const existingUserMetadata = session?.user?.user_metadata && typeof session.user.user_metadata === 'object'
+    ? session.user.user_metadata
+    : {};
+  const userMetadata = {
+    ...existingUserMetadata,
+    ...(profile.name ? { full_name: profile.name } : {}),
+    ...(profile.avatarUrl ? { avatar_url: profile.avatarUrl } : {})
+  };
+  return {
+    ...session,
+    user: {
+      ...(session?.user || {}),
+      ...(Object.keys(userMetadata).length > 0 ? { user_metadata: userMetadata } : {})
+    }
+  };
+}
+
+async function hydrateClientAccountProfile(session) {
+  const accessToken = normalizeString(session?.access_token, 8192);
+  if (!accessToken) return session;
+  try {
+    const response = await fetch(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/user`, {
+      headers: {
+        apikey: SUPABASE_PUBLISHABLE_KEY,
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json'
+      },
+      signal: AbortSignal.timeout(5_000)
+    });
+    if (!response.ok) return session;
+    const verifiedUser = await response.json().catch(() => null);
+    return verifiedUser ? mergeClientAccountProfile(session, verifiedUser) : session;
+  } catch {
+    return session;
+  }
+}
+
+function normalizePort(value, fallback = DEFAULT_PORT) {
+  const port = Number(value);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : fallback;
+}
+
+function normalizeSlotNumber(value) {
+  const slotNumber = Number(String(value ?? '').trim());
+  return Number.isInteger(slotNumber) && slotNumber >= 1 && slotNumber <= 999
+    ? slotNumber
+    : 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);
+    totals.idle += Number(cpu.times?.idle || 0);
+    totals.total += times.reduce((sum, value) => sum + value, 0);
+    return totals;
+  }, { idle: 0, total: 0 });
+}
+
+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;
+}
+
+function percentFromRatio(value) {
+  const number = finiteNumber(value);
+  if (number === null) return null;
+  return Math.round(Math.max(0, Math.min(100, number)) * 10) / 10;
+}
+
+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) {
+  return String(output || '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => {
+      const [name = '', usage = '', totalMemoryMiB = '', usedMemoryMiB = ''] = line.split(',').map(value => value.trim());
+      const memoryTotalBytes = finiteNumber(totalMemoryMiB);
+      const memoryUsedBytes = finiteNumber(usedMemoryMiB);
+      return {
+        name: normalizeString(name, 160),
+        usagePercent: percentFromRatio(usage),
+        memoryTotalBytes: memoryTotalBytes === null ? null : Math.round(memoryTotalBytes * 1024 ** 2),
+        memoryUsedBytes: memoryUsedBytes === null ? null : Math.round(memoryUsedBytes * 1024 ** 2)
+      };
+    })
+    .filter(gpu => gpu.name);
+}
+
+function parseCounter(value) {
+  const number = Number(String(value || '').replaceAll(',', ''));
+  return Number.isFinite(number) && number >= 0 ? number : 0;
+}
+
+export function parseWindowsNetworkOutput(output) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const match = line.match(/(?:^|\s)(\d[\d,]*)\s+(\d[\d,]*)\s*$/);
+    if (match) return { receivedBytes: parseCounter(match[1]), sentBytes: parseCounter(match[2]) };
+  }
+  return { receivedBytes: 0, sentBytes: 0 };
+}
+
+export function parseMacNetworkOutput(output) {
+  const lines = String(output || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  const header = lines.find(line => /\bIbytes\b/i.test(line) && /\bObytes\b/i.test(line));
+  if (!header) return { receivedBytes: 0, sentBytes: 0 };
+  const columns = header.split(/\s+/);
+  const receivedIndex = columns.findIndex(column => column.toLowerCase() === 'ibytes');
+  const sentIndex = columns.findIndex(column => column.toLowerCase() === 'obytes');
+  const byInterface = new Map();
+  for (const line of lines.slice(lines.indexOf(header) + 1)) {
+    const fields = line.split(/\s+/);
+    const name = normalizeString(fields[0], 80);
+    if (!name || name === 'lo0' || fields.length <= Math.max(receivedIndex, sentIndex)) continue;
+    const receivedBytes = parseCounter(fields[receivedIndex]);
+    const sentBytes = parseCounter(fields[sentIndex]);
+    const previous = byInterface.get(name) || { receivedBytes: 0, sentBytes: 0 };
+    byInterface.set(name, {
+      receivedBytes: Math.max(previous.receivedBytes, receivedBytes),
+      sentBytes: Math.max(previous.sentBytes, sentBytes)
+    });
+  }
+  return [...byInterface.values()].reduce((total, current) => ({
+    receivedBytes: total.receivedBytes + current.receivedBytes,
+    sentBytes: total.sentBytes + current.sentBytes
+  }), { receivedBytes: 0, sentBytes: 0 });
+}
+
+export function parseLinuxNetworkOutput(output) {
+  let receivedBytes = 0;
+  let sentBytes = 0;
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const separator = line.indexOf(':');
+    if (separator < 0) continue;
+    const name = line.slice(0, separator).trim();
+    if (!name || name === 'lo') continue;
+    const fields = line.slice(separator + 1).trim().split(/\s+/);
+    receivedBytes += parseCounter(fields[0]);
+    sentBytes += parseCounter(fields[8]);
+  }
+  return { receivedBytes, sentBytes };
+}
+
+function activeNetworkInterfaces() {
+  const interfaces = [];
+  for (const [name, addresses] of Object.entries(os.networkInterfaces())) {
+    for (const address of addresses || []) {
+      if (address.internal) continue;
+      interfaces.push({
+        name: normalizeString(name, 80),
+        address: normalizeString(address.address, 100),
+        family: normalizeString(address.family, 20)
+      });
+    }
+  }
+  return interfaces;
+}
+
+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 (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 {
+      ok: true,
+      value: parseLinuxNetworkOutput(readFileSync('/proc/net/dev', 'utf8'))
+    };
+  } catch {
+    return {
+      ok: false,
+      value: { receivedBytes: 0, sentBytes: 0 },
+      error: 'network-counters-unavailable'
+    };
+  }
+}
+
+function normalizeGpu(value) {
+  if (!value || typeof value !== 'object') return null;
+  const name = normalizeString(value.name, 160);
+  if (!name) return null;
+  return {
+    name,
+    usagePercent: percentFromRatio(value.usagePercent),
+    memoryTotalBytes: finiteNumber(value.memoryTotalBytes),
+    memoryUsedBytes: finiteNumber(value.memoryUsedBytes)
+  };
+}
+
+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);
+  const totalBytes = finiteNumber(value.totalBytes);
+  const freeBytes = finiteNumber(value.freeBytes);
+  if (!mount || totalBytes === null || totalBytes <= 0 || freeBytes === null) return null;
+  const boundedFreeBytes = Math.min(totalBytes, freeBytes);
+  const usedBytes = Math.max(0, totalBytes - boundedFreeBytes);
+  return {
+    name: normalizeString(value.name, 120),
+    mount,
+    totalBytes,
+    freeBytes: boundedFreeBytes,
+    usedBytes,
+    usedPercent: Math.round((usedBytes / totalBytes) * 1000) / 10
+  };
+}
+
+export function parseWindowsHardwareOutput(output) {
+  try {
+    const payload = JSON.parse(String(output || '').trim());
+    const rawGpus = Array.isArray(payload?.gpus) ? payload.gpus : payload?.gpus ? [payload.gpus] : [];
+    const rawDisks = Array.isArray(payload?.disks) ? payload.disks : payload?.disks ? [payload.disks] : [];
+    return {
+      gpus: rawGpus.map(normalizeGpu).filter(Boolean),
+      disks: rawDisks.map(normalizeDisk).filter(Boolean)
+    };
+  } catch {
+    return { gpus: [], disks: [] };
+  }
+}
+
+function readRootDiskSnapshot() {
+  try {
+    const mount = parse(os.homedir()).root || '/';
+    const stats = statfsSync(mount, { bigint: true });
+    return normalizeDisk({
+      name: process.platform === 'darwin' ? 'Macintosh HD' : 'System',
+      mount,
+      totalBytes: Number(stats.bsize * stats.blocks),
+      freeBytes: Number(stats.bsize * stats.bavail)
+    });
+  } catch {
+    return null;
+  }
+}
+
+function readFilesystemDiskSnapshot(mount, name) {
+  try {
+    const stats = statfsSync(mount, { bigint: true });
+    return normalizeDisk({
+      name,
+      mount,
+      totalBytes: Number(stats.bsize * stats.blocks),
+      freeBytes: Number(stats.bsize * stats.bavail)
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function readMacDiskSnapshots(options = {}) {
+  const rootMount = String(options.rootMount || '/');
+  const volumesRoot = String(options.volumesRoot || '/Volumes');
+  const disks = [];
+  const seenPaths = new Set();
+  const addDisk = (mount, name) => {
+    try {
+      const resolvedPath = realpathSync(mount);
+      if (seenPaths.has(resolvedPath)) return;
+      const disk = readFilesystemDiskSnapshot(mount, name);
+      if (!disk) return;
+      seenPaths.add(resolvedPath);
+      disks.push(disk);
+    } catch {
+      // A removable volume may disappear while the snapshot is being read.
+    }
+  };
+
+  addDisk(rootMount, 'Macintosh HD');
+  try {
+    for (const entry of readdirSync(volumesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      addDisk(join(volumesRoot, entry.name), entry.name);
+    }
+  } catch {
+    // /Volumes can be unavailable in restricted environments; keep the root disk.
+  }
+  return disks;
+}
+
+async function readWindowsHardwareSnapshot(commandOwner) {
+  const script = [
+    '$ErrorActionPreference="Stop"',
+    '$OutputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new($false)',
+    '$physicalDriveIds=@(Get-CimInstance Win32_DiskDrive | ForEach-Object { Get-CimAssociatedInstance -InputObject $_ -Association Win32_DiskDriveToDiskPartition | ForEach-Object { Get-CimAssociatedInstance -InputObject $_ -Association Win32_LogicalDiskToPartition } } | Select-Object -ExpandProperty DeviceID -Unique)',
+    '$gpus=@(Get-CimInstance Win32_VideoController | Where-Object { $_.Name } | ForEach-Object { [pscustomobject]@{ name=[string]$_.Name; usagePercent=$null; memoryTotalBytes=if ($_.AdapterRAM) { [double]$_.AdapterRAM } else { $null }; memoryUsedBytes=$null } })',
+    '$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 commandOwner.capture('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], 5000));
+}
+
+function parseMacGpuOutput(output) {
+  try {
+    const payload = JSON.parse(String(output || '').trim());
+    return (Array.isArray(payload?.SPDisplaysDataType) ? payload.SPDisplaysDataType : [])
+      .map(item => normalizeGpu({ name: item?.sppci_model || item?._name }))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+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' };
+  }
+  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 {
+    ok: Boolean(disk),
+    value: { gpus: [], disks: disk ? [disk] : [] },
+    error: disk ? '' : 'root-disk-unavailable'
+  };
+}
+
+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) {
+  const candidate = normalizeString(value, 300);
+  if (!candidate) return '';
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '';
+    return parsed.origin.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function createTrustedWebOrigins(port) {
+  const origins = new Set([
+    ...DEFAULT_TRUSTED_WEB_ORIGINS,
+    `http://127.0.0.1:${port}`,
+    `http://localhost:${port}`
+  ]);
+  for (const value of [process.env.LIVEDESK_WEB_ORIGINS, process.env.LIVEDESK_SITE_URL]) {
+    for (const candidate of String(value || '').split(/[\s,]+/)) {
+      const origin = normalizeOrigin(candidate);
+      if (origin) origins.add(origin);
+    }
+  }
+  return origins;
+}
+
+function readSavedSession() {
+  if (process.env.LIVEDESK_DESKTOP_HOST === '1') return null;
+  try {
     const raw = JSON.parse(readFileSync(CLIENT_AUTH_PATH, 'utf8'))?.[CLIENT_AUTH_STORAGE_KEY];
-    const session = typeof raw === 'string' ? JSON.parse(raw) : null;
-    if (!session?.access_token) return null;
-    const plaintextRefreshToken = normalizeString(session.refresh_token, 8192);
-    const refreshToken = plaintextRefreshToken || (session.refresh_token_ref === OS_SECRET_REFERENCE
-      ? CLIENT_REFRESH_SECRET_STORE.read()
-      : '');
-    if (!refreshToken) return null;
-    if (plaintextRefreshToken) {
-      if (!CLIENT_REFRESH_SECRET_STORE.write(plaintextRefreshToken)) {
-        writePrivateJsonAtomic(CLIENT_AUTH_PATH, {});
-        return null;
-      }
-      const migrated = { ...session, refresh_token_ref: OS_SECRET_REFERENCE };
-      delete migrated.refresh_token;
-      writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(migrated) });
-    }
-    return { ...session, refresh_token: refreshToken };
+    const session = typeof raw === 'string' ? JSON.parse(raw) : null;
+    return session?.access_token ? session : null;
   } catch {
     return null;
   }
-}
-
-function resolveSavedSessionSecret(session) {
-  if (!session || typeof session !== 'object') return null;
-  const refreshToken = normalizeString(session.refresh_token, 8192)
-    || (session.refresh_token_ref === OS_SECRET_REFERENCE ? CLIENT_REFRESH_SECRET_STORE.read() : '');
-  return session.access_token && refreshToken ? { ...session, refresh_token: refreshToken } : null;
-}
-
-function writePrivateJsonAtomic(path, value) {
-  mkdirSync(dirname(path), { recursive: true });
-  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
-  try {
-    writeFileSync(temporaryPath, JSON.stringify(value, null, 2), 'utf8');
-    try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
-    renameSync(temporaryPath, path);
-    try { chmodSync(path, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
-  } catch (error) {
-    try { rmSync(temporaryPath, { force: true }); } catch { /* best effort cleanup */ }
-    throw error;
-  }
-}
-
-function writeSavedSession(session) {
-  if (!session?.access_token || !session?.refresh_token) return false;
-  if (process.env.LIVEDESK_DESKTOP_HOST === '1') return true;
-  if (!CLIENT_REFRESH_SECRET_STORE.write(session.refresh_token)) return false;
-  const persisted = { ...session, refresh_token_ref: OS_SECRET_REFERENCE };
-  delete persisted.refresh_token;
-  writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(persisted) });
-  return true;
-}
-
-function clearSavedSession() {
-  CLIENT_REFRESH_SECRET_STORE.clear();
-  writePrivateJsonAtomic(CLIENT_AUTH_PATH, {});
-}
-
-export async function revokeClientProviderSession(session, options = {}) {
-  const accessToken = normalizeString(session?.access_token, 8192);
-  if (!accessToken) return { ok: true, skipped: true, reason: 'no-access-token' };
-  try {
-    if (typeof options.revokeProviderSession === 'function') {
-      const result = await options.revokeProviderSession(session);
-      return result && typeof result === 'object' ? result : { ok: result !== false };
-    }
-    const fetchImpl = typeof options.fetchImpl === 'function' ? options.fetchImpl : fetch;
-    const response = await fetchImpl(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/logout?scope=local`, {
-      method: 'POST',
-      headers: {
-        apikey: SUPABASE_PUBLISHABLE_KEY,
-        Authorization: `Bearer ${accessToken}`,
-        Accept: 'application/json'
-      },
-      signal: AbortSignal.timeout(10_000)
-    });
-    if (response.ok) return { ok: true, revoked: true };
-    if ([401, 403, 404].includes(response.status)) {
-      return { ok: true, alreadyInvalid: true, status: response.status };
-    }
-    return { ok: false, error: `provider-session-revoke-failed:${response.status}` };
-  } catch (error) {
-    return { ok: false, error: normalizeString(error?.message || error, 240) || 'provider-session-revoke-failed' };
-  }
-}
+}
+
+function writePrivateJsonAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(value, null, 2), 'utf8');
+    try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+    renameSync(temporaryPath, path);
+    try { chmodSync(path, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+  } catch (error) {
+    try { rmSync(temporaryPath, { force: true }); } catch { /* best effort cleanup */ }
+    throw error;
+  }
+}
+
+function writeSavedSession(session) {
+  if (!session?.access_token || !session?.refresh_token) return false;
+  if (process.env.LIVEDESK_DESKTOP_HOST === '1') return true;
+  writePrivateJsonAtomic(CLIENT_AUTH_PATH, { [CLIENT_AUTH_STORAGE_KEY]: JSON.stringify(session) });
+  return true;
+}
+
+function clearSavedSession() {
+  writePrivateJsonAtomic(CLIENT_AUTH_PATH, {});
+}
 
 function readBody(req) {
   return new Promise((resolveBody, reject) => {
@@ -1077,82 +1017,82 @@ function contentType(pathname) {
   return 'text/html; charset=utf-8';
 }
 
-function isLoopbackRequest(req) {
-  const address = String(req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
-  return address === '127.0.0.1' || address === '::1' || address === 'localhost' || !address;
-}
-
-function isTrustedApiOrigin(value, trustedWebOrigins) {
-  const rawOrigin = normalizeString(value, 300);
-  if (rawOrigin === 'null') return true;
-  const origin = normalizeOrigin(rawOrigin);
-  if (!origin) return false;
-  if (trustedWebOrigins.has(origin)) return true;
-  try {
-    const parsed = new URL(origin);
-    // The unified local shell has existed at both an explicit runtime port and
-    // the default loopback origin during Hub/Client module transitions. Treat
-    // every HTTP loopback origin as local. The API still requires a per-process
-    // CSRF token for mutations, and non-browser local processes already share
-    // the same machine trust boundary.
-    if (parsed.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(parsed.hostname.toLowerCase())) {
-      return true;
-    }
-    return parsed.protocol === 'https:' && LIVE_DESK_PAGES_PREVIEW_HOST.test(parsed.hostname);
-  } catch {
-    return false;
-  }
-}
-
-function isTrustedLocalRequest(req, host, port, options = {}) {
-  if (!isLoopbackRequest(req)) return false;
-  const requestHost = normalizeString(req.headers.host, 300).split(':')[0].toLowerCase();
-  if (requestHost && requestHost !== host.toLowerCase() && requestHost !== 'localhost' && requestHost !== '127.0.0.1') return false;
-
-  // Chromium can mark modulepreload/stylesheet requests as cross-site, or
-  // send Origin: null when the page was opened from a local shell. Static
-  // assets are not privileged, and the local shell still needs to read the
-  // loopback runtime API to determine the active role. Mutating API routes
-  // remain protected by the CSRF token check below.
-  if (options.allowStaticCrossSite === true) {
-    return true;
-  }
-
-  const origin = normalizeString(req.headers.origin, 300);
-  if (isTrustedApiOrigin(origin, options.trustedWebOrigins || createTrustedWebOrigins(port))) return true;
-  if (origin) return false;
-  // Chrome can label a loopback fetch as cross-site while omitting Origin.
-  // Permit only explicitly read-only status routes in that shape. The response
-  // still uses the loopback ACAO value, and all mutations continue to require
-  // both a trusted Origin and the per-process CSRF token.
-  if (options.allowReadOnlyCrossSite === true && ['GET', 'HEAD'].includes(req.method || '')) return true;
-  const fetchSite = normalizeString(req.headers['sec-fetch-site'], 40).toLowerCase();
-  return !fetchSite
-    || fetchSite === 'same-origin'
-    || fetchSite === 'same-site'
-    || fetchSite === 'none';
-}
-
-function resolveCorsOrigin(requestOrigin, port, trustedWebOrigins) {
-  const origin = normalizeString(requestOrigin, 300);
-  if (origin === 'null') return 'null';
-  return origin && isTrustedApiOrigin(origin, trustedWebOrigins)
-    ? normalizeOrigin(origin)
-    : `http://127.0.0.1:${port}`;
-}
-
-function sendJson(res, status, payload, requestOrigin = '', port = DEFAULT_PORT, trustedWebOrigins = createTrustedWebOrigins(port)) {
-  const body = JSON.stringify(payload);
-  const allowedOrigin = resolveCorsOrigin(requestOrigin, port, trustedWebOrigins);
-  res.writeHead(status, {
-    'Content-Type': 'application/json; charset=utf-8',
-    'Cache-Control': 'no-store',
-    'Access-Control-Allow-Origin': allowedOrigin,
-    'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-LiveDesk-CSRF',
-    'Access-Control-Allow-Private-Network': 'true',
-    Vary: 'Origin'
-  });
+function isLoopbackRequest(req) {
+  const address = String(req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
+  return address === '127.0.0.1' || address === '::1' || address === 'localhost' || !address;
+}
+
+function isTrustedApiOrigin(value, trustedWebOrigins) {
+  const rawOrigin = normalizeString(value, 300);
+  if (rawOrigin === 'null') return true;
+  const origin = normalizeOrigin(rawOrigin);
+  if (!origin) return false;
+  if (trustedWebOrigins.has(origin)) return true;
+  try {
+    const parsed = new URL(origin);
+    // The unified local shell has existed at both an explicit runtime port and
+    // the default loopback origin during Hub/Client module transitions. Treat
+    // every HTTP loopback origin as local. The API still requires a per-process
+    // CSRF token for mutations, and non-browser local processes already share
+    // the same machine trust boundary.
+    if (parsed.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(parsed.hostname.toLowerCase())) {
+      return true;
+    }
+    return parsed.protocol === 'https:' && LIVE_DESK_PAGES_PREVIEW_HOST.test(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function isTrustedLocalRequest(req, host, port, options = {}) {
+  if (!isLoopbackRequest(req)) return false;
+  const requestHost = normalizeString(req.headers.host, 300).split(':')[0].toLowerCase();
+  if (requestHost && requestHost !== host.toLowerCase() && requestHost !== 'localhost' && requestHost !== '127.0.0.1') return false;
+
+  // Chromium can mark modulepreload/stylesheet requests as cross-site, or
+  // send Origin: null when the page was opened from a local shell. Static
+  // assets are not privileged, and the local shell still needs to read the
+  // loopback runtime API to determine the active role. Mutating API routes
+  // remain protected by the CSRF token check below.
+  if (options.allowStaticCrossSite === true) {
+    return true;
+  }
+
+  const origin = normalizeString(req.headers.origin, 300);
+  if (isTrustedApiOrigin(origin, options.trustedWebOrigins || createTrustedWebOrigins(port))) return true;
+  if (origin) return false;
+  // Chrome can label a loopback fetch as cross-site while omitting Origin.
+  // Permit only explicitly read-only status routes in that shape. The response
+  // still uses the loopback ACAO value, and all mutations continue to require
+  // both a trusted Origin and the per-process CSRF token.
+  if (options.allowReadOnlyCrossSite === true && ['GET', 'HEAD'].includes(req.method || '')) return true;
+  const fetchSite = normalizeString(req.headers['sec-fetch-site'], 40).toLowerCase();
+  return !fetchSite
+    || fetchSite === 'same-origin'
+    || fetchSite === 'same-site'
+    || fetchSite === 'none';
+}
+
+function resolveCorsOrigin(requestOrigin, port, trustedWebOrigins) {
+  const origin = normalizeString(requestOrigin, 300);
+  if (origin === 'null') return 'null';
+  return origin && isTrustedApiOrigin(origin, trustedWebOrigins)
+    ? normalizeOrigin(origin)
+    : `http://127.0.0.1:${port}`;
+}
+
+function sendJson(res, status, payload, requestOrigin = '', port = DEFAULT_PORT, trustedWebOrigins = createTrustedWebOrigins(port)) {
+  const body = JSON.stringify(payload);
+  const allowedOrigin = resolveCorsOrigin(requestOrigin, port, trustedWebOrigins);
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+    'Access-Control-Allow-Origin': allowedOrigin,
+    'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-LiveDesk-CSRF',
+    'Access-Control-Allow-Private-Network': 'true',
+    Vary: 'Origin'
+  });
   res.end(body);
 }
 
@@ -1161,122 +1101,121 @@ function sendText(res, status, body, type = 'text/plain; charset=utf-8') {
   res.end(body);
 }
 
-export function createClientRuntimeServer(options = {}) {
-  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
-  const port = normalizePort(options.port, DEFAULT_PORT);
-  const initialChoice = options.initialChoice && typeof options.initialChoice === 'object'
-    ? options.initialChoice
-    : null;
-  const initialChoiceMessage = normalizeString(
-    options.initialChoiceMessage,
-    1000
-  ) || 'Existing LiveDesk credentials accepted. Starting the Client.';
-  const trustedWebOrigins = createTrustedWebOrigins(port);
-  const webDist = resolve(String(options.webDist || process.env.LIVEDESK_WEB_DIST || '').trim() || join(process.cwd(), 'apps', 'web', 'dist'));
+export function createClientRuntimeServer(options = {}) {
+  const host = normalizeString(options.host, 80) || DEFAULT_HOST;
+  const port = normalizePort(options.port, DEFAULT_PORT);
+  const initialChoice = options.initialChoice && typeof options.initialChoice === 'object'
+    ? options.initialChoice
+    : null;
+  const initialChoiceMessage = normalizeString(
+    options.initialChoiceMessage,
+    1000
+  ) || 'Existing LiveDesk credentials accepted. Starting the Client.';
+  const trustedWebOrigins = createTrustedWebOrigins(port);
+  const webDist = resolve(String(options.webDist || process.env.LIVEDESK_WEB_DIST || '').trim() || join(process.cwd(), 'apps', 'web', 'dist'));
   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 providedSavedSession = resolveSavedSessionSecret(options.savedSession);
-  const savedSession = options.loadSavedSession === false
-    ? null
-    : providedSavedSession
-      ? providedSavedSession
-      : 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: 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 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',
-    manager: '',
-    pairToken: '',
-    slotNumber: normalizeSlotNumber(options.slot),
-    assignedHubId: normalizeString(options.assignedHubId ?? process.env.LIVEDESK_ASSIGNED_HUB_ID, 160),
-    endpointCandidates: [],
-    roleVersion: normalizeRoleVersion(options.roleVersion ?? process.env.LIVEDESK_ROLE_VERSION),
+  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.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: 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 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',
+    manager: '',
+    pairToken: '',
+    slotNumber: normalizeSlotNumber(options.slot),
+    assignedHubId: normalizeString(options.assignedHubId ?? process.env.LIVEDESK_ASSIGNED_HUB_ID, 160),
+    endpointCandidates: [],
+    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,
-    agent: { requestedEngine: normalizeString(options.engine, 40), state: 'waiting', pid: null, engine: '' },
-    videoAcceleration: options.videoAcceleration && typeof options.videoAcceleration === 'object'
-      ? { ...options.videoAcceleration, busy: false }
-      : null,
-    lastError: '',
-    auth: {
-      lastAttemptAt: '',
-      lastResult: '',
-      lastError: '',
-      persisted: savedSessionPersisted,
-      email: savedAccountProfile.email,
-      name: savedAccountProfile.name,
-      avatarUrl: savedAccountProfile.avatarUrl
-    }
+    startup: false,
+    agent: { requestedEngine: normalizeString(options.engine, 40), state: 'waiting', pid: null, engine: '' },
+    videoAcceleration: options.videoAcceleration && typeof options.videoAcceleration === 'object'
+      ? { ...options.videoAcceleration, busy: false }
+      : null,
+    lastError: '',
+    auth: {
+      lastAttemptAt: '',
+      lastResult: '',
+      lastError: '',
+      persisted: savedSessionPersisted,
+      email: savedAccountProfile.email,
+      name: savedAccountProfile.name,
+      avatarUrl: savedAccountProfile.avatarUrl
+    }
   };
-  let completed = false;
-  let loggedOut = false;
-  let lastChoice = null;
+  let completed = false;
+  let loggedOut = false;
+  let lastChoice = null;
   let settleChoice;
   let rejectChoice;
   let server;
@@ -1287,219 +1226,219 @@ export function createClientRuntimeServer(options = {}) {
   const runtime = createRuntimeManager({
     role: 'client',
     state: RuntimeState.WAITING_AUTH,
-    authenticated: Boolean(savedSession?.access_token),
-    userId: savedSession?.user?.id || '',
+    authenticated: Boolean(savedSession?.access_token),
+    userId: savedSession?.user?.id || '',
     deviceId,
     appVersion,
     startedAt: new Date().toISOString(),
     runtimePid: process.pid
   });
-  runtime.emit('runtime.waiting-auth', { role: 'client' });
-
-  const requestDiagnosticRefresh = () => {
-    if (closed || options.diagnosticsEnabled === false) return Promise.resolve();
-    if (diagnosticRefreshInFlight) return diagnosticRefreshInFlight;
-    lastDiagnosticRequestAt = new Date().toISOString();
-    hardwareSnapshot = { ...hardwareSnapshot, collecting: true };
-    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 = {
-        // 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: errors.join(', ')
-      };
-
-      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 };
-      }
-      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;
-  };
-
-  const recordAuthAttempt = (result, error = '') => {
-    const message = normalizeString(error, 240);
-    state.auth = { ...state.auth, lastAttemptAt: new Date().toISOString(), lastResult: normalizeString(result, 80), lastError: message };
-    state.lastError = message;
-    if (message) state.message = `Client authentication needs attention: ${message}`;
-    runtime.emit('client.auth.session', { result: state.auth.lastResult, error: message });
-  };
-
-  const complete = (choice, message = 'Client credentials accepted. Finding the Hub.') => {
-    lastChoice = choice || lastChoice;
-    if (completed) {
-      if (choice?.session?.access_token) {
-        const accountProfile = readClientAccountProfile(choice.session);
-        runtime.setAuthenticated(true, choice.session.user?.id || '');
-        state.auth = {
-          ...state.auth,
-          lastAttemptAt: new Date().toISOString(),
-          lastResult: 'accepted',
-          lastError: '',
-          persisted: true,
-          email: accountProfile.email || state.auth.email,
-          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;
-    }
+  runtime.emit('runtime.waiting-auth', { role: 'client' });
+
+  const requestDiagnosticRefresh = () => {
+    if (closed || options.diagnosticsEnabled === false) return Promise.resolve();
+    if (diagnosticRefreshInFlight) return diagnosticRefreshInFlight;
+    lastDiagnosticRequestAt = new Date().toISOString();
+    hardwareSnapshot = { ...hardwareSnapshot, collecting: true };
+    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 = {
+        // 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: errors.join(', ')
+      };
+
+      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 };
+      }
+      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;
+  };
+
+  const recordAuthAttempt = (result, error = '') => {
+    const message = normalizeString(error, 240);
+    state.auth = { ...state.auth, lastAttemptAt: new Date().toISOString(), lastResult: normalizeString(result, 80), lastError: message };
+    state.lastError = message;
+    if (message) state.message = `Client authentication needs attention: ${message}`;
+    runtime.emit('client.auth.session', { result: state.auth.lastResult, error: message });
+  };
+
+  const complete = (choice, message = 'Client credentials accepted. Finding the Hub.') => {
+    lastChoice = choice || lastChoice;
+    if (completed) {
+      if (choice?.session?.access_token) {
+        const accountProfile = readClientAccountProfile(choice.session);
+        runtime.setAuthenticated(true, choice.session.user?.id || '');
+        state.auth = {
+          ...state.auth,
+          lastAttemptAt: new Date().toISOString(),
+          lastResult: 'accepted',
+          lastError: '',
+          persisted: true,
+          email: accountProfile.email || state.auth.email,
+          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;
+    }
     completed = true;
-    loggedOut = false;
-    state.connectedAt = new Date().toISOString();
-    state.manager = normalizeString(choice?.manager, 256);
-    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)
-      : [];
-    state.message = message;
-    state.lastError = '';
-    const accountProfile = readClientAccountProfile(choice?.session);
-    state.auth = {
-      ...state.auth,
-      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
-    };
+    loggedOut = false;
+    state.connectedAt = new Date().toISOString();
+    state.manager = normalizeString(choice?.manager, 256);
+    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)
+      : [];
+    state.message = message;
+    state.lastError = '';
+    const accountProfile = readClientAccountProfile(choice?.session);
+    state.auth = {
+      ...state.auth,
+      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
+    };
     runtime.setAuthenticated(Boolean(choice?.session?.access_token), choice?.session?.user?.id || '');
     runtime.update({ state: RuntimeState.RESOLVING_ROLE }, 'credentials-accepted');
     settleChoice?.(choice);
     settleChoice = null;
   };
 
-  const getState = () => {
-    const snapshot = runtime.getSnapshot();
-    const currentCpuTotals = readCpuTotals();
-    const cpuTotalDelta = Math.max(0, currentCpuTotals.total - previousCpuTotals.total);
-    const cpuIdleDelta = Math.max(0, currentCpuTotals.idle - previousCpuTotals.idle);
-    const cpuUsagePercent = cpuTotalDelta > 0 ? Math.max(0, Math.min(100, (1 - cpuIdleDelta / cpuTotalDelta) * 100)) : 0;
-    previousCpuTotals = currentCpuTotals;
-    const totalMemoryBytes = os.totalmem();
-    const freeMemoryBytes = os.freemem();
-    return {
+  const getState = () => {
+    const snapshot = runtime.getSnapshot();
+    const currentCpuTotals = readCpuTotals();
+    const cpuTotalDelta = Math.max(0, currentCpuTotals.total - previousCpuTotals.total);
+    const cpuIdleDelta = Math.max(0, currentCpuTotals.idle - previousCpuTotals.idle);
+    const cpuUsagePercent = cpuTotalDelta > 0 ? Math.max(0, Math.min(100, (1 - cpuIdleDelta / cpuTotalDelta) * 100)) : 0;
+    previousCpuTotals = currentCpuTotals;
+    const totalMemoryBytes = os.totalmem();
+    const freeMemoryBytes = os.freemem();
+    return {
       ok: true,
       role: 'client',
       state: snapshot.state,
       deviceId,
       deviceName,
       runtimeStarted: completed,
-      authenticated: snapshot.authenticated,
-      userId: snapshot.userId || '',
-      userEmail: state.auth.email || '',
-      userName: state.auth.name || '',
-      userAvatarUrl: state.auth.avatarUrl || '',
-      appVersion,
-      runtimeId: `client-${snapshot.runtimePid}-${snapshot.startedAt}`,
-      runtimePid: snapshot.runtimePid,
+      authenticated: snapshot.authenticated,
+      userId: snapshot.userId || '',
+      userEmail: state.auth.email || '',
+      userName: state.auth.name || '',
+      userAvatarUrl: state.auth.avatarUrl || '',
+      appVersion,
+      runtimeId: `client-${snapshot.runtimePid}-${snapshot.startedAt}`,
+      runtimePid: snapshot.runtimePid,
       startedAt: snapshot.startedAt,
-      route: state.route,
-      manager: state.manager,
-      slotNumber: state.slotNumber,
-      assignedHubId: state.assignedHubId,
-      endpointCandidates: state.endpointCandidates,
+      route: state.route,
+      manager: state.manager,
+      slotNumber: state.slotNumber,
+      assignedHubId: state.assignedHubId,
+      endpointCandidates: state.endpointCandidates,
       roleVersion: state.roleVersion,
       connectedAt: state.connectedAt,
-      connectionState: state.agent.state === 'running' ? 'connected' : completed ? 'connecting' : 'waiting-auth',
-      needsAuth: !snapshot.authenticated,
-      statusLabel: loggedOut ? 'Signed out' : state.agent.state === 'running' ? 'Agent running' : completed ? 'Finding Hub' : 'Waiting for auth',
-      message: state.message,
-      lastError: state.lastError,
-      auth: { ...state.auth },
-      startup: state.startup,
-      agent: { ...state.agent, pid: runtime.getSnapshot().agentPid },
-      videoAcceleration: state.videoAcceleration ? { ...state.videoAcceleration } : null,
-      system: {
-        platform: process.platform,
-        arch: process.arch,
-        osVersion: os.release(),
-        pid: process.pid,
-        cpuUsagePercent: Math.round(cpuUsagePercent * 10) / 10,
-        cpuLogicalCores: Math.max(1, os.cpus().length),
-        memoryTotalBytes: totalMemoryBytes,
-        memoryUsedBytes: Math.max(0, totalMemoryBytes - freeMemoryBytes),
-        uptimeSeconds: Math.max(0, Math.floor(os.uptime())),
-        gpus: hardwareSnapshot.gpus,
-        disks: hardwareSnapshot.disks,
-        network: networkSnapshot,
-        hardwareCollectedAt: hardwareSnapshot.collectedAt,
-        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()
-        }
-      },
+      connectionState: state.agent.state === 'running' ? 'connected' : completed ? 'connecting' : 'waiting-auth',
+      needsAuth: !snapshot.authenticated,
+      statusLabel: loggedOut ? 'Signed out' : state.agent.state === 'running' ? 'Agent running' : completed ? 'Finding Hub' : 'Waiting for auth',
+      message: state.message,
+      lastError: state.lastError,
+      auth: { ...state.auth },
+      startup: state.startup,
+      agent: { ...state.agent, pid: runtime.getSnapshot().agentPid },
+      videoAcceleration: state.videoAcceleration ? { ...state.videoAcceleration } : null,
+      system: {
+        platform: process.platform,
+        arch: process.arch,
+        osVersion: os.release(),
+        pid: process.pid,
+        cpuUsagePercent: Math.round(cpuUsagePercent * 10) / 10,
+        cpuLogicalCores: Math.max(1, os.cpus().length),
+        memoryTotalBytes: totalMemoryBytes,
+        memoryUsedBytes: Math.max(0, totalMemoryBytes - freeMemoryBytes),
+        uptimeSeconds: Math.max(0, Math.floor(os.uptime())),
+        gpus: hardwareSnapshot.gpus,
+        disks: hardwareSnapshot.disks,
+        network: networkSnapshot,
+        hardwareCollectedAt: hardwareSnapshot.collectedAt,
+        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',
         remoteInput: state.agent.state === 'running',
@@ -1528,385 +1467,366 @@ export function createClientRuntimeServer(options = {}) {
     }
   };
 
-  const handleRequest = async (req, res) => {
-    const requestUrl = new URL(req.url || '/', `http://${host}:${port}`);
-    const pathname = requestUrl.pathname;
-    const requestOrigin = normalizeString(req.headers.origin, 300);
-    const respondJson = (status, payload) => sendJson(res, status, payload, requestOrigin, port, trustedWebOrigins);
-    const isStaticAppRequest = !pathname.startsWith('/api/');
-    const allowReadOnlyCrossSite = READ_ONLY_CLIENT_API_PATHS.has(pathname);
-    if (!isTrustedLocalRequest(req, host, port, { allowStaticCrossSite: isStaticAppRequest, allowReadOnlyCrossSite, trustedWebOrigins })) {
-      runtime.emit('client.http.rejected', {
-        method: normalizeString(req.method, 12),
-        pathname: normalizeString(pathname, 160),
-        reason: 'untrusted-local-origin',
-        origin: requestOrigin,
-        fetchSite: normalizeString(req.headers['sec-fetch-site'], 40)
-      });
-      if (pathname === '/api/auth/session') recordAuthAttempt('rejected', 'untrusted-local-origin');
-      respondJson(403, { ok: false, error: 'untrusted-local-origin' });
-      return;
-    }
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204, {
-        'Access-Control-Allow-Origin': resolveCorsOrigin(requestOrigin, port, trustedWebOrigins),
-        'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-        'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-LiveDesk-CSRF',
-        'Access-Control-Allow-Private-Network': 'true',
-        Vary: 'Origin'
-      });
-      res.end();
-      return;
+  const handleRequest = async (req, res) => {
+    const requestUrl = new URL(req.url || '/', `http://${host}:${port}`);
+    const pathname = requestUrl.pathname;
+    const requestOrigin = normalizeString(req.headers.origin, 300);
+    const respondJson = (status, payload) => sendJson(res, status, payload, requestOrigin, port, trustedWebOrigins);
+    const isStaticAppRequest = !pathname.startsWith('/api/');
+    const allowReadOnlyCrossSite = READ_ONLY_CLIENT_API_PATHS.has(pathname);
+    if (!isTrustedLocalRequest(req, host, port, { allowStaticCrossSite: isStaticAppRequest, allowReadOnlyCrossSite, trustedWebOrigins })) {
+      runtime.emit('client.http.rejected', {
+        method: normalizeString(req.method, 12),
+        pathname: normalizeString(pathname, 160),
+        reason: 'untrusted-local-origin',
+        origin: requestOrigin,
+        fetchSite: normalizeString(req.headers['sec-fetch-site'], 40)
+      });
+      if (pathname === '/api/auth/session') recordAuthAttempt('rejected', 'untrusted-local-origin');
+      respondJson(403, { ok: false, error: 'untrusted-local-origin' });
+      return;
     }
-    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method || '') && req.headers['x-livedesk-csrf'] !== csrfToken) {
-      if (pathname === '/api/auth/session') recordAuthAttempt('rejected', 'csrf-token-required');
-      respondJson(403, { ok: false, error: 'csrf-token-required' });
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': resolveCorsOrigin(requestOrigin, port, trustedWebOrigins),
+        'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-LiveDesk-CSRF',
+        'Access-Control-Allow-Private-Network': 'true',
+        Vary: 'Origin'
+      });
+      res.end();
+      return;
+    }
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method || '') && req.headers['x-livedesk-csrf'] !== csrfToken) {
+      if (pathname === '/api/auth/session') recordAuthAttempt('rejected', 'csrf-token-required');
+      respondJson(403, { ok: false, error: 'csrf-token-required' });
       return;
     }
     if (pathname === '/api/health') {
-      respondJson(200, { ok: true, product: 'LiveDesk', role: 'client', timestamp: new Date().toISOString() });
+      respondJson(200, { ok: true, product: 'LiveDesk', role: 'client', timestamp: new Date().toISOString() });
+      return;
+    }
+    if (pathname === '/api/client/diagnostics') {
+      await requestDiagnosticRefresh();
+      respondJson(200, getState());
+      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;
+    }
+    if (pathname === '/api/auth/status') {
+      const snapshot = runtime.getSnapshot();
+      respondJson(200, {
+        ok: true,
+        authenticated: snapshot.authenticated,
+        userId: snapshot.userId || null,
+        userEmail: state.auth.email || null,
+        userName: state.auth.name || null,
+        userAvatarUrl: state.auth.avatarUrl || null,
+        role: 'client'
+      });
+      return;
+    }
+    if (pathname === '/auth/google' && req.method === 'GET') {
+      try {
+        if (runtime.getSnapshot().authenticated) {
+          res.writeHead(303, { Location: '/', 'Cache-Control': 'no-store' });
+          res.end();
+          return;
+        }
+        if (typeof options.beginGoogleSignIn !== 'function') {
+          throw new Error('client-google-sign-in-unavailable');
+        }
+        recordAuthAttempt('oauth-starting');
+        const redirectTo = `http://${host}:${port}/callback`;
+        const result = await options.beginGoogleSignIn(redirectTo);
+        const authorizationUrl = normalizeString(result?.url || result, 4000);
+        if (!authorizationUrl) throw new Error(result?.error || 'google-authorization-url-missing');
+        recordAuthAttempt('oauth-waiting');
+        res.writeHead(302, {
+          Location: authorizationUrl,
+          'Cache-Control': 'no-store',
+          'Referrer-Policy': 'no-referrer'
+        });
+        res.end();
+      } catch (error) {
+        const message = normalizeString(error?.message || error, 240);
+        recordAuthAttempt('rejected', message);
+        res.writeHead(303, { Location: `/?auth_error=${encodeURIComponent(message)}`, 'Cache-Control': 'no-store' });
+        res.end();
+      }
       return;
     }
-    if (pathname === '/api/client/diagnostics') {
-      await requestDiagnosticRefresh();
-      respondJson(200, getState());
-      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() });
+    if (pathname === '/callback' && req.method === 'GET') {
+      const providerError = normalizeString(
+        requestUrl.searchParams.get('error_description') || requestUrl.searchParams.get('error'),
+        240
+      );
+      const code = normalizeString(requestUrl.searchParams.get('code'), 2000);
+      try {
+        if (providerError) throw new Error(providerError);
+        if (!code) throw new Error('google-auth-code-missing');
+        if (typeof options.exchangeGoogleCode !== 'function') {
+          throw new Error('client-google-callback-unavailable');
+        }
+        recordAuthAttempt('oauth-exchanging');
+        const exchanged = await options.exchangeGoogleCode(code);
+        const sessionCandidate = exchanged?.session || exchanged;
+        const normalized = normalizeRuntimeAuthSession(sessionCandidate, { requireRefreshToken: true });
+        if (!normalized.ok) throw new Error(normalized.error);
+        const session = {
+          ...sessionCandidate,
+          ...mergeClientAccountProfile(normalized.session, sessionCandidate?.user)
+        };
+        if (!writeSavedSession(session)) throw new Error('refresh-token-required');
+        state.auth.persisted = true;
+        complete({ type: 'google', session }, 'Signed in. Finding the LiveDesk Hub.');
+        res.writeHead(303, { Location: '/', 'Cache-Control': 'no-store' });
+        res.end();
+      } catch (error) {
+        const message = normalizeString(error?.message || error, 240);
+        recordAuthAttempt('rejected', message);
+        res.writeHead(303, { Location: `/?auth_error=${encodeURIComponent(message)}`, 'Cache-Control': 'no-store' });
+        res.end();
+      }
       return;
     }
-    if (pathname === '/api/auth/status') {
-      const snapshot = runtime.getSnapshot();
-      respondJson(200, {
-        ok: true,
-        authenticated: snapshot.authenticated,
-        userId: snapshot.userId || null,
-        userEmail: state.auth.email || null,
-        userName: state.auth.name || null,
-        userAvatarUrl: state.auth.avatarUrl || null,
-        role: 'client'
-      });
-      return;
-    }
-    if (pathname === '/auth/google' && req.method === 'GET') {
-      try {
-        if (runtime.getSnapshot().authenticated) {
-          res.writeHead(303, { Location: '/', 'Cache-Control': 'no-store' });
-          res.end();
-          return;
-        }
-        if (typeof options.beginGoogleSignIn !== 'function') {
-          throw new Error('client-google-sign-in-unavailable');
-        }
-        recordAuthAttempt('oauth-starting');
-        const redirectTo = `http://${host}:${port}/callback`;
-        const result = await options.beginGoogleSignIn(redirectTo);
-        const authorizationUrl = normalizeString(result?.url || result, 4000);
-        if (!authorizationUrl) throw new Error(result?.error || 'google-authorization-url-missing');
-        recordAuthAttempt('oauth-waiting');
-        res.writeHead(302, {
-          Location: authorizationUrl,
-          'Cache-Control': 'no-store',
-          'Referrer-Policy': 'no-referrer'
-        });
-        res.end();
-      } catch (error) {
-        const message = normalizeString(error?.message || error, 240);
-        recordAuthAttempt('rejected', message);
-        res.writeHead(303, { Location: `/?auth_error=${encodeURIComponent(message)}`, 'Cache-Control': 'no-store' });
-        res.end();
-      }
-      return;
-    }
-    if (pathname === '/callback' && req.method === 'GET') {
-      const providerError = normalizeString(
-        requestUrl.searchParams.get('error_description') || requestUrl.searchParams.get('error'),
-        240
-      );
-      const code = normalizeString(requestUrl.searchParams.get('code'), 2000);
-      try {
-        if (providerError) throw new Error(providerError);
-        if (!code) throw new Error('google-auth-code-missing');
-        if (typeof options.exchangeGoogleCode !== 'function') {
-          throw new Error('client-google-callback-unavailable');
-        }
-        recordAuthAttempt('oauth-exchanging');
-        const exchanged = await options.exchangeGoogleCode(code);
-        const sessionCandidate = exchanged?.session || exchanged;
-        const normalized = normalizeRuntimeAuthSession(sessionCandidate, { requireRefreshToken: true });
-        if (!normalized.ok) throw new Error(normalized.error);
-        const session = {
-          ...sessionCandidate,
-          ...mergeClientAccountProfile(normalized.session, sessionCandidate?.user)
-        };
-        if (!writeSavedSession(session)) throw new Error('refresh-token-required');
-        state.auth.persisted = true;
-        complete({ type: 'google', session }, 'Signed in. Finding the LiveDesk Hub.');
-        res.writeHead(303, { Location: '/', 'Cache-Control': 'no-store' });
-        res.end();
-      } catch (error) {
-        const message = normalizeString(error?.message || error, 240);
-        recordAuthAttempt('rejected', message);
-        res.writeHead(303, { Location: `/?auth_error=${encodeURIComponent(message)}`, 'Cache-Control': 'no-store' });
-        res.end();
-      }
-      return;
-    }
-    if (pathname === '/api/auth/session' && req.method === 'POST') {
-      const body = parseJsonBody(await readBody(req));
-      const normalized = normalizeRuntimeAuthSession(body, { requireRefreshToken: true });
-      if (!normalized.ok) {
-        recordAuthAttempt('rejected', normalized.error);
-        respondJson(400, { ok: false, error: normalized.error });
-        return;
-      }
-      const accessToken = normalized.session.access_token;
-      recordAuthAttempt('verifying');
-      const verifyResponse = await fetch(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/user`, {
+    if (pathname === '/api/auth/session' && req.method === 'POST') {
+      const body = parseJsonBody(await readBody(req));
+      const normalized = normalizeRuntimeAuthSession(body, { requireRefreshToken: true });
+      if (!normalized.ok) {
+        recordAuthAttempt('rejected', normalized.error);
+        respondJson(400, { ok: false, error: normalized.error });
+        return;
+      }
+      const accessToken = normalized.session.access_token;
+      recordAuthAttempt('verifying');
+      const verifyResponse = await fetch(`${SUPABASE_URL.replace(/\/+$/, '')}/auth/v1/user`, {
         headers: { apikey: SUPABASE_PUBLISHABLE_KEY, Authorization: `Bearer ${accessToken}`, Accept: 'application/json' }
       });
-      if (!verifyResponse.ok) {
-        recordAuthAttempt('rejected', `supabase-user-verification-failed:${verifyResponse.status}`);
-        respondJson(401, { ok: false, error: `supabase-user-verification-failed:${verifyResponse.status}` });
+      if (!verifyResponse.ok) {
+        recordAuthAttempt('rejected', `supabase-user-verification-failed:${verifyResponse.status}`);
+        respondJson(401, { ok: false, error: `supabase-user-verification-failed:${verifyResponse.status}` });
+        return;
+      }
+      const verifiedUser = await verifyResponse.json().catch(() => ({}));
+      const verifiedSession = {
+        ...normalized.session,
+        user: {
+          id: normalizeString(verifiedUser?.id || body.user?.id || body.userId, 160),
+          email: normalizeString(verifiedUser?.email || body.user?.email || body.email, 320)
+        }
+      };
+      const session = mergeClientAccountProfile(verifiedSession, verifiedUser);
+      try {
+        if (!writeSavedSession(session)) throw new Error('refresh-token-required');
+        state.auth.persisted = true;
+      } catch (error) {
+        const message = `session-persistence-failed:${normalizeString(error?.message || error, 160)}`;
+        recordAuthAttempt('rejected', message);
+        respondJson(500, { ok: false, error: message });
         return;
       }
-      const verifiedUser = await verifyResponse.json().catch(() => ({}));
-      const verifiedSession = {
-        ...normalized.session,
-        user: {
-          id: normalizeString(verifiedUser?.id || body.user?.id || body.userId, 160),
-          email: normalizeString(verifiedUser?.email || body.user?.email || body.email, 320)
-        }
-      };
-      const session = mergeClientAccountProfile(verifiedSession, verifiedUser);
-      try {
-        if (!writeSavedSession(session)) throw new Error('refresh-token-required');
-        state.auth.persisted = true;
-      } catch (error) {
-        const message = `session-persistence-failed:${normalizeString(error?.message || error, 160)}`;
-        recordAuthAttempt('rejected', message);
-        respondJson(500, { ok: false, error: message });
-        return;
-      }
-      complete({ type: 'google', session }, 'Signed in. Finding the LiveDesk Hub.');
-      respondJson(200, { ok: true, authenticated: true, persisted: true, role: 'client' });
+      complete({ type: 'google', session }, 'Signed in. Finding the LiveDesk Hub.');
+      respondJson(200, { ok: true, authenticated: true, persisted: true, role: 'client' });
+      return;
+    }
+    if (pathname === '/api/auth/session' && req.method === 'DELETE') {
+      clearSavedSession();
+      loggedOut = true;
+      completed = false;
+      lastChoice = null;
+      state.manager = '';
+      state.message = 'Saved sign-in was cleared. Sign in again to start the Client.';
+      state.lastError = '';
+      state.auth = {
+        lastAttemptAt: new Date().toISOString(),
+        lastResult: 'cleared',
+        lastError: '',
+        persisted: false,
+        email: '',
+        name: '',
+        avatarUrl: ''
+      };
+      runtime.setAuthenticated(false);
+      respondJson(200, { ok: true, authenticated: false, role: 'client' });
       return;
-    }
-    if (pathname === '/api/auth/session' && req.method === 'DELETE') {
-      const activeSession = lastChoice?.session || savedSession || readSavedSession();
-      const providerLogout = await revokeClientProviderSession(activeSession, {
-        revokeProviderSession: options.revokeProviderSession,
-        fetchImpl: options.fetchImpl
-      });
-      clearSavedSession();
-      loggedOut = true;
-      completed = false;
-      lastChoice = null;
-      state.manager = '';
-      state.message = 'Saved sign-in was cleared. Sign in again to start the Client.';
-      state.lastError = '';
-      state.auth = {
-        lastAttemptAt: new Date().toISOString(),
-        lastResult: 'cleared',
-        lastError: '',
-        persisted: false,
-        email: '',
-        name: '',
-        avatarUrl: ''
-      };
-      runtime.setAuthenticated(false);
-      respondJson(providerLogout.ok ? 200 : 502, {
-        ok: providerLogout.ok,
-        authenticated: false,
-        localCleared: true,
-        role: 'client',
-        providerLogout
-      });
-      return;
     }
     if (pathname === '/api/runtime/restart' && req.method === 'POST') {
       runtime.emit('runtime.restart.requested', { role: 'client' });
-      respondJson(200, { ok: true, restarting: true, role: 'client' });
+      respondJson(200, { ok: true, restarting: true, role: 'client' });
       setTimeout(() => options.onRestart?.(), 150);
       return;
     }
-    if (pathname === '/api/runtime/shutdown' && req.method === 'POST') {
-      runtime.emit('runtime.shutdown.requested', { role: 'client' });
-      respondJson(200, { ok: true, shuttingDown: true, role: 'client' });
-      setTimeout(() => options.onShutdown?.(), 150);
-      return;
-    }
-    if (pathname === '/api/client/slot' && req.method === 'POST') {
-      const body = parseJsonBody(await readBody(req));
-      const slotNumber = normalizeSlotNumber(body.slotNumber ?? body.slot);
-      if (!slotNumber) {
-        respondJson(400, { ok: false, error: 'invalid-slot-number', slotNumber: state.slotNumber });
-        return;
-      }
-      if (!state.manager || !state.pairToken || state.agent.state !== 'running') {
-        respondJson(409, { ok: false, error: 'hub-not-connected', slotNumber: state.slotNumber });
-        return;
-      }
-      if (typeof options.assignSlot !== 'function') {
-        respondJson(409, { ok: false, error: 'slot-assignment-unavailable', slotNumber: state.slotNumber });
-        return;
-      }
-      runtime.emit('client.slot.assignment-requested', {
-        deviceId,
-        previousSlotNumber: state.slotNumber,
-        slotNumber
-      });
-      try {
-        const result = await options.assignSlot({
-          manager: state.manager,
-          pairToken: state.pairToken,
-          deviceId,
-          slotNumber
-        });
-        if (result?.ok !== true) {
-          const error = normalizeString(result?.error, 120) || 'slot-assignment-failed';
-          runtime.emit('client.slot.assignment-rejected', {
-            deviceId,
-            slotNumber,
-            error,
-            conflictDeviceId: normalizeString(result?.conflict?.deviceId, 160)
-          });
-          respondJson(error === 'slot-taken' ? 409 : 502, {
-            ...(result && typeof result === 'object' ? result : {}),
-            ok: false,
-            error,
-            slotNumber: state.slotNumber
-          });
-          return;
-        }
-        state.slotNumber = slotNumber;
-        state.message = `Slot ${String(slotNumber).padStart(3, '0')} saved. Reconnecting this Client.`;
-        runtime.emit('client.slot.assigned', { deviceId, slotNumber });
-        respondJson(200, { ...getState(), ...result, ok: true, slotNumber });
-      } catch (error) {
-        const message = normalizeString(error?.message || error, 240) || 'slot-assignment-failed';
-        runtime.emit('client.slot.assignment-failed', { deviceId, slotNumber, error: message });
-        respondJson(502, { ok: false, error: message, slotNumber: state.slotNumber });
-      }
-      return;
-    }
-    if (pathname === '/api/client/video-acceleration/install' && req.method === 'POST') {
-      if (process.platform !== 'linux') {
-        respondJson(409, { ok: false, error: 'linux-video-acceleration-only' });
-        return;
-      }
-      if (state.videoAcceleration?.busy) {
-        respondJson(409, { ok: false, error: 'video-acceleration-install-in-progress', ...getState() });
-        return;
-      }
-      if (typeof options.installVideoAcceleration !== 'function') {
-        respondJson(409, { ok: false, error: 'video-acceleration-install-unavailable' });
-        return;
-      }
-      state.videoAcceleration = {
-        ...(state.videoAcceleration || {}),
-        supported: true,
-        state: 'installing',
-        busy: true,
-        ready: false,
-        error: '',
-        message: 'Installing Linux hardware video support…'
-      };
-      runtime.emit('client.video-acceleration.installing', {
-        packageManager: normalizeString(state.videoAcceleration.packageManager?.id, 40)
-      });
-      try {
-        const result = await options.installVideoAcceleration();
-        state.videoAcceleration = {
-          ...(result && typeof result === 'object' ? result : {}),
-          busy: false
-        };
-        const ok = state.videoAcceleration.ready === true;
-        runtime.emit(ok ? 'client.video-acceleration.ready' : 'client.video-acceleration.failed', {
-          encoder: normalizeString(state.videoAcceleration.encoder, 80),
-          driver: normalizeString(state.videoAcceleration.driver, 80),
-          error: normalizeString(state.videoAcceleration.error, 240)
-        });
-        respondJson(ok ? 200 : 409, { ...getState(), ok });
-        if (ok && state.videoAcceleration.restartAgent) {
-          setTimeout(() => options.onVideoAccelerationReady?.(state.videoAcceleration), 150);
-        }
-      } catch (error) {
-        state.videoAcceleration = {
-          ...(state.videoAcceleration || {}),
-          state: 'error',
-          busy: false,
-          ready: false,
-          error: normalizeString(error?.message || error, 320)
-        };
-        runtime.emit('client.video-acceleration.failed', { error: state.videoAcceleration.error });
-        respondJson(409, { ok: false, ...getState(), error: state.videoAcceleration.error });
-      }
-      return;
-    }
-    if (pathname === '/api/runtime/switch-role' && req.method === 'POST') {
+    if (pathname === '/api/runtime/shutdown' && req.method === 'POST') {
+      runtime.emit('runtime.shutdown.requested', { role: 'client' });
+      respondJson(200, { ok: true, shuttingDown: true, role: 'client' });
+      setTimeout(() => options.onShutdown?.(), 150);
+      return;
+    }
+    if (pathname === '/api/client/slot' && req.method === 'POST') {
+      const body = parseJsonBody(await readBody(req));
+      const slotNumber = normalizeSlotNumber(body.slotNumber ?? body.slot);
+      if (!slotNumber) {
+        respondJson(400, { ok: false, error: 'invalid-slot-number', slotNumber: state.slotNumber });
+        return;
+      }
+      if (!state.manager || !state.pairToken || state.agent.state !== 'running') {
+        respondJson(409, { ok: false, error: 'hub-not-connected', slotNumber: state.slotNumber });
+        return;
+      }
+      if (typeof options.assignSlot !== 'function') {
+        respondJson(409, { ok: false, error: 'slot-assignment-unavailable', slotNumber: state.slotNumber });
+        return;
+      }
+      runtime.emit('client.slot.assignment-requested', {
+        deviceId,
+        previousSlotNumber: state.slotNumber,
+        slotNumber
+      });
+      try {
+        const result = await options.assignSlot({
+          manager: state.manager,
+          pairToken: state.pairToken,
+          deviceId,
+          slotNumber
+        });
+        if (result?.ok !== true) {
+          const error = normalizeString(result?.error, 120) || 'slot-assignment-failed';
+          runtime.emit('client.slot.assignment-rejected', {
+            deviceId,
+            slotNumber,
+            error,
+            conflictDeviceId: normalizeString(result?.conflict?.deviceId, 160)
+          });
+          respondJson(error === 'slot-taken' ? 409 : 502, {
+            ...(result && typeof result === 'object' ? result : {}),
+            ok: false,
+            error,
+            slotNumber: state.slotNumber
+          });
+          return;
+        }
+        state.slotNumber = slotNumber;
+        state.message = `Slot ${String(slotNumber).padStart(3, '0')} saved. Reconnecting this Client.`;
+        runtime.emit('client.slot.assigned', { deviceId, slotNumber });
+        respondJson(200, { ...getState(), ...result, ok: true, slotNumber });
+      } catch (error) {
+        const message = normalizeString(error?.message || error, 240) || 'slot-assignment-failed';
+        runtime.emit('client.slot.assignment-failed', { deviceId, slotNumber, error: message });
+        respondJson(502, { ok: false, error: message, slotNumber: state.slotNumber });
+      }
+      return;
+    }
+    if (pathname === '/api/client/video-acceleration/install' && req.method === 'POST') {
+      if (process.platform !== 'linux') {
+        respondJson(409, { ok: false, error: 'linux-video-acceleration-only' });
+        return;
+      }
+      if (state.videoAcceleration?.busy) {
+        respondJson(409, { ok: false, error: 'video-acceleration-install-in-progress', ...getState() });
+        return;
+      }
+      if (typeof options.installVideoAcceleration !== 'function') {
+        respondJson(409, { ok: false, error: 'video-acceleration-install-unavailable' });
+        return;
+      }
+      state.videoAcceleration = {
+        ...(state.videoAcceleration || {}),
+        supported: true,
+        state: 'installing',
+        busy: true,
+        ready: false,
+        error: '',
+        message: 'Installing Linux hardware video support…'
+      };
+      runtime.emit('client.video-acceleration.installing', {
+        packageManager: normalizeString(state.videoAcceleration.packageManager?.id, 40)
+      });
+      try {
+        const result = await options.installVideoAcceleration();
+        state.videoAcceleration = {
+          ...(result && typeof result === 'object' ? result : {}),
+          busy: false
+        };
+        const ok = state.videoAcceleration.ready === true;
+        runtime.emit(ok ? 'client.video-acceleration.ready' : 'client.video-acceleration.failed', {
+          encoder: normalizeString(state.videoAcceleration.encoder, 80),
+          driver: normalizeString(state.videoAcceleration.driver, 80),
+          error: normalizeString(state.videoAcceleration.error, 240)
+        });
+        respondJson(ok ? 200 : 409, { ...getState(), ok });
+        if (ok && state.videoAcceleration.restartAgent) {
+          setTimeout(() => options.onVideoAccelerationReady?.(state.videoAcceleration), 150);
+        }
+      } catch (error) {
+        state.videoAcceleration = {
+          ...(state.videoAcceleration || {}),
+          state: 'error',
+          busy: false,
+          ready: false,
+          error: normalizeString(error?.message || error, 320)
+        };
+        runtime.emit('client.video-acceleration.failed', { error: state.videoAcceleration.error });
+        respondJson(409, { ok: false, ...getState(), error: state.videoAcceleration.error });
+      }
+      return;
+    }
+    if (pathname === '/api/runtime/switch-role' && req.method === 'POST') {
       const body = parseJsonBody(await readBody(req));
       if (String(body.role || '').trim().toLowerCase() !== 'hub') {
-        respondJson(400, { ok: false, error: 'client-can-only-transition-to-hub' });
+        respondJson(400, { ok: false, error: 'client-can-only-transition-to-hub' });
         return;
       }
       try {
-        const result = await options.changeRole?.(
-          'hub',
-          runtime.getSnapshot(),
-          lastChoice?.session || savedSession || null
-        );
-        respondJson(result?.ok === false ? 409 : 200, result || { ok: false, error: 'role-change-unavailable' });
+        const result = await options.changeRole?.('hub', runtime.getSnapshot());
+        respondJson(result?.ok === false ? 409 : 200, result || { ok: false, error: 'role-change-unavailable' });
       } catch (error) {
-        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
+        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
       }
       return;
     }
     if (pathname === '/api/client/role' && req.method === 'POST') {
       const body = parseJsonBody(await readBody(req));
       if (String(body.role || '').trim().toLowerCase() !== 'hub') {
-        respondJson(400, { ok: false, error: 'client-can-only-transition-to-hub' });
+        respondJson(400, { ok: false, error: 'client-can-only-transition-to-hub' });
         return;
       }
       try {
-        const result = await options.changeRole?.(
-          'hub',
-          runtime.getSnapshot(),
-          lastChoice?.session || savedSession || null
-        );
-        respondJson(result?.ok === false ? 409 : 200, result || { ok: false, error: 'role-change-unavailable' });
+        const result = await options.changeRole?.('hub', runtime.getSnapshot());
+        respondJson(result?.ok === false ? 409 : 200, result || { ok: false, error: 'role-change-unavailable' });
       } catch (error) {
-        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
+        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
       }
       return;
-    }
-    if (pathname === '/api/client/reconnect' && req.method === 'POST') {
-      const body = parseJsonBody(await readBody(req));
-      if (body.onlyIfWaiting === true && state.agent.state === 'running') {
-        respondJson(200, { ok: true, skipped: true, reason: 'already-connected', ...getState() });
-        return;
-      }
-      const previousManager = state.manager;
-      state.manager = '';
-      state.agent.state = 'reconnecting';
-      state.lastError = '';
-      state.message = 'Refreshing the LiveDesk Hub discovery now.';
-      runtime.update({ state: RuntimeState.RESOLVING_ROLE }, 'client-reconnect-requested');
-      runtime.emit('client.reconnect.requested', { deviceId, previousManager: previousManager || '' });
-      await options.onReconnect?.();
-      respondJson(200, { ok: true, ...getState() });
+    }
+    if (pathname === '/api/client/reconnect' && req.method === 'POST') {
+      const body = parseJsonBody(await readBody(req));
+      if (body.onlyIfWaiting === true && state.agent.state === 'running') {
+        respondJson(200, { ok: true, skipped: true, reason: 'already-connected', ...getState() });
+        return;
+      }
+      const previousManager = state.manager;
+      state.manager = '';
+      state.agent.state = 'reconnecting';
+      state.lastError = '';
+      state.message = 'Refreshing the LiveDesk Hub discovery now.';
+      runtime.update({ state: RuntimeState.RESOLVING_ROLE }, 'client-reconnect-requested');
+      runtime.emit('client.reconnect.requested', { deviceId, previousManager: previousManager || '' });
+      await options.onReconnect?.();
+      respondJson(200, { ok: true, ...getState() });
       return;
     }
     if (pathname === '/api/client/disconnect' && req.method === 'POST') {
       await options.onDisconnect?.();
       state.manager = '';
       state.agent.state = 'waiting';
-      respondJson(200, { ok: true, ...getState() });
+      respondJson(200, { ok: true, ...getState() });
       return;
     }
     if (pathname === '/api/client/pin' && req.method === 'POST') {
@@ -1917,181 +1837,181 @@ export function createClientRuntimeServer(options = {}) {
         if (!resolved) throw new Error('pin-not-resolved');
         state.message = 'PIN accepted. Starting the Client.';
         complete({ type: 'pin', ...resolved }, state.message);
-        respondJson(200, { ok: true, ...getState() });
+        respondJson(200, { ok: true, ...getState() });
       } catch (error) {
-        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
+        respondJson(409, { ok: false, error: normalizeString(error?.message || error) });
       }
       return;
     }
     if (pathname.startsWith('/api/')) {
-      respondJson(409, runtimeRoleError('client', 'client'));
+      respondJson(409, runtimeRoleError('client', 'client'));
       return;
     }
     serveApp(req, res, pathname);
   };
 
-  const start = () => new Promise((resolveStart, rejectStart) => {
-    if (process.env.LIVEDESK_DESKTOP_HOST === '1') clearSavedSession();
-    let settled = false;
-    server = createServer((req, res) => {
+  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);
+        if (!res.headersSent) sendJson(res, 500, { ok: false, error: normalizeString(error?.message || error) }, req.headers.origin, port, trustedWebOrigins);
         else res.end();
-      });
-    });
-    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(() => {
-          complete(initialChoice, initialChoiceMessage);
-        });
-      } else {
-        const saved = normalizeRuntimeAuthSession(savedSession, { requireRefreshToken: true });
-        if (saved.ok) {
-          setImmediate(() => {
-            void (async () => {
-              try {
-                // Older persisted sessions kept only id/email on `user`, while
-                // Supabase still carries Google name/avatar claims in the
-                // access-token payload. Recover those display-only claims
-                // locally before any best-effort network hydration.
-                const normalizedSession = mergeClientAccountProfile(saved.session, savedSession);
-                const hydratedSession = await hydrateClientAccountProfile(normalizedSession);
-                if (!writeSavedSession(hydratedSession)) throw new Error('refresh-token-required');
-                state.auth.persisted = true;
-                complete({ type: 'google', session: hydratedSession }, 'Saved sign-in found. Finding the LiveDesk Hub.');
-              } catch (error) {
-                recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
-              }
-            })();
-          });
-        }
-      }
-      resolveStart();
-    });
-  });
-
-  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 {
+      });
+    });
+    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(() => {
+          complete(initialChoice, initialChoiceMessage);
+        });
+      } else {
+        const saved = normalizeRuntimeAuthSession(savedSession, { requireRefreshToken: true });
+        if (saved.ok) {
+          setImmediate(() => {
+            void (async () => {
+              try {
+                // Older persisted sessions kept only id/email on `user`, while
+                // Supabase still carries Google name/avatar claims in the
+                // access-token payload. Recover those display-only claims
+                // locally before any best-effort network hydration.
+                const normalizedSession = mergeClientAccountProfile(saved.session, savedSession);
+                const hydratedSession = await hydrateClientAccountProfile(normalizedSession);
+                if (!writeSavedSession(hydratedSession)) throw new Error('refresh-token-required');
+                state.auth.persisted = true;
+                complete({ type: 'google', session: hydratedSession }, 'Saved sign-in found. Finding the LiveDesk Hub.');
+              } catch (error) {
+                recordAuthAttempt('rejected', `session-persistence-failed:${normalizeString(error?.message || error, 160)}`);
+              }
+            })();
+          });
+        }
+      }
+      resolveStart();
+    });
+  });
+
+  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,
-    get url() { return `http://${host}:${port}/`; },
-    getLastChoice() { return lastChoice; },
-    acceptChoice(choice, message) {
-      complete(choice, message);
-      return lastChoice;
-    },
-    update(patch = {}) {
+    waitForChoice,
+    start,
+    get url() { return `http://${host}:${port}/`; },
+    getLastChoice() { return lastChoice; },
+    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 };
         runtime.setAgentPid(Number.isInteger(patch.agent.pid) ? patch.agent.pid : runtime.getSnapshot().agentPid);
         if (patch.agent.state === 'running') runtime.update({ state: RuntimeState.RUNNING }, 'agent-running');
       }
-      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 (Object.prototype.hasOwnProperty.call(patch, 'assignedHubId')) {
-        state.assignedHubId = normalizeString(patch.assignedHubId, 160);
-      }
+      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 (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;
     },
-    close() {
-      if (!runtimeClosePromise) runtimeClosePromise = closeRuntime();
-      return runtimeClosePromise;
-    },
+    close() {
+      if (!runtimeClosePromise) runtimeClosePromise = closeRuntime();
+      return runtimeClosePromise;
+    },
     getRoleRestartRequest() { return options.getRoleRestartRequest?.() || null; }
   };
 }