livedesk 0.1.441 → 0.1.443

package/bin/livedesk.js

@@ -13,7 +13,10 @@ import { acquireRuntimeLock } from '../bootstrap/runtime-lock.js';
 import { migrateLegacyClientState } from '../bootstrap/state-migration.js';
 import { createRoleBootstrapServer } from '../bootstrap/role-bootstrap-server.js';
 import { parseLsofPids } from '../bootstrap/port-inspection.js';
-import { isKnownLiveDeskClientAgentProcess } from '../bootstrap/client-process-identity.js';
+import {
+  isKnownLiveDeskCaptureHelperProcess,
+  isKnownLiveDeskClientAgentProcess
+} from '../bootstrap/client-process-identity.js';
 import { runLegacyClientUpdateSupervisorCli } from '../bootstrap/legacy-client-update.js';
 import { transferSavedClientSessionToHub } from '../bootstrap/hub-auth-handoff.js';
 
@@ -569,11 +572,11 @@ function runQuiet(command, args) {
 }
 
 function isKnownLiveDeskLauncherProcess(processName, commandLine) {
-  const normalizedName = String(processName || '').trim();
+  const normalizedName = String(processName || '').trim().replaceAll('\\', '/').split('/').pop() || '';
   const normalizedCommandLine = String(commandLine || '').replaceAll('\\', '/');
   return /^(?:node|node\.exe)$/i.test(normalizedName)
-    && /livedesk/i.test(normalizedCommandLine)
-    && /(?:^|\/)bin\/livedesk\.js(?:\s|["']|$)/i.test(normalizedCommandLine);
+    && /(?:^|\/)(?:node_modules\/livedesk\/bin\/livedesk\.js|packages\/livedesk\/bin\/livedesk\.js|node_modules\/\.bin\/livedesk)(?:\s|["']|$)/i
+      .test(normalizedCommandLine);
 }
 
 function existingRuntimeProbePorts() {
@@ -595,7 +598,7 @@ async function probeExistingRuntimeIdentity(existing) {
 
   for (const port of existingRuntimeProbePorts()) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 1200);
+    const timer = setTimeout(() => controller.abort(), 2500);
     try {
       const baseUrl = `http://127.0.0.1:${port}`;
       const [healthResponse, statusResponse] = await Promise.all([
@@ -707,7 +710,19 @@ async function stopExistingRuntime(existing) {
       if (error?.code !== 'ESRCH') throw error;
     }
   }
-  await waitForProcessExit(processId);
+  try {
+    await waitForProcessExit(processId);
+  } catch (error) {
+    if (os.platform() === 'win32') throw error;
+    console.warn(
+      `[LiveDesk] Confirmed launcher pid ${processId} did not finish graceful Client cleanup; `
+      + 'force-stopping that launcher only. Verified orphan agents/helpers will be audited before restart.'
+    );
+    try { process.kill(processId, 'SIGKILL'); } catch (killError) {
+      if (killError?.code !== 'ESRCH') throw killError;
+    }
+    await waitForProcessExit(processId, 2000);
+  }
   return runtimeProof;
 }
 
@@ -881,7 +896,7 @@ async function stopUnixProcessesOnPorts(ports) {
 async function stopStaleUnixClientAgents() {
   if (os.platform() === 'win32') return;
   const candidatePids = new Set();
-  for (const pattern of ['livedesk-client-fast', 'livedesk-client-node.js']) {
+  for (const pattern of ['livedesk-client-fast', 'livedesk-client-node.js', 'livedesk-sck-h264']) {
     const result = await runQuiet('pgrep', ['-f', pattern]);
     if (result.error?.code === 'ENOENT') return;
     for (const pid of parseLsofPids(result.stdout)) {
@@ -889,22 +904,29 @@ async function stopStaleUnixClientAgents() {
     }
   }
 
-  const stalePids = [];
+  const staleProcesses = [];
   for (const pid of candidatePids) {
     const details = await getProcessDetails(pid);
     if (details && isKnownLiveDeskClientAgentProcess(details.processName, details.commandLine)) {
-      stalePids.push(pid);
+      staleProcesses.push({ pid, type: 'agent' });
+    } else if (details && isKnownLiveDeskCaptureHelperProcess(details.processName, details.commandLine)) {
+      staleProcesses.push({ pid, type: 'capture-helper' });
     }
   }
-  if (stalePids.length === 0) return;
+  if (staleProcesses.length === 0) {
+    if (process.env.LIVEDESK_DEBUG === '1') {
+      console.log('[LiveDesk] Client lifecycle audit: verified stale agents=0 capture-helpers=0.');
+    }
+    return;
+  }
 
-  for (const pid of stalePids) {
+  for (const { pid } of staleProcesses) {
     try { process.kill(pid, 'SIGTERM'); } catch (error) {
       if (error?.code !== 'ESRCH') throw error;
     }
   }
   await waitMilliseconds(500);
-  for (const pid of stalePids) {
+  for (const { pid } of staleProcesses) {
     try {
       process.kill(pid, 0);
       process.kill(pid, 'SIGKILL');
@@ -912,7 +934,12 @@ async function stopStaleUnixClientAgents() {
       if (error?.code !== 'ESRCH') throw error;
     }
   }
-  console.log(`[LiveDesk] Stopped stale Client agent process(es): ${stalePids.join(', ')}.`);
+  const agentPids = staleProcesses.filter(item => item.type === 'agent').map(item => item.pid);
+  const helperPids = staleProcesses.filter(item => item.type === 'capture-helper').map(item => item.pid);
+  console.log(
+    `[LiveDesk] Client lifecycle audit: verified stale agents=${agentPids.length} `
+    + `capture-helpers=${helperPids.length}; stopped pids=${staleProcesses.map(item => item.pid).join(', ')}.`
+  );
 }
 
 async function stopProcessesOnPorts(ports) {

package/bootstrap/client-process-identity.js

@@ -2,8 +2,29 @@ export function isKnownLiveDeskClientAgentProcess(processName, commandLine) {
   const normalizedName = String(processName || '').trim().replaceAll('\\', '/').split('/').pop() || '';
   const normalizedCommandLine = String(commandLine || '').replaceAll('\\', '/');
   const isNode = /^(?:node|node\.exe)$/i.test(normalizedName);
+  const isDotnet = /^(?:dotnet|dotnet\.exe)$/i.test(normalizedName);
   const isFast = /^livedesk-client-fast(?:\.exe)?$/i.test(normalizedName);
   const isKnownNodeAgent = /(?:node_modules\/(?:livedesk\/client|@livedesk\/client)|packages\/(?:livedesk\/client|client))\/bin\/livedesk-client-node\.js(?:\s|["']|$)/i.test(normalizedCommandLine);
-  const isKnownFastAgent = /(?:node_modules\/(?:livedesk\/client|@livedesk\/client)|packages\/(?:livedesk\/client|client))\/fast\/[^/\s]+\/livedesk-client-fast(?:\.exe)?(?:\s|["']|$)/i.test(normalizedCommandLine);
-  return (isNode && isKnownNodeAgent) || (isFast && isKnownFastAgent);
+  const bundledFastRoot = '(?:node_modules/(?:livedesk/client|@livedesk/client)|packages/(?:livedesk/client|client))/fast/[^/\\s]+';
+  const optionalFastRoot = 'node_modules/@livedesk/fast-(?:linux-x64|osx-arm64|osx-x64|win-x64)/fast';
+  const fastRoot = `(?:${bundledFastRoot}|${optionalFastRoot})`;
+  const isKnownFastExecutable = new RegExp(
+    `${fastRoot}/livedesk-client-fast(?:\\.exe)?(?:\\s|["']|$)`,
+    'i'
+  ).test(normalizedCommandLine);
+  const isKnownFastDll = new RegExp(
+    `${fastRoot}/livedesk-client-fast\\.dll(?:\\s|["']|$)`,
+    'i'
+  ).test(normalizedCommandLine);
+  return (isNode && isKnownNodeAgent)
+    || (isFast && isKnownFastExecutable)
+    || (isDotnet && isKnownFastDll);
+}
+
+export function isKnownLiveDeskCaptureHelperProcess(processName, commandLine) {
+  const normalizedName = String(processName || '').trim().replaceAll('\\', '/').split('/').pop() || '';
+  const normalizedCommandLine = String(commandLine || '').replaceAll('\\', '/');
+  return /^livedesk-sck-h264$/i.test(normalizedName)
+    && /(?:^|\/)\.livedesk\/helpers\/macos-sck-h264\/livedesk-sck-h264(?:\s|["']|$)/i
+      .test(normalizedCommandLine);
 }

package/client/bin/livedesk-client.js

@@ -4102,11 +4102,17 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
         agentPid: 0,
         restartVerified: false
     });
+    const ownsProcessGroup = process.platform !== 'win32';
     const child = spawn(command, args, {
         env,
         stdio: 'inherit',
+        // A dedicated Unix process group lets Ctrl+C, replacement startup, and
+        // forced shutdown terminate RemoteFast together with its SCK/FFmpeg
+        // descendants without touching npm, the terminal, or unrelated jobs.
+        detached: ownsProcessGroup,
         windowsHide: true
     });
+    child.livedeskOwnsProcessGroup = ownsProcessGroup;
     activeAgentProcess = child;
     if (typeof onStart === 'function') {
         onStart(child);

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.196",
+  "version": "0.1.198",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.403",
-    "@livedesk/fast-osx-arm64": "0.1.403",
-    "@livedesk/fast-osx-x64": "0.1.403",
-    "@livedesk/fast-win-x64": "0.1.403"
+    "@livedesk/fast-linux-x64": "0.1.405",
+    "@livedesk/fast-osx-arm64": "0.1.405",
+    "@livedesk/fast-osx-x64": "0.1.405",
+    "@livedesk/fast-win-x64": "0.1.405"
   },
   "publishConfig": {
     "access": "public"

package/client/src/runtime/agent-process-lifecycle.js

@@ -1,9 +1,76 @@
+import { execFile } from 'node:child_process';
+
 const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
 
+function terminateWindowsProcessTree(processId) {
+    return new Promise(resolve => {
+        execFile(
+            'taskkill.exe',
+            ['/PID', String(processId), '/T', '/F'],
+            {
+                windowsHide: true,
+                timeout: 10000,
+                killSignal: 'SIGKILL'
+            },
+            error => resolve({ ok: !error, error: error || null })
+        );
+    });
+}
+
+function isOwnedUnixProcessGroupAlive(child, platform, signalProcess) {
+    const processId = Number(child?.pid || 0);
+    if (platform === 'win32'
+        || child?.livedeskOwnsProcessGroup !== true
+        || !Number.isInteger(processId)
+        || processId <= 1) {
+        return false;
+    }
+    try {
+        signalProcess(-processId, 0);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+function isProcessIdAlive(processId, signalProcess) {
+    if (!Number.isInteger(processId) || processId <= 1) {
+        return false;
+    }
+    try {
+        signalProcess(processId, 0);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+function signalAgentTree(child, signal, platform, signalProcess) {
+    const processId = Number(child?.pid || 0);
+    if (platform !== 'win32'
+        && child?.livedeskOwnsProcessGroup === true
+        && Number.isInteger(processId)
+        && processId > 1) {
+        try {
+            signalProcess(-processId, signal);
+            return;
+        } catch (error) {
+            if (error?.code !== 'ESRCH') throw error;
+        }
+    }
+    child.kill(signal);
+}
+
 export function installAgentTerminationHandlers({
     hostProcess = process,
     getAgentProcess,
-    shutdownTimeoutMs = 3000,
+    shutdownTimeoutMs = 8000,
+    platform = process.platform,
+    signalProcess = (pid, signal) => process.kill(pid, signal),
+    terminateWindowsTree = terminateWindowsProcessTree,
+    windowsTerminateAttemptLimit = 3,
+    windowsTerminateRetryMs = 100,
+    reportTerminationFailure = message => console.error(message),
     exitProcess = code => hostProcess.exit(code)
 } = {}) {
     if (typeof getAgentProcess !== 'function') {
@@ -18,32 +85,110 @@ export function installAgentTerminationHandlers({
             terminating = true;
             const exitCode = SIGNAL_EXIT_CODES[signal] || 1;
             const child = getAgentProcess();
-            if (!child || child.exitCode !== null || child.killed === true) {
+            if (!child || child.exitCode !== null) {
                 exitProcess(exitCode);
                 return;
             }
 
             let finished = false;
+            let poll = null;
+            let timeout = null;
+            let hardStop = null;
+            let windowsRetryTimer = null;
             const finish = () => {
                 if (finished) return;
                 finished = true;
+                if (poll) clearInterval(poll);
+                if (timeout) clearTimeout(timeout);
+                if (hardStop) clearTimeout(hardStop);
+                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
                 exitProcess(exitCode);
             };
-            child.once('exit', finish);
+            const processId = Number(child?.pid || 0);
+            if (platform === 'win32') {
+                if (!Number.isInteger(processId) || processId <= 1) {
+                    finish();
+                    return;
+                }
+                // On Windows child.kill() only gives us the Agent leader's
+                // lifecycle. It does not provide an authoritative contract
+                // that FFmpeg descendants have stopped. Keep the launcher
+                // alive until taskkill has completed against this exact,
+                // launcher-owned process tree. Never search for or terminate
+                // unrelated ffmpeg.exe processes globally.
+                const attemptLimit = Math.max(1, Number(windowsTerminateAttemptLimit) || 3);
+                const retryMs = Math.max(25, Number(windowsTerminateRetryMs) || 100);
+                let attempt = 0;
+                let failureReported = false;
+                const terminateOwnedTree = () => {
+                    if (finished) return;
+                    attempt += 1;
+                    let treeTermination;
+                    try {
+                        treeTermination = terminateWindowsTree(processId);
+                    } catch (error) {
+                        treeTermination = { ok: false, error };
+                    }
+                    Promise.resolve(treeTermination)
+                        .catch(error => ({ ok: false, error }))
+                        .then(result => {
+                            if (finished) return;
+                            if (result?.ok !== false) {
+                                finish();
+                                return;
+                            }
+                            if (!isProcessIdAlive(processId, signalProcess)) {
+                                finish();
+                                return;
+                            }
+
+                            const burstExhausted = attempt >= attemptLimit;
+                            if (burstExhausted && !failureReported) {
+                                failureReported = true;
+                                const reason = result?.error?.message || 'taskkill returned an error';
+                                reportTerminationFailure(
+                                    `[LiveDesk Client] Agent tree pid=${processId} is still alive after `
+                                    + `${attemptLimit} exact-PID taskkill attempts (${reason}). `
+                                    + 'The launcher will remain alive and keep retrying so capture descendants are not orphaned.'
+                                );
+                            }
+                            if (burstExhausted) {
+                                attempt = 0;
+                            }
+                            windowsRetryTimer = setTimeout(
+                                terminateOwnedTree,
+                                burstExhausted ? Math.max(1000, retryMs) : retryMs
+                            );
+                        });
+                };
+                terminateOwnedTree();
+                return;
+            }
+            const finishWhenTreeStops = () => {
+                const ownsUnixGroup = child?.livedeskOwnsProcessGroup === true
+                    && Number(child?.pid || 0) > 1;
+                const childAlive = child.exitCode === null && child.signalCode == null;
+                const groupAlive = ownsUnixGroup
+                    && isOwnedUnixProcessGroupAlive(child, platform, signalProcess);
+                if (!childAlive && !groupAlive) {
+                    finish();
+                }
+            };
+            child.once('exit', finishWhenTreeStops);
             try {
-                child.kill(signal);
+                signalAgentTree(child, signal, platform, signalProcess);
             } catch {
                 finish();
                 return;
             }
-            const timeout = setTimeout(() => {
+            poll = setInterval(finishWhenTreeStops, 50);
+            timeout = setTimeout(() => {
                 try {
-                    if (child.exitCode === null) child.kill('SIGKILL');
+                    signalAgentTree(child, 'SIGKILL', platform, signalProcess);
                 } catch {
                 }
-                finish();
+                hardStop = setTimeout(finish, 250);
             }, Math.max(100, Number(shutdownTimeoutMs) || 3000));
-            timeout.unref?.();
         };
         handlers.set(signal, handler);
         hostProcess.once(signal, handler);

package/hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/hub/src/remote-hub.js

@@ -3881,6 +3881,9 @@ export function createRemoteHub(options = {}) {
             nativeEncodableFrameCount: Number.isFinite(Number(message.nativeEncodableFrameCount)) ? Number(message.nativeEncodableFrameCount) : 0,
             nativeSkippedFrameCount: Number.isFinite(Number(message.nativeSkippedFrameCount)) ? Number(message.nativeSkippedFrameCount) : 0,
             nativeEncodedFrameCount: Number.isFinite(Number(message.nativeEncodedFrameCount)) ? Number(message.nativeEncodedFrameCount) : 0,
+            nativeEncodeFramesInFlight: Number.isFinite(Number(message.nativeEncodeFramesInFlight)) ? Number(message.nativeEncodeFramesInFlight) : 0,
+            nativeBackpressureSkippedFrameCount: Number.isFinite(Number(message.nativeBackpressureSkippedFrameCount)) ? Number(message.nativeBackpressureSkippedFrameCount) : 0,
+            nativeIdleSkippedFrameCount: Number.isFinite(Number(message.nativeIdleSkippedFrameCount)) ? Number(message.nativeIdleSkippedFrameCount) : 0,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hardwareEncoder: safeString(message.hardwareEncoder, 80),
@@ -4258,6 +4261,9 @@ export function createRemoteHub(options = {}) {
             nativeEncodableFrameCount: Number.isFinite(Number(message.nativeEncodableFrameCount)) ? Number(message.nativeEncodableFrameCount) : 0,
             nativeSkippedFrameCount: Number.isFinite(Number(message.nativeSkippedFrameCount)) ? Number(message.nativeSkippedFrameCount) : 0,
             nativeEncodedFrameCount: Number.isFinite(Number(message.nativeEncodedFrameCount)) ? Number(message.nativeEncodedFrameCount) : 0,
+            nativeEncodeFramesInFlight: Number.isFinite(Number(message.nativeEncodeFramesInFlight)) ? Number(message.nativeEncodeFramesInFlight) : 0,
+            nativeBackpressureSkippedFrameCount: Number.isFinite(Number(message.nativeBackpressureSkippedFrameCount)) ? Number(message.nativeBackpressureSkippedFrameCount) : 0,
+            nativeIdleSkippedFrameCount: Number.isFinite(Number(message.nativeIdleSkippedFrameCount)) ? Number(message.nativeIdleSkippedFrameCount) : 0,
             nativeCaptureTelemetryAt: safeString(message.nativeCaptureTelemetryAt, 80),
             droppedByAgent: Number.isFinite(Number(message.droppedByAgent)) ? Number(message.droppedByAgent) : 0,
             hubIngressDropped: Number.isFinite(Number(message.hubIngressDropped)) ? Number(message.hubIngressDropped) : 0,

package/hub/src/server.js

@@ -2070,6 +2070,9 @@ function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
     nativeEncodableFrameCount: Number(frame.nativeEncodableFrameCount || 0) || 0,
     nativeSkippedFrameCount: Number(frame.nativeSkippedFrameCount || 0) || 0,
     nativeEncodedFrameCount: Number(frame.nativeEncodedFrameCount || 0) || 0,
+    nativeEncodeFramesInFlight: Number(frame.nativeEncodeFramesInFlight || 0) || 0,
+    nativeBackpressureSkippedFrameCount: Number(frame.nativeBackpressureSkippedFrameCount || 0) || 0,
+    nativeIdleSkippedFrameCount: Number(frame.nativeIdleSkippedFrameCount || 0) || 0,
     nativeCaptureTelemetryAt: frame.nativeCaptureTelemetryAt || '',
     droppedByAgent: Number(frame.droppedByAgent || 0) || 0,
     hubIngressDropped: Number(frame.hubIngressDropped || 0) || 0,