@livedesk/hub 0.1.5 → 0.1.7

package/src/server.js

@@ -3,13 +3,14 @@
 import express from 'express';
 import crypto from 'node:crypto';
 import { createServer } from 'node:http';
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { WebSocketServer } from 'ws';
-import { createRemoteHub } from './remote-hub.js';
-import { Mode4AtlasSession } from './mode4-atlas.js';
+import { createRemoteHub } from './remote-hub.js';
+import { buildMode4AtlasSessionKey, Mode4AtlasPool, planMode4AtlasInputTransitions } from './mode4-atlas-pool.js';
+import { resolveMode4AtlasTileSize } from './mode4-atlas-sizing.js';
 import { createHubFilesystem } from './filesystem/hub-filesystem.js';
 import { createHubTransferJobs } from './filesystem/transfer-jobs.js';
 import { createHubSharedFolders } from './filesystem/shared-folders.js';
@@ -59,19 +60,31 @@ const runtimeManager = createHubRuntime({
   runtimePid: process.pid
 });
 runtimeManager.emit('runtime.started', { role: runtimeRole, pid: process.pid });
-const frameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_BACKPRESSURE_BYTES', 64 * 1024 * 1024);
-const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 256);
-const controlFrameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_CONTROL_FRAME_WS_QUEUE_PACKETS', 4);
-const frameClientDrainBudgetPackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_DRAIN_BUDGET_PACKETS', 64);
-const frameStreamStopGraceMs = readPositiveIntegerEnv('LIVEDESK_FRAME_STREAM_STOP_GRACE_MS', 1500);
-const mode5FrameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_BACKPRESSURE_BYTES', 2 * 1024 * 1024);
-const mode5FrameQueuePackets = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_QUEUE_PACKETS', 2);
-const audioBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_AUDIO_WS_BACKPRESSURE_BYTES', 96 * 1024);
-const frameClients = new Set();
+const frameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_BACKPRESSURE_BYTES', 8 * 1024 * 1024);
+const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 4);
+const controlFrameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_CONTROL_FRAME_WS_QUEUE_PACKETS', 2);
+const frameStreamStopGraceMs = readPositiveIntegerEnv('LIVEDESK_FRAME_STREAM_STOP_GRACE_MS', 1500);
+const mode5FrameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_BACKPRESSURE_BYTES', 2 * 1024 * 1024);
+const mode5FrameQueuePackets = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_QUEUE_PACKETS', 2);
+const audioBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_AUDIO_WS_BACKPRESSURE_BYTES', 96 * 1024);
+const webSocketHeartbeatMs = readPositiveIntegerEnv('LIVEDESK_BROWSER_WS_HEARTBEAT_MS', 15_000);
+const hubShutdownGraceMs = readPositiveIntegerEnv('LIVEDESK_HUB_SHUTDOWN_GRACE_MS', 1_500);
+const hubShutdownTimeoutMs = Math.max(
+  hubShutdownGraceMs + 1_000,
+  readPositiveIntegerEnv('LIVEDESK_HUB_SHUTDOWN_TIMEOUT_MS', 8_000)
+);
+const frameClients = new Set();
 const frameClientsByDeviceId = new Map();
 const frameWildcardClients = new Set();
 const pendingFrameStreamStops = new Map();
-const atlasClients = new Map();
+const atlasClients = new Map();
+const atlasPool = new Mode4AtlasPool({
+  onStatus: status => {
+    if (status?.type !== 'log') return;
+    const logger = status.level === 'warn' ? console.warn : console.log;
+    logger(`[LiveDesk Hub] ${status.message}`);
+  }
+});
 const inputClients = new Set();
 const audioClients = new Set();
 const FREE_DEVICE_LIMIT = 5;
@@ -94,6 +107,10 @@ const supabasePublishableKey = String(configuredSupabaseKey || PRODUCTION_SUPABA
 const SUPABASE_AUTH_TIMEOUT_MS = process.env.LIVEDESK_AUTH_TEST_MODE === '1'
   ? readPositiveIntegerEnv('LIVEDESK_AUTH_TEST_TIMEOUT_MS', AUTH_REQUEST_TIMEOUT_MS)
   : AUTH_REQUEST_TIMEOUT_MS;
+const CLIENT_AUTH_STORAGE_KEY = 'livedesk.client.supabase.auth';
+const runtimeAuthStatePath = process.env.LIVEDESK_DESKTOP_HOST === '1'
+  ? ''
+  : String(process.env.LIVEDESK_AUTH_STATE_PATH || '').trim();
 const testLicensePlan = process.env.LIVEDESK_TEST_MODE === '1'
   && ['ltd', 'pro'].includes(String(process.env.LIVEDESK_TEST_LICENSE_PLAN || '').toLowerCase())
   ? String(process.env.LIVEDESK_TEST_LICENSE_PLAN).toLowerCase()
@@ -111,9 +128,10 @@ let verifiedLicense = {
   verifiedAt: 0
 };
 let frameClientSeq = 0;
-let inputClientSeq = 0;
-let audioClientSeq = 0;
+let inputClientSeq = 0;
+let audioClientSeq = 0;
 let liveDeskUpdateManager = null;
+let hubTransferJobs = null;
 const HUB_HOST_TARGET_LEASE_MS = Math.max(5000, readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_LEASE_MS', 60_000));
 const HUB_HOST_TARGET_RENEW_MS = Math.max(1000, Math.min(
   readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_RENEW_MS', 20_000),
@@ -124,6 +142,7 @@ const hubWakeBaseUrl = String(process.env.LIVEDESK_WAKE_URL || 'https://livedesk
 const HUB_WAKE_NOTIFY_RETRY_MS = 60_000;
 let hubHostTargetRenewTimer = null;
 let hubHostTargetRenewInFlight = false;
+let roleTransitionTakeoverPending = process.env.LIVEDESK_ROLE_TAKEOVER === '1';
 let hubHostTargetLeaseState = {
   state: 'idle',
   lastAttemptAt: '',
@@ -148,8 +167,9 @@ function readPositiveIntegerEnv(name, fallback) {
   return Number.isFinite(value) && value > 0 ? Math.round(value) : fallback;
 }
 
-function handleRemoteHubEvent(type, event) {
-  liveDeskUpdateManager?.handleRemoteEvent(type, event);
+function handleRemoteHubEvent(type, event) {
+  liveDeskUpdateManager?.handleRemoteEvent(type, event);
+  hubTransferJobs?.handleRemoteEvent(type, event);
   if (type === 'RemoteInputApplied') {
     for (const ws of inputClients) {
       sendJson(ws, {
@@ -159,16 +179,16 @@ function handleRemoteHubEvent(type, event) {
     }
     return;
   }
-  if (type === 'RemoteInputError') {
+  if (type === 'RemoteInputError') {
     for (const ws of inputClients) {
       sendJson(ws, {
         type: 'RemoteInputError',
         ...event
       });
-    }
-    return;
-  }
-  if (type === 'RemoteDeviceConnected' || type === 'RemoteDeviceDisconnected') {
+    }
+    return;
+  }
+  if (type === 'RemoteDeviceConnected' || type === 'RemoteDeviceDisconnected') {
     connectedDeviceCount = Number(remoteHub.getStatus({ includeSecrets: false }).connectedDeviceCount || 0);
   }
   if (type !== 'RemoteDeviceConnected') {
@@ -293,11 +313,82 @@ function normalizeSessionExpiryMs(value) {
   return numeric < 100_000_000_000 ? Math.round(numeric * 1000) : Math.round(numeric);
 }
 
+function readRuntimeAuthState() {
+  if (!runtimeAuthStatePath) return {};
+  try {
+    const state = JSON.parse(readFileSync(runtimeAuthStatePath, 'utf8'));
+    return state && typeof state === 'object' ? state : {};
+  } catch {
+    return {};
+  }
+}
+
+function readPersistedRuntimeSession(state = readRuntimeAuthState()) {
+  try {
+    const raw = state?.[CLIENT_AUTH_STORAGE_KEY];
+    const session = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return session && typeof session === 'object' ? session : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePrivateRuntimeAuthState(state) {
+  if (!runtimeAuthStatePath) return false;
+  mkdirSync(dirname(runtimeAuthStatePath), { recursive: true });
+  const temporaryPath = `${runtimeAuthStatePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    writeFileSync(temporaryPath, JSON.stringify(state, null, 2), 'utf8');
+    try { chmodSync(temporaryPath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+    renameSync(temporaryPath, runtimeAuthStatePath);
+    try { chmodSync(runtimeAuthStatePath, 0o600); } catch { /* Windows profile ACLs apply instead. */ }
+    return true;
+  } catch (error) {
+    try { rmSync(temporaryPath, { force: true }); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function persistRuntimeSession(session) {
+  if (!runtimeAuthStatePath) return false;
+  const state = readRuntimeAuthState();
+  const previous = readPersistedRuntimeSession(state) || {};
+  const incomingUserId = String(session?.user?.id || '').trim();
+  const previousUserId = String(previous?.user?.id || '').trim();
+  const sameUser = !incomingUserId || !previousUserId || incomingUserId === previousUserId;
+  const refreshToken = String(
+    session?.refresh_token
+    || (sameUser ? previous?.refresh_token : '')
+    || ''
+  ).trim();
+  const normalized = normalizeRuntimeAuthSession({
+    ...previous,
+    ...session,
+    refresh_token: refreshToken,
+    user: {
+      ...(sameUser && previous?.user && typeof previous.user === 'object' ? previous.user : {}),
+      ...(session?.user && typeof session.user === 'object' ? session.user : {})
+    }
+  }, { requireRefreshToken: true });
+  if (!normalized.ok) return false;
+  state[CLIENT_AUTH_STORAGE_KEY] = JSON.stringify(normalized.session);
+  writePrivateRuntimeAuthState(state);
+  return true;
+}
+
+function clearPersistedRuntimeSession() {
+  if (!runtimeAuthStatePath) return false;
+  const state = readRuntimeAuthState();
+  delete state[CLIENT_AUTH_STORAGE_KEY];
+  return writePrivateRuntimeAuthState(state);
+}
+
 function clearRuntimeSession() {
   runtimeAccessToken = '';
   runtimeRefreshToken = '';
   runtimeAccessTokenExpiresAt = 0;
   runtimeManager.setAuthenticated(false);
+  try { clearPersistedRuntimeSession(); } catch { /* runtime auth is already invalid */ }
 }
 
 async function getRuntimeAccessToken() {
@@ -343,6 +434,15 @@ async function getRuntimeAccessToken() {
   runtimeRefreshToken = String(refreshed?.refresh_token || refreshToken).trim();
   runtimeAccessTokenExpiresAt = normalizeSessionExpiryMs(refreshed?.expires_at)
     || (Number(refreshed?.expires_in) > 0 ? Date.now() + Number(refreshed.expires_in) * 1000 : 0);
+  try {
+    persistRuntimeSession({
+      access_token: runtimeAccessToken,
+      refresh_token: runtimeRefreshToken,
+      expires_at: Math.floor(runtimeAccessTokenExpiresAt / 1000)
+    });
+  } catch (error) {
+    console.warn(`[LiveDesk Hub] Refreshed session persistence failed: ${error?.message || error}`);
+  }
   return runtimeAccessToken;
 }
 
@@ -500,7 +600,7 @@ const remoteHub = createRemoteHub({
   }
 });
 
-function requestHubRestart(request = {}) {
+function requestHubRestart(request = {}) {
   const requestPath = String(process.env.LIVEDESK_HUB_UPDATE_REQUEST_PATH || '').trim();
   if (!requestPath) {
     return { ok: false, error: 'hub-launcher-restart-unavailable' };
@@ -517,10 +617,76 @@ function requestHubRestart(request = {}) {
     return { ok: true };
   } catch (error) {
     return { ok: false, error: `hub-restart-request-failed: ${error instanceof Error ? error.message : String(error)}` };
-  }
-}
-
-if (process.env.LIVEDESK_DESKTOP_HOST !== '1') {
+  }
+}
+
+const HUB_RESTART_RESULT_STAGES = new Set([
+  'supervisor-starting',
+  'preflight-failed',
+  'waiting-for-old-launcher',
+  'old-launcher-exited',
+  'target-attempt',
+  'target-failed',
+  'fallback-attempt',
+  'fallback-failed',
+  'updated',
+  'restored',
+  'failed'
+]);
+const HUB_RESTART_RESULT_OUTCOMES = new Set(['in-progress', 'updated', 'restored', 'failed']);
+
+function readHubRestartResult() {
+  const resultPath = String(process.env.LIVEDESK_HUB_UPDATE_RESULT_PATH || '').trim();
+  if (!resultPath || !existsSync(resultPath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(resultPath, 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    const operationId = String(raw.operationId || '').trim().slice(0, 160);
+    const stage = String(raw.stage || '').trim();
+    const outcome = String(raw.outcome || '').trim();
+    if (!operationId || !HUB_RESTART_RESULT_STAGES.has(stage) || !HUB_RESTART_RESULT_OUTCOMES.has(outcome)) {
+      return null;
+    }
+    const text = (value, maximum = 200) => String(value || '').trim().slice(0, maximum);
+    const positiveInteger = value => {
+      const numeric = Number(value);
+      return Number.isInteger(numeric) && numeric > 0 ? numeric : undefined;
+    };
+    return {
+      operationId,
+      stage,
+      outcome,
+      targetVersion: text(raw.targetVersion),
+      fallbackVersion: text(raw.fallbackVersion),
+      appVersion: text(raw.appVersion),
+      attempt: positiveInteger(raw.attempt),
+      previousRuntimePid: positiveInteger(raw.previousRuntimePid),
+      supervisorPid: positiveInteger(raw.supervisorPid),
+      launcherPid: positiveInteger(raw.launcherPid),
+      runtimePid: positiveInteger(raw.runtimePid),
+      startedAt: text(raw.startedAt, 64),
+      updatedAt: text(raw.updatedAt, 64),
+      completedAt: text(raw.completedAt, 64),
+      error: text(raw.error, 4_000)
+    };
+  } catch {
+    return null;
+  }
+}
+
+function getLiveDeskUpdateStatus() {
+  const restartResult = readHubRestartResult();
+  liveDeskUpdateManager?.reconcileHubRestartResult(restartResult);
+  return {
+    ...(liveDeskUpdateManager?.getStatus() || {
+      updateAvailable: false,
+      state: 'unavailable'
+    }),
+    restartResult
+  };
+}
+
+if (process.env.LIVEDESK_DESKTOP_HOST !== '1') {
   liveDeskUpdateManager = createLiveDeskUpdateManager({
     remoteHub,
     currentManagerVersion: process.env.LIVEDESK_MANAGER_VERSION || packageInfo.version,
@@ -1044,23 +1210,58 @@ async function synchronizeAgentEnablement() {
 }
 
 const hubFilesystem = createHubFilesystem();
-const hubTransferJobs = createHubTransferJobs({
-  filesystem: hubFilesystem,
-  remoteHub,
-  maxConcurrent: Number(process.env.LIVEDESK_MAX_FILE_JOBS || 2)
-});
+hubTransferJobs = createHubTransferJobs({
+  filesystem: hubFilesystem,
+  remoteHub,
+  maxConcurrent: Number(process.env.LIVEDESK_MAX_FILE_JOBS || 2),
+  commandResultTimeoutMs: readPositiveIntegerEnv('LIVEDESK_FILE_CHUNK_ACK_TIMEOUT_MS', 30_000)
+});
 const hubSharedFolders = createHubSharedFolders({
   filesystem: hubFilesystem,
   transferJobs: hubTransferJobs,
   remoteHub
 });
 
-const app = express();
-const httpServer = createServer(app);
-const frameWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
-const atlasWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
-const inputWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
-const audioWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const app = express();
+const httpServer = createServer(app);
+const httpConnections = new Set();
+const frameWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const atlasWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const inputWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const audioWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const browserWebSocketServers = [frameWss, atlasWss, inputWss, audioWss];
+
+httpServer.on('connection', socket => {
+  httpConnections.add(socket);
+  socket.once('close', () => httpConnections.delete(socket));
+});
+
+for (const wss of browserWebSocketServers) {
+  wss.on('connection', ws => {
+    ws.liveDeskHeartbeatAlive = true;
+    ws.on('pong', () => {
+      ws.liveDeskHeartbeatAlive = true;
+    });
+  });
+}
+
+const browserWebSocketHeartbeatTimer = setInterval(() => {
+  for (const wss of browserWebSocketServers) {
+    for (const ws of wss.clients) {
+      if (ws.liveDeskHeartbeatAlive === false) {
+        ws.terminate();
+        continue;
+      }
+      ws.liveDeskHeartbeatAlive = false;
+      try {
+        ws.ping();
+      } catch {
+        ws.terminate();
+      }
+    }
+  }
+}, webSocketHeartbeatMs);
+browserWebSocketHeartbeatTimer.unref?.();
 
 function normalizeHostname(value) {
   return String(value || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
@@ -1340,25 +1541,27 @@ function forgetWebSocketClient(ws) {
   }
 }
 
-function safeWebSocketSend(ws, payload, options = undefined) {
-  if (!ws || ws.readyState !== 1) {
-    return false;
-  }
-
-  try {
-    ws.send(payload, options, err => {
-      if (err) {
-        forgetWebSocketClient(ws);
-      }
-    });
-    return true;
-  } catch {
-    forgetWebSocketClient(ws);
-    return false;
-  }
-}
+function safeWebSocketSend(ws, payload, options = undefined, onComplete = undefined) {
+  if (!ws || ws.readyState !== 1) {
+    return false;
+  }
+
+  try {
+    ws.send(payload, options, err => {
+      if (err) {
+        forgetWebSocketClient(ws);
+      }
+      onComplete?.(err || null);
+    });
+    return true;
+  } catch (error) {
+    forgetWebSocketClient(ws);
+    onComplete?.(error);
+    return false;
+  }
+}
 
-function unregisterFrameClient(ws) {
+function unregisterFrameClient(ws) {
   if (!ws) {
     return;
   }
@@ -1373,10 +1576,16 @@ function unregisterFrameClient(ws) {
     if (clients.size === 0) {
       frameClientsByDeviceId.delete(deviceId);
     }
-  }
-  frameWildcardClients.delete(ws);
-  ws.liveDeskFrameSendLane?.queue?.splice?.(0);
-}
+  }
+  frameWildcardClients.delete(ws);
+  ws.liveDeskExpectedStreamBindingsByDeviceId?.clear?.();
+  const lane = ws.liveDeskFrameSendLane;
+  if (lane) {
+    clearTimeout(lane.retryTimer);
+    lane.retryTimer = null;
+    lane.queue.splice(0);
+  }
+}
 
 function hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose = '') {
   if (!streamId) {
@@ -1476,11 +1685,12 @@ function registerFrameClient(ws) {
 function ensureFrameClientSendLane(ws) {
   if (!ws.liveDeskFrameSendLane) {
     ws.liveDeskFrameSendLane = {
-      queue: [],
-      draining: false,
-      dropped: 0,
-      awaitingKeyFrames: new Set()
-    };
+      queue: [],
+      sending: false,
+      retryTimer: null,
+      dropped: 0,
+      awaitingKeyFrames: new Set()
+    };
   }
   return ws.liveDeskFrameSendLane;
 }
@@ -1528,39 +1738,48 @@ function dropQueuedMode5FrameForLane(lane, deviceId) {
   return true;
 }
 
-function drainFrameClientSendLane(ws) {
-  const lane = ws.liveDeskFrameSendLane;
-  if (!lane || lane.draining) {
-    return;
-  }
-  lane.draining = true;
-  setImmediate(() => {
-    lane.draining = false;
-    if (!ws || ws.readyState !== ws.OPEN) {
-      lane.queue.length = 0;
-      return;
-    }
-
-    let sent = 0;
-    while (lane.queue.length > 0 && sent < frameClientDrainBudgetPackets) {
-      if (ws.bufferedAmount > frameBackpressureBytes) {
-        ws.liveDeskFrameBackpressured = true;
-        break;
-      }
-      const item = lane.queue.shift();
-      if (!item) {
-        continue;
-      }
-      ws.liveDeskFrameBackpressured = false;
-      safeWebSocketSend(ws, item.packet, { binary: true });
-      sent += 1;
-    }
-
-    if (lane.queue.length > 0 && ws.readyState === ws.OPEN) {
-      drainFrameClientSendLane(ws);
-    }
-  });
-}
+function drainFrameClientSendLane(ws) {
+  const lane = ws.liveDeskFrameSendLane;
+  if (!lane || lane.sending) {
+    return;
+  }
+  clearTimeout(lane.retryTimer);
+  lane.retryTimer = null;
+  if (!ws || ws.readyState !== ws.OPEN) {
+    lane.queue.length = 0;
+    return;
+  }
+  const item = lane.queue[0];
+  if (!item) {
+    return;
+  }
+  const backpressureBytes = item.isMode5 ? mode5FrameBackpressureBytes : frameBackpressureBytes;
+  if (ws.bufferedAmount > backpressureBytes) {
+    ws.liveDeskFrameBackpressured = true;
+    lane.retryTimer = setTimeout(() => {
+      lane.retryTimer = null;
+      drainFrameClientSendLane(ws);
+    }, 10);
+    lane.retryTimer.unref?.();
+    return;
+  }
+
+  lane.queue.shift();
+  lane.sending = true;
+  ws.liveDeskFrameBackpressured = false;
+  const accepted = safeWebSocketSend(ws, item.packet, { binary: true }, error => {
+    lane.sending = false;
+    if (error || ws.readyState !== ws.OPEN) {
+      lane.queue.length = 0;
+      return;
+    }
+    drainFrameClientSendLane(ws);
+  });
+  if (!accepted) {
+    lane.sending = false;
+    lane.queue.length = 0;
+  }
+}
 
 function enqueueFramePacketForClient(ws, packet, meta) {
   if (!ws || ws.readyState !== ws.OPEN) {
@@ -1610,7 +1829,7 @@ function enqueueFramePacketForClient(ws, packet, meta) {
   return true;
 }
 
-function updateFrameSubscription(ws, payload = {}) {
+function updateFrameSubscription(ws, payload = {}) {
   const previousDeviceIds = ws.liveDeskDeviceIds instanceof Set
     ? new Set(ws.liveDeskDeviceIds)
     : new Set();
@@ -1620,14 +1839,18 @@ function updateFrameSubscription(ws, payload = {}) {
   registerFrameClient(ws);
   ws.liveDeskAutoStart = /^(1|true|yes|on|live)$/i.test(String(payload.autoStartLive ?? payload.startLive ?? ''));
   ws.liveDeskLiveOptions = normalizeLiveOptions(payload);
-  if (!(ws.liveDeskStreamIdsByDeviceId instanceof Map)) {
-    ws.liveDeskStreamIdsByDeviceId = new Map();
-  }
-  for (const subscribedDeviceId of ws.liveDeskStreamIdsByDeviceId.keys()) {
-    if (!ws.liveDeskDeviceIds.has(subscribedDeviceId)) {
-      ws.liveDeskStreamIdsByDeviceId.delete(subscribedDeviceId);
-    }
-  }
+  if (!(ws.liveDeskStreamIdsByDeviceId instanceof Map)) {
+    ws.liveDeskStreamIdsByDeviceId = new Map();
+  }
+  if (!(ws.liveDeskExpectedStreamBindingsByDeviceId instanceof Map)) {
+    ws.liveDeskExpectedStreamBindingsByDeviceId = new Map();
+  }
+  for (const subscribedDeviceId of ws.liveDeskStreamIdsByDeviceId.keys()) {
+    if (!ws.liveDeskDeviceIds.has(subscribedDeviceId)) {
+      ws.liveDeskStreamIdsByDeviceId.delete(subscribedDeviceId);
+      ws.liveDeskExpectedStreamBindingsByDeviceId.delete(subscribedDeviceId);
+    }
+  }
   sendJson(ws, {
     type: 'RemoteFrameSubscription',
     timestamp: new Date().toISOString(),
@@ -1681,15 +1904,46 @@ function startFrameSubscriptionLive(ws, reason = 'subscribe', onlyDeviceId = '',
       reuseExisting: liveOptions.forceRestart !== true
         && (liveOptions.reuseExisting === true || reason === 'subscribe' || reason === 'watchdog'),
       silentReuse: reason === 'watchdog' && liveOptions.forceRestart !== true
-    });
-    if (result?.ok) {
-      ws.liveDeskStreamIdsByDeviceId.set(deviceId, result.streamId);
-      cancelPendingFrameStreamStop(deviceId, result.streamId, String(liveOptions.streamPurpose || 'wall'));
-      started.push({ deviceId, streamId: result.streamId, fps: result.fps, reused: result.reused === true });
-    } else {
-      ws.liveDeskStreamIdsByDeviceId.delete(deviceId);
-      skipped.push({ deviceId, reason: result?.error || 'start-failed' });
-    }
+    });
+    if (result?.ok) {
+      const expectedBinding = {
+        deviceId,
+        sessionId: String(result.sessionId || device.sessionId || ''),
+        streamId: String(result.streamId || ''),
+        streamPurpose: String(result.streamPurpose || liveOptions.streamPurpose || 'wall'),
+        commandId: String(result.commandId || ''),
+        captureGeneration: Number(result.captureGeneration || 0),
+        monitorIndex: Number(result.monitorIndex || 0),
+        readySent: false
+      };
+      const activeStream = device?.activeLiveStream;
+      const reusedFrameReady = result.reused === true
+        && result.ready === true
+        && Number(result.framesReceived ?? activeStream?.framesReceived ?? 0) > 0
+        && String(activeStream?.streamId || expectedBinding.streamId) === expectedBinding.streamId
+        && String(activeStream?.commandId || expectedBinding.commandId) === expectedBinding.commandId
+        && Number(activeStream?.captureGeneration || expectedBinding.captureGeneration) === expectedBinding.captureGeneration;
+      expectedBinding.readySent = reusedFrameReady;
+      ws.liveDeskStreamIdsByDeviceId.set(deviceId, result.streamId);
+      ws.liveDeskExpectedStreamBindingsByDeviceId.set(deviceId, expectedBinding);
+      cancelPendingFrameStreamStop(deviceId, result.streamId, String(liveOptions.streamPurpose || 'wall'));
+      started.push({
+        deviceId: expectedBinding.deviceId,
+        sessionId: expectedBinding.sessionId,
+        streamId: expectedBinding.streamId,
+        streamPurpose: expectedBinding.streamPurpose,
+        commandId: expectedBinding.commandId,
+        captureGeneration: expectedBinding.captureGeneration,
+        monitorIndex: expectedBinding.monitorIndex,
+        ready: reusedFrameReady,
+        fps: result.fps,
+        reused: result.reused === true
+      });
+    } else {
+      ws.liveDeskStreamIdsByDeviceId.delete(deviceId);
+      ws.liveDeskExpectedStreamBindingsByDeviceId.delete(deviceId);
+      skipped.push({ deviceId, reason: result?.error || 'start-failed' });
+    }
   }
   if (reason === 'watchdog' && !started.some(item => item.reused !== true)) {
     return;
@@ -1749,10 +2003,13 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     kind: frameEvent.kind || 'live',
     deviceId: frameEvent.deviceId || frame.deviceId || '',
     frameSeq: Number(frame.frameSeq || 0) || 0,
-    streamFrameSeq: Number(frame.streamFrameSeq || 0) || 0,
-    streamId: frame.streamId || '',
-    commandId: frame.commandId || '',
-    width: Number(frame.width || 0) || 0,
+    streamFrameSeq: Number(frame.streamFrameSeq || 0) || 0,
+    streamId: frame.streamId || '',
+    commandId: frame.commandId || '',
+    sessionId: frame.sessionId || '',
+    captureGeneration: Number(frame.captureGeneration || 0) || 0,
+    streamPurpose: frame.streamPurpose || '',
+    width: Number(frame.width || 0) || 0,
     height: Number(frame.height || 0) || 0,
     sourceWidth: Number(frame.sourceWidth || 0) || 0,
     sourceHeight: Number(frame.sourceHeight || 0) || 0,
@@ -1812,9 +2069,13 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     sameContentStreak: Number(frame.sameContentStreak || 0) || 0,
     layoutVersion: Number(frame.layoutVersion || 0) || 0,
     atlasComposeMs: Number(frame.atlasComposeMs || 0) || 0,
-    atlasPoolStarved: Number(frame.atlasPoolStarved || 0) || 0,
-    atlasReadyTiles: Number(frame.atlasReadyTiles || 0) || 0,
-    atlasTileCount: Number(frame.atlasTileCount || 0) || 0
+    atlasPoolStarved: Number(frame.atlasPoolStarved || 0) || 0,
+    atlasReadyTiles: Number(frame.atlasReadyTiles || 0) || 0,
+    atlasTileCount: Number(frame.atlasTileCount || 0) || 0,
+    atlasInputRevision: Number(frame.atlasInputRevision || 0) || 0,
+    atlasSourceNewestAtEpochMs: Number(frame.atlasSourceNewestAtEpochMs || 0) || 0,
+    atlasSourceOldestAtEpochMs: Number(frame.atlasSourceOldestAtEpochMs || 0) || 0,
+    atlasSourceMaxAgeMs: Number(frame.atlasSourceMaxAgeMs || 0) || 0
   };
   const metaBuffer = Buffer.from(JSON.stringify(metadata), 'utf8');
   const header = Buffer.allocUnsafe(4);
@@ -1860,10 +2121,8 @@ function buildRemoteAudioBinaryPacket(audioEvent) {
   return Buffer.concat([header, metaBuffer, payload], 4 + metaBuffer.length + payload.length);
 }
 
-function broadcastRemoteBinaryFrame(frameEvent) {
-  for (const session of atlasClients.values()) {
-    session.ingest(frameEvent);
-  }
+function broadcastRemoteBinaryFrame(frameEvent) {
+  atlasPool.ingest(frameEvent);
   const deviceId = String(frameEvent?.deviceId || frameEvent?.frame?.deviceId || '').trim();
   if (!deviceId || frameClients.size === 0) {
     return;
@@ -1879,18 +2138,40 @@ function broadcastRemoteBinaryFrame(frameEvent) {
   const isH264 = String(frame.codec || frame.mimeType || frame.format || '').toLowerCase().includes('h264')
     || String(frame.frameMode || frame.mode || '').toLowerCase() === 'mode3-h264-hw';
   const isMode5 = String(frame.frameMode || frame.mode || '').toLowerCase() === 'mode5-lzo-delta';
-  const isKeyFrame = frame.isKeyFrame === true || String(frame.chunkType || '').toLowerCase() === 'key';
-  const frameSeq = Number(frame.frameSeq || 0) || 0;
-  for (const client of targetClients) {
-    if (client.readyState !== client.OPEN) {
-      continue;
-    }
-    const expectedStreamId = client.liveDeskStreamIdsByDeviceId instanceof Map
-      ? client.liveDeskStreamIdsByDeviceId.get(deviceId)
-      : '';
-    if (expectedStreamId && String(frame.streamId || '') !== expectedStreamId) {
-      continue;
-    }
+  const isKeyFrame = frame.isKeyFrame === true || String(frame.chunkType || '').toLowerCase() === 'key';
+  const frameSeq = Number(frame.frameSeq || 0) || 0;
+  let sharedPacket = null;
+  for (const client of targetClients) {
+    if (client.readyState !== client.OPEN) {
+      continue;
+    }
+    const expectedBinding = client.liveDeskExpectedStreamBindingsByDeviceId instanceof Map
+      ? client.liveDeskExpectedStreamBindingsByDeviceId.get(deviceId)
+      : null;
+    if (!expectedBinding
+      || String(frame.streamId || '') !== expectedBinding.streamId
+      || String(frame.sessionId || '') !== expectedBinding.sessionId
+      || String(frame.commandId || '') !== expectedBinding.commandId
+      || Number(frame.captureGeneration || 0) !== expectedBinding.captureGeneration
+      || String(frame.streamPurpose || '') !== expectedBinding.streamPurpose
+      || Number(frame.monitorIndex || 0) !== expectedBinding.monitorIndex) {
+      continue;
+    }
+    if (!expectedBinding.readySent) {
+      expectedBinding.readySent = sendJson(client, {
+        type: 'RemoteFrameStreamReady',
+        deviceId,
+        sessionId: expectedBinding.sessionId,
+        streamId: expectedBinding.streamId,
+        streamPurpose: expectedBinding.streamPurpose,
+        commandId: expectedBinding.commandId,
+        captureGeneration: expectedBinding.captureGeneration,
+        monitorIndex: expectedBinding.monitorIndex
+      });
+      if (!expectedBinding.readySent) {
+        continue;
+      }
+    }
     const lane = ensureFrameClientSendLane(client);
     if (client.liveDeskFrameBackpressured && isH264 && !isKeyFrame) {
       lane.dropped += 1;
@@ -1898,13 +2179,11 @@ function broadcastRemoteBinaryFrame(frameEvent) {
       client.liveDeskFrameBackpressureDrops = Number(client.liveDeskFrameBackpressureDrops || 0) + 1;
       continue;
     }
-    const packet = buildRemoteFrameBinaryPacket(frameEvent, {
-      hubClientDropped: lane.dropped
-    });
-    if (!packet) {
-      continue;
-    }
-    enqueueFramePacketForClient(client, packet, { deviceId, frameSeq, isH264, isMode5, isKeyFrame });
+    sharedPacket ||= buildRemoteFrameBinaryPacket(frameEvent);
+    if (!sharedPacket) {
+      continue;
+    }
+    enqueueFramePacketForClient(client, sharedPacket, { deviceId, frameSeq, isH264, isMode5, isKeyFrame });
   }
 }
 
@@ -1977,9 +2256,13 @@ function sendMode4AtlasFrame(ws, output) {
       encoderGeneration,
       layoutVersion: Number(metadata.layoutVersion || 0),
       atlasComposeMs: Number(metadata.composeMs || 0),
-      atlasPoolStarved: Number(metadata.poolStarved || 0),
-      atlasReadyTiles: Number(metadata.readyTileCount || 0),
-      atlasTileCount: Number(metadata.tileCount || 0)
+      atlasPoolStarved: Number(metadata.poolStarved || 0),
+      atlasReadyTiles: Number(metadata.readyTileCount || 0),
+      atlasTileCount: Number(metadata.tileCount || 0),
+      atlasInputRevision: Number(metadata.inputRevision || 0),
+      atlasSourceNewestAtEpochMs: Number(metadata.sourceNewestAtEpochMs || 0),
+      atlasSourceOldestAtEpochMs: Number(metadata.sourceOldestAtEpochMs || 0),
+      atlasSourceMaxAgeMs: Number(metadata.sourceMaxAgeMs || 0)
     }
   };
   const lane = ensureFrameClientSendLane(ws);
@@ -1988,7 +2271,15 @@ function sendMode4AtlasFrame(ws, output) {
     lane.awaitingKeyFrames.add('__livedesk_mode4_atlas__');
     return;
   }
-  const packet = buildRemoteFrameBinaryPacket(frameEvent, { hubClientDropped: lane.dropped });
+  const packetCacheKey = `${streamId}:${frameSeq}`;
+  let packet = output.liveDeskBinaryPacketKey === packetCacheKey
+    ? output.liveDeskBinaryPacket
+    : null;
+  if (!packet) {
+    packet = buildRemoteFrameBinaryPacket(frameEvent);
+    output.liveDeskBinaryPacketKey = packetCacheKey;
+    output.liveDeskBinaryPacket = packet;
+  }
   if (packet) {
     enqueueFramePacketForClient(ws, packet, {
       deviceId: '__livedesk_mode4_atlas__',
@@ -1999,67 +2290,114 @@ function sendMode4AtlasFrame(ws, output) {
   }
 }
 
-function configureMode4Atlas(ws, payload = {}) {
-  const deviceIds = normalizeDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId).slice(0, 100);
-  const captureDeviceIds = normalizeDeviceIds(payload.captureDeviceIds ?? payload.inputDeviceIds ?? deviceIds)
-    .filter(deviceId => deviceIds.includes(deviceId));
-  const monitorSelections = normalizeMonitorSelections(payload.monitorSelections);
-  const sharpTiles = Number(payload.tileWidth) >= 480 || Number(payload.tileHeight) >= 270;
-  const tileWidth = sharpTiles ? 480 : 320;
-  const tileHeight = sharpTiles ? 270 : 180;
-  const previousInputDeviceIds = ws.liveDeskAtlasInputDeviceIds instanceof Set
-    ? new Set(ws.liveDeskAtlasInputDeviceIds)
-    : new Set(deviceIds);
-  ws.liveDeskAtlasDeviceIds = new Set(deviceIds);
-  ws.liveDeskAtlasInputDeviceIds = new Set(captureDeviceIds);
-  ws.liveDeskAtlasInputOptions = { tileWidth, tileHeight, monitorSelections };
-  ws.liveDeskAtlasSession.configure({
-    deviceIds,
-    inputDeviceIds: captureDeviceIds,
-    width: clampNumber(payload.width, 640, 3840, 1920),
-    height: clampNumber(payload.height, 360, 2160, 1080),
+function configureMode4Atlas(ws, payload = {}) {
+  const deviceIds = normalizeDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId).slice(0, 100);
+  const captureDeviceIds = normalizeDeviceIds(payload.captureDeviceIds ?? payload.inputDeviceIds ?? deviceIds)
+    .filter(deviceId => deviceIds.includes(deviceId));
+  const monitorSelections = normalizeMonitorSelections(payload.monitorSelections);
+  const width = clampNumber(payload.width, 640, 3840, 1920);
+  const height = clampNumber(payload.height, 360, 2160, 1080);
+  const tileSize = resolveMode4AtlasTileSize({
+    requestedWidth: payload.tileWidth,
+    requestedHeight: payload.tileHeight,
+    deviceCount: deviceIds.length,
+    atlasWidth: width,
+    atlasHeight: height
+  });
+  const tileWidth = tileSize.width;
+  const tileHeight = tileSize.height;
+  const inputFps = clampNumber(payload.inputFps, 1, 30, 8);
+  const previousInputDeviceIds = ws.liveDeskAtlasInputDeviceIds instanceof Set
+    ? new Set(ws.liveDeskAtlasInputDeviceIds)
+    : new Set();
+  const previousInputOptions = ws.liveDeskAtlasInputOptions || {};
+  const atlasConfig = {
+    deviceIds,
+    // Composition ownership is independent from capture ownership. Keeping
+    // every layout device ingestible lets a paused/reused input retain its
+    // latest tile while only the changed device restarts capture.
+    inputDeviceIds: deviceIds,
+    width,
+    height,
     tileWidth,
     tileHeight,
-    fps: clampNumber(payload.fps, 1, 30, 20)
-  });
-  for (const deviceId of previousInputDeviceIds) {
-    if (ws.liveDeskAtlasInputDeviceIds.has(deviceId)) {
-      continue;
-    }
-    stopMode4AtlasInput(ws, deviceId, 'atlas-input-paused');
-  }
-  for (const deviceId of captureDeviceIds) {
-    startMode4AtlasInput(ws, deviceId, 'atlas-configure');
-  }
-  sendJson(ws, {
-    type: 'Mode4AtlasSubscription',
-    deviceIds,
+    fps: clampNumber(payload.fps, 1, 30, 20),
+    monitorSelections
+  };
+  const previousHandle = ws.liveDeskAtlasHandle;
+  const nextKey = buildMode4AtlasSessionKey(atlasConfig);
+  if (!previousHandle || previousHandle.key !== nextKey) {
+    const nextHandle = atlasPool.acquire(atlasConfig, {
+      onFrame: output => sendMode4AtlasFrame(ws, output),
+      onLayout: layout => sendJson(ws, { ...layout, type: 'Mode4AtlasLayout' }),
+      onStatus: status => sendJson(ws, { ...status, type: 'Mode4AtlasStatus' })
+    });
+    ws.liveDeskAtlasHandle = nextHandle;
+    ws.liveDeskAtlasSession = nextHandle.session;
+    ws.liveDeskAtlasStreamId = nextHandle.streamId;
+    atlasClients.set(ws, nextHandle);
+    previousHandle?.release?.();
+  }
+  ws.liveDeskAtlasDeviceIds = new Set(deviceIds);
+  ws.liveDeskAtlasInputDeviceIds = new Set(captureDeviceIds);
+  ws.liveDeskAtlasInputOptions = { tileWidth, tileHeight, inputFps, monitorSelections };
+  const inputTransitions = planMode4AtlasInputTransitions({
+    inputDeviceIds: [...previousInputDeviceIds],
+    tileWidth: previousInputOptions.tileWidth,
+    tileHeight: previousInputOptions.tileHeight,
+    inputFps: previousInputOptions.inputFps,
+    monitorSelections: previousInputOptions.monitorSelections
+  }, {
+    inputDeviceIds: captureDeviceIds,
+    tileWidth,
+    tileHeight,
+    inputFps,
+    monitorSelections
+  });
+  for (const deviceId of inputTransitions.stop) {
+    stopMode4AtlasInput(ws, deviceId, 'atlas-input-paused');
+  }
+  for (const deviceId of inputTransitions.start) {
+    startMode4AtlasInput(ws, deviceId, 'atlas-input-started');
+  }
+  for (const deviceId of inputTransitions.restart) {
+    startMode4AtlasInput(ws, deviceId, 'atlas-input-changed', {
+      forceRestart: true
+    });
+  }
+  sendJson(ws, {
+    type: 'Mode4AtlasSubscription',
+    streamId: ws.liveDeskAtlasStreamId,
+    deviceIds,
     captureDeviceIds,
     inputMode: 'mode2-lzo',
-    outputMode: 'mode4-h264-atlas',
-    tileWidth,
-    tileHeight,
-    timestamp: new Date().toISOString()
+    outputMode: 'mode4-h264-atlas',
+    tileWidth,
+    tileHeight,
+    inputFps,
+    timestamp: new Date().toISOString()
   });
 }
 
-function startMode4AtlasInput(ws, deviceId, reason = 'atlas-configure') {
-  const options = ws?.liveDeskAtlasInputOptions;
-  if (!options || !ws.liveDeskAtlasInputDeviceIds?.has(deviceId)) return { ok: false, error: 'atlas-device-not-configured' };
-  return remoteHub.startLiveStream(deviceId, {
-    fps: 8,
+function startMode4AtlasInput(ws, deviceId, reason = 'atlas-configure', { forceRestart = false } = {}) {
+  const options = ws?.liveDeskAtlasInputOptions;
+  if (!options || !ws.liveDeskAtlasInputDeviceIds?.has(deviceId)) return { ok: false, error: 'atlas-device-not-configured' };
+  return remoteHub.startLiveStream(deviceId, {
+    fps: options.inputFps,
     maxWidth: options.tileWidth,
     maxHeight: options.tileHeight,
     quality: 60,
     mode: 'mode2-lzo',
     frameMode: 'mode2-lzo',
-    streamPurpose: 'atlas',
-    monitorIndex: Number(options.monitorSelections?.[deviceId] || 0),
-    reuseExisting: false,
-    silentReuse: true,
-    restartReason: reason
-  });
-}
+    streamPurpose: 'atlas',
+    monitorIndex: Number(options.monitorSelections?.[deviceId] || 0),
+    reuseExisting: !forceRestart,
+    forceRestart,
+    restartToken: forceRestart ? `atlas-monitor-${deviceId}-${Date.now()}` : '',
+    silentReuse: !forceRestart,
+    restartReason: reason
+  });
+}
 
 function hasOtherAtlasInputOwner(ws, deviceId) {
   for (const candidate of atlasClients.keys()) {
@@ -2112,10 +2450,35 @@ function isCapabilityEnabled(device, key) {
   return /^(1|true|yes|on)$/i.test(String(value || '').trim());
 }
 
-app.get('/api/health', (_req, res) => {
-  noStore(res);
-  res.json({ ok: true, product: 'LiveDesk', timestamp: new Date().toISOString() });
-});
+app.get('/api/health', (_req, res) => {
+  noStore(res);
+  const memory = process.memoryUsage();
+  const webSockets = {
+    frame: frameWss.clients.size,
+    atlas: atlasWss.clients.size,
+    input: inputWss.clients.size,
+    audio: audioWss.clients.size
+  };
+  res.json({
+    ok: true,
+    product: 'LiveDesk',
+    timestamp: new Date().toISOString(),
+    memory: {
+      rssBytes: memory.rss,
+      heapUsedBytes: memory.heapUsed,
+      heapTotalBytes: memory.heapTotal,
+      externalBytes: memory.external,
+      arrayBuffersBytes: memory.arrayBuffers
+    },
+    webSockets: {
+      ...webSockets,
+      total: Object.values(webSockets).reduce((sum, count) => sum + count, 0),
+      bufferedBytes: [...browserWebSocketServers]
+        .flatMap(wss => [...wss.clients])
+        .reduce((sum, ws) => sum + Math.max(0, Number(ws.bufferedAmount || 0)), 0)
+    }
+  });
+});
 
 app.get('/api/settings', async (_req, res) => {
   noStore(res);
@@ -2444,7 +2807,7 @@ app.post('/api/settings/agent/run', async (req, res) => {
     const deviceIds = normalizeDeviceIds(req.body?.deviceIds).slice(0, 500);
     const connectedDeviceIds = new Set(connectedAgentDeviceIds());
     if (deviceIds.length === 0 || deviceIds.some(deviceId => !connectedDeviceIds.has(deviceId))) {
-      throw new AgentProviderError('agent-target-not-connected', 'Every selected workstation must have an active Agent control channel.', { status: 409 });
+      throw new AgentProviderError('agent-target-not-connected', 'Every selected Client must have an active Agent control channel.', { status: 409 });
     }
     const permissionMode = String(req.body?.permissionMode || 'ask').trim().toLowerCase();
     if (!AGENT_PERMISSION_MODES.includes(permissionMode)) {
@@ -2580,8 +2943,8 @@ app.get('/api/remote/status', (_req, res) => {
     deviceId: runtimeDeviceId,
     deviceName: runtimeDeviceName,
     roleSource: runtimeRoleSource,
-    agentPackage: '@livedesk/client',
-    update: liveDeskUpdateManager?.getStatus() || null
+    agentPackage: '@livedesk/client',
+    update: getLiveDeskUpdateStatus()
   });
 });
 
@@ -2595,19 +2958,27 @@ app.get('/api/runtime/events', (_req, res) => {
   res.json({ ok: true, events: runtimeManager.getEvents() });
 });
 
-app.post('/api/runtime/restart', (_req, res) => {
-  noStore(res);
-  runtimeManager.emit('runtime.restart.requested', { role: runtimeRole });
-  res.json({ ok: true, restarting: true, role: runtimeRole });
-  setTimeout(() => process.kill(process.pid, 'SIGTERM'), 150);
-});
-
-app.post('/api/runtime/shutdown', (_req, res) => {
-  noStore(res);
-  runtimeManager.emit('runtime.shutdown.requested', { role: runtimeRole });
-  res.json({ ok: true, shuttingDown: true, role: runtimeRole });
-  setTimeout(() => process.kill(process.pid, 'SIGTERM'), 150);
-});
+app.post('/api/runtime/restart', (_req, res) => {
+  noStore(res);
+  runtimeManager.emit('runtime.restart.requested', { role: runtimeRole });
+  res.json({ ok: true, restarting: true, role: runtimeRole });
+  setTimeout(() => {
+    void shutdownHub('API_RESTART')
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  }, 150);
+});
+
+app.post('/api/runtime/shutdown', (_req, res) => {
+  noStore(res);
+  runtimeManager.emit('runtime.shutdown.requested', { role: runtimeRole });
+  res.json({ ok: true, shuttingDown: true, role: runtimeRole });
+  setTimeout(() => {
+    void shutdownHub('API_SHUTDOWN')
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  }, 150);
+});
 
 app.post('/api/runtime/switch-role', (req, res) => {
   noStore(res);
@@ -2642,13 +3013,19 @@ app.post('/api/auth/session', async (req, res) => {
     runtimeRefreshToken = refreshToken;
     runtimeAccessTokenExpiresAt = normalizeSessionExpiryMs(expiresAt);
     runtimeManager.setAuthenticated(true, user.id);
+    const persisted = persistRuntimeSession({
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      expires_at: expiresAt,
+      user
+    });
     const hostTarget = runtimeRole === 'hub'
-      ? await publishHubHostTarget({ reason: 'session-received' })
+      ? await publishHubHostTargetWithPendingRoleTakeover('session-received')
       : { ok: true, active: false };
     if (runtimeRole === 'hub') {
       startHubHostTargetLeaseRenewal();
     }
-    res.json({ ok: true, authenticated: true, userId: user.id, role: runtimeRole, hostTarget });
+    res.json({ ok: true, authenticated: true, persisted, userId: user.id, role: runtimeRole, hostTarget });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const status = authVerificationHttpStatus(message);
@@ -2877,6 +3254,21 @@ async function publishHubHostTarget({ takeover = false, reason = 'renewal' } = {
   }
 }
 
+async function publishHubHostTargetWithPendingRoleTakeover(reason = 'renewal') {
+  const takeover = roleTransitionTakeoverPending;
+  const result = await publishHubHostTarget({
+    takeover,
+    reason: takeover ? `${reason}-role-takeover` : reason
+  });
+  if (takeover && result.ok) {
+    // One explicit Client -> Hub selection authorizes one ownership handoff.
+    // Normal renewals must never keep takeover authority after publication.
+    roleTransitionTakeoverPending = false;
+    delete process.env.LIVEDESK_ROLE_TAKEOVER;
+  }
+  return result;
+}
+
 async function clearHubHostTarget(reason = 'shutdown') {
   if (hubHostTargetRenewTimer) {
     clearInterval(hubHostTargetRenewTimer);
@@ -2924,7 +3316,7 @@ function startHubHostTargetLeaseRenewal() {
     return;
   }
   hubHostTargetRenewTimer = setInterval(() => {
-    void publishHubHostTarget({ reason: 'renewal' });
+    void publishHubHostTargetWithPendingRoleTakeover('renewal');
   }, HUB_HOST_TARGET_RENEW_MS);
   hubHostTargetRenewTimer.unref?.();
 }
@@ -2952,7 +3344,7 @@ app.get('/api/hub/status', (_req, res) => {
     roleSource: runtimeRoleSource,
     runtimeStarted: true,
     hostTargetLease: getHubHostTargetLeaseStatus(),
-    update: liveDeskUpdateManager?.getStatus() || null
+    update: getLiveDeskUpdateStatus()
   });
 });
 
@@ -3063,23 +3455,30 @@ app.post('/api/runtime/role', async (req, res) => {
   }
 });
 
-app.get('/api/update/status', (_req, res) => {
-  noStore(res);
-  if (process.env.LIVEDESK_DESKTOP_HOST === '1') {
-    res.json({ updateAvailable: false, state: 'electron-managed', canApply: false, disabled: true });
-    return;
-  }
-  res.json(liveDeskUpdateManager?.getStatus() || { updateAvailable: false, state: 'unavailable' });
-});
+app.get('/api/update/status', (_req, res) => {
+  noStore(res);
+  if (process.env.LIVEDESK_DESKTOP_HOST === '1') {
+    res.json({
+      updateAvailable: false,
+      state: 'electron-managed',
+      canApply: false,
+      disabled: true,
+      restartResult: readHubRestartResult()
+    });
+    return;
+  }
+  res.json(getLiveDeskUpdateStatus());
+});
 
 app.post('/api/update/apply', async (_req, res) => {
   noStore(res);
   if (process.env.LIVEDESK_DESKTOP_HOST === '1') {
     res.status(409).json({ ok: false, error: 'electron-updater-managed', disabled: true });
     return;
-  }
-  try {
-    const result = await liveDeskUpdateManager?.startUpdate();
+  }
+  try {
+    liveDeskUpdateManager?.reconcileHubRestartResult(readHubRestartResult());
+    const result = await liveDeskUpdateManager?.startUpdate();
     res.status(result?.ok === false ? 409 : 200).json(result || { ok: false, error: 'update-manager-unavailable' });
   } catch (error) {
     res.status(500).json({ ok: false, error: error instanceof Error ? error.message : String(error) });
@@ -3468,8 +3867,8 @@ app.post('/api/remote/devices/:deviceId/quick-actions', requireHubFeatureAccess,
 
   const label = action === 'shutdown' ? 'Shut down' : `${action.slice(0, 1).toUpperCase()}${action.slice(1)}`;
   const result = remoteHub.requestAgentTask(req.params.deviceId, {
-    instruction: `${label} this workstation. This action was explicitly requested and confirmed from the LiveDesk Hub action panel.`,
-    title: `${label} workstation`,
+    instruction: `${label} this Client. This action was explicitly requested and confirmed from the LiveDesk Hub action panel.`,
+    title: `${label} Client`,
     operation: 'system.power',
     approvalLevel: 'task-only',
     toolArguments: { action, delaySec: 0 },
@@ -3719,30 +4118,18 @@ frameWss.on('connection', (ws, req) => {
   });
 });
 
-atlasWss.on('connection', ws => {
-  ws.liveDeskFrameClientId = `atlas-${++frameClientSeq}`;
-  ws.liveDeskAtlasStreamId = `mode4-atlas-${crypto.randomUUID()}`;
-  try { ws._socket?.setNoDelay?.(true); } catch {}
-  const session = new Mode4AtlasSession({
-    onFrame: output => sendMode4AtlasFrame(ws, output),
-    onLayout: layout => sendJson(ws, { ...layout, type: 'Mode4AtlasLayout' }),
-    onStatus: status => {
-      if (status?.type === 'log') {
-        const logger = status.level === 'warn' ? console.warn : console.log;
-        logger(`[LiveDesk Hub] ${status.message}`);
-      }
-      sendJson(ws, { ...status, type: 'Mode4AtlasStatus' });
-    }
-  });
-  ws.liveDeskAtlasSession = session;
-  atlasClients.set(ws, session);
-  const cleanup = () => {
-    atlasClients.delete(ws);
+atlasWss.on('connection', ws => {
+  ws.liveDeskFrameClientId = `atlas-${++frameClientSeq}`;
+  try { ws._socket?.setNoDelay?.(true); } catch {}
+  const cleanup = () => {
+    atlasClients.delete(ws);
     for (const deviceId of ws.liveDeskAtlasInputDeviceIds || []) {
       stopMode4AtlasInput(ws, deviceId, 'atlas-client-closed');
-    }
-    ws.liveDeskAtlasInputDeviceIds = new Set();
-    session.close();
+    }
+    ws.liveDeskAtlasInputDeviceIds = new Set();
+    ws.liveDeskAtlasHandle?.release?.();
+    ws.liveDeskAtlasHandle = null;
+    ws.liveDeskAtlasSession = null;
     const lane = ws.liveDeskFrameSendLane;
     if (lane) {
       lane.queue.length = 0;
@@ -3813,11 +4200,12 @@ inputWss.on('connection', ws => {
     } catch {
       sendJson(ws, { type: 'RemoteInputError', error: 'invalid-json' });
       return;
-    }
-    const deviceId = String(payload?.deviceId || '').trim();
-    const input = payload?.input && typeof payload.input === 'object'
-      ? { ...payload.input, hubReceivedAtEpochMs: Date.now() }
-      : { ...payload, hubReceivedAtEpochMs: Date.now() };
+    }
+    const deviceId = String(payload?.deviceId || '').trim();
+    const inputEventId = String(payload?.requestId || '').trim() || crypto.randomUUID();
+    const input = payload?.input && typeof payload.input === 'object'
+      ? { ...payload.input, inputEventId, hubConnectionId: ws.liveDeskInputClientId, hubReceivedAtEpochMs: Date.now() }
+      : { ...payload, inputEventId, hubConnectionId: ws.liveDeskInputClientId, hubReceivedAtEpochMs: Date.now() };
     const result = remoteHub.sendInputControl(deviceId, input);
     const inputType = String(input?.type || '').toLowerCase();
     const fireAndForget = payload?.fireAndForget === true
@@ -3863,17 +4251,130 @@ const roleWatchTimer = runtimeRole === 'hub'
   : null;
 roleWatchTimer?.unref?.();
 
-for (const signal of ['SIGINT', 'SIGTERM']) {
-  process.once(signal, async () => {
-    if (roleWatchTimer) {
-      clearInterval(roleWatchTimer);
+function waitForShutdownDelay(milliseconds) {
+  return new Promise(resolveWait => {
+    const timer = setTimeout(resolveWait, milliseconds);
+    timer.unref?.();
+  });
+}
+
+async function boundedShutdownStep(label, action, timeoutMs) {
+  let timer;
+  try {
+    await Promise.race([
+      Promise.resolve().then(action),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer.unref?.();
+      })
+    ]);
+    console.log(`[LiveDesk Hub] Shutdown stage completed: ${label}.`);
+  } catch (error) {
+    console.warn(`[LiveDesk Hub] Shutdown stage warning: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function runSynchronousShutdownStep(label, action) {
+  try {
+    action();
+  } catch (error) {
+    console.warn(`[LiveDesk Hub] Shutdown stage warning: ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function closeBrowserWebSockets() {
+  let closeRequested = 0;
+  for (const wss of browserWebSocketServers) {
+    for (const ws of wss.clients) {
+      closeRequested += 1;
+      try {
+        ws.close(1012, 'LiveDesk Hub restarting');
+      } catch {
+        try { ws.terminate(); } catch { /* socket already closed */ }
+      }
+    }
+  }
+  console.log(`[LiveDesk Hub] Shutdown stage: requested ${closeRequested} browser WebSocket connection(s) to close.`);
+}
+
+function terminateOpenConnections() {
+  let terminatedWebSockets = 0;
+  for (const wss of browserWebSocketServers) {
+    for (const ws of wss.clients) {
+      terminatedWebSockets += 1;
+      try { ws.terminate(); } catch { /* socket already closed */ }
     }
-    liveDeskUpdateManager?.close();
-    for (const session of atlasClients.values()) session.close();
+    try { wss.close(); } catch { /* no active WebSocket server state */ }
+  }
+  let destroyedHttpConnections = 0;
+  for (const socket of httpConnections) {
+    if (socket.destroyed) continue;
+    destroyedHttpConnections += 1;
+    try { socket.destroy(); } catch { /* socket already closed */ }
+  }
+  try { httpServer.closeAllConnections?.(); } catch { /* older Node runtime */ }
+  console.log(`[LiveDesk Hub] Shutdown stage: force-closed ${terminatedWebSockets} WebSocket and ${destroyedHttpConnections} HTTP connection(s).`);
+}
+
+let hubShutdownPromise = null;
+function shutdownHub(signal) {
+  if (hubShutdownPromise) return hubShutdownPromise;
+  hubShutdownPromise = (async () => {
+    const startedAt = Date.now();
+    console.log(`[LiveDesk Hub] Shutdown started signal=${signal} grace=${hubShutdownGraceMs}ms timeout=${hubShutdownTimeoutMs}ms.`);
+    if (roleWatchTimer) clearInterval(roleWatchTimer);
+    clearInterval(browserWebSocketHeartbeatTimer);
+    runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
+    runSynchronousShutdownStep('atlas pool close', () => atlasPool.close());
     atlasClients.clear();
-    hubSharedFolders.close();
-    await clearHubHostTarget(`process-${signal.toLowerCase()}`);
-    await remoteHub.close();
-    httpServer.close(() => process.exit(0));
-  });
-}
+    runSynchronousShutdownStep('shared folder close', () => hubSharedFolders.close());
+
+    const httpClosed = new Promise(resolveClose => {
+      try {
+        httpServer.close(error => {
+          if (error) {
+            console.warn(`[LiveDesk Hub] HTTP listener close warning: ${error.message}`);
+          } else {
+            console.log('[LiveDesk Hub] Shutdown stage completed: HTTP listener closed.');
+          }
+          resolveClose();
+        });
+        httpServer.closeIdleConnections?.();
+      } catch (error) {
+        console.warn(`[LiveDesk Hub] HTTP listener close warning: ${error instanceof Error ? error.message : String(error)}`);
+        resolveClose();
+      }
+    });
+
+    closeBrowserWebSockets();
+    const forceCloseTimer = setTimeout(terminateOpenConnections, hubShutdownGraceMs);
+    forceCloseTimer.unref?.();
+
+    const cleanupBudgetMs = Math.max(500, hubShutdownTimeoutMs - hubShutdownGraceMs - 500);
+    await Promise.all([
+      boundedShutdownStep('host target lease cleared', () => clearHubHostTarget(`process-${String(signal).toLowerCase()}`), Math.min(3_000, cleanupBudgetMs)),
+      boundedShutdownStep('remote transport closed', () => remoteHub.close(), cleanupBudgetMs)
+    ]);
+
+    const remainingMs = Math.max(0, hubShutdownTimeoutMs - (Date.now() - startedAt));
+    await Promise.race([httpClosed, waitForShutdownDelay(remainingMs)]);
+    clearTimeout(forceCloseTimer);
+    terminateOpenConnections();
+    console.log(`[LiveDesk Hub] Shutdown complete in ${Date.now() - startedAt}ms.`);
+  })();
+  return hubShutdownPromise;
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.once(signal, () => {
+    void shutdownHub(signal)
+      .then(() => process.exit(0))
+      .catch(error => {
+        console.error(`[LiveDesk Hub] Shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+        terminateOpenConnections();
+        process.exit(1);
+      });
+  });
+}