livedesk 0.1.444 → 0.1.446

package/bin/livedesk.js

@@ -5,7 +5,17 @@ import net from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { execFile, spawn } from 'node:child_process';
-import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import os from 'node:os';
 import { resolveDeviceRole, writeRoleCache } from '../bootstrap/device-role.js';
@@ -558,9 +568,9 @@ async function isManagerAlreadyRunning(url = DEFAULT_MANAGER_URL) {
   }
 }
 
-function runQuiet(command, args) {
-  return new Promise(resolve => {
-    execFile(command, args, { windowsHide: true }, (error, stdout, stderr) => {
+function runQuiet(command, args, options = {}) {
+  return new Promise(resolve => {
+    execFile(command, args, { windowsHide: true, ...options }, (error, stdout, stderr) => {
       resolve({
         ok: !error,
         stdout: String(stdout || '').trim(),
@@ -632,6 +642,28 @@ async function probeExistingRuntimeIdentity(existing) {
   return null;
 }
 
+function readLinuxProcessStartMarker(pid) {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const commandEnd = stat.lastIndexOf(')');
+    if (commandEnd < 0) return '';
+    const fieldsAfterCommand = stat.slice(commandEnd + 1).trim().split(/\s+/);
+    // /proc/<pid>/stat field 22 is the process start time in clock ticks.
+    // fieldsAfterCommand[0] is field 3 (state).
+    return fieldsAfterCommand[19] ? `linux-start-ticks:${fieldsAfterCommand[19]}` : '';
+  } catch {
+    return '';
+  }
+}
+
+function processInstanceMarker(details) {
+  const processId = Number(details?.processId || 0);
+  const startMarker = String(details?.startMarker || '').trim();
+  return Number.isInteger(processId) && processId > 1 && startMarker
+    ? `${processId}:${startMarker}`
+    : '';
+}
+
 async function getProcessDetails(pid) {
   const processId = Number(pid);
   if (!Number.isInteger(processId) || processId <= 1) {
@@ -639,31 +671,114 @@ async function getProcessDetails(pid) {
   }
 
   if (os.platform() === 'win32') {
-    const script = `$targetPid = ${processId}; $process = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1; if ($process) { [pscustomobject]@{ ProcessName = [string]$process.Name; CommandLine = [string]$process.CommandLine } | ConvertTo-Json -Compress }`;
-    const result = await runQuiet('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script]);
+    const script = `$targetPid = ${processId}; $process = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1; if ($process) { $creationUtcTicks = if ($process.CreationDate) { [string]$process.CreationDate.ToUniversalTime().Ticks } else { "" }; [pscustomobject]@{ ProcessId = [int]$process.ProcessId; ParentProcessId = [int]$process.ParentProcessId; ProcessName = [string]$process.Name; CommandLine = [string]$process.CommandLine; ExecutablePath = [string]$process.ExecutablePath; CreationDate = [string]$process.CreationDate; CreationUtcTicks = $creationUtcTicks } | ConvertTo-Json -Compress }`;
+    const result = await runQuiet(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { timeout: 10000, killSignal: 'SIGKILL' }
+    );
     if (!result.stdout) return null;
     try {
       const parsed = JSON.parse(result.stdout);
       return {
+        processId: Number(parsed?.ProcessId || processId),
+        parentProcessId: Number(parsed?.ParentProcessId || 0),
         processName: String(parsed?.ProcessName || ''),
-        commandLine: String(parsed?.CommandLine || '')
+        commandLine: String(parsed?.CommandLine || ''),
+        executablePath: String(parsed?.ExecutablePath || ''),
+        startMarker: String(parsed?.CreationDate || ''),
+        startOrder: String(parsed?.CreationUtcTicks || '')
       };
     } catch {
       return null;
     }
   }
 
-  const [nameResult, commandResult] = await Promise.all([
+  const [nameResult, commandResult, groupResult, parentResult, startResult] = await Promise.all([
     runQuiet('ps', ['-p', String(processId), '-o', 'comm=']),
-    runQuiet('ps', ['-p', String(processId), '-o', 'args='])
+    runQuiet('ps', ['-p', String(processId), '-o', 'args=']),
+    runQuiet('ps', ['-p', String(processId), '-o', 'pgid=']),
+    runQuiet('ps', ['-p', String(processId), '-o', 'ppid=']),
+    runQuiet('ps', ['-p', String(processId), '-o', 'lstart='])
   ]);
   if (!nameResult.stdout && !commandResult.stdout) return null;
+  let executablePath = '';
+  if (os.platform() === 'linux') {
+    try {
+      executablePath = readlinkSync(`/proc/${processId}/exe`);
+    } catch {
+      executablePath = '';
+    }
+  }
   return {
+    processId,
+    parentProcessId: Number(parentResult.stdout || 0),
     processName: nameResult.stdout,
-    commandLine: commandResult.stdout
+    commandLine: commandResult.stdout,
+    executablePath,
+    processGroupId: Number(groupResult.stdout || 0),
+    startMarker: readLinuxProcessStartMarker(processId) || startResult.stdout
   };
 }
 
+async function hasKnownLiveDeskClientAgentDescendant(rootPid) {
+  const processId = Number(rootPid);
+  if (!Number.isInteger(processId) || processId <= 1) return false;
+  let pairs = [];
+  if (os.platform() === 'win32') {
+    const script = '$ErrorActionPreference = "Stop"; @(Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId } }) | ConvertTo-Json -Compress';
+    const result = await runQuiet(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { timeout: 10000, killSignal: 'SIGKILL' }
+    );
+    if (!result.ok || !result.stdout) return false;
+    try {
+      const parsed = JSON.parse(result.stdout);
+      pairs = (Array.isArray(parsed) ? parsed : [parsed]).map(item => ({
+        pid: Number(item?.ProcessId || 0),
+        parentPid: Number(item?.ParentProcessId || 0)
+      }));
+    } catch {
+      return false;
+    }
+  } else {
+    const result = await runQuiet(
+      'ps',
+      ['-axo', 'pid=,ppid='],
+      { timeout: 10000, killSignal: 'SIGKILL' }
+    );
+    if (!result.ok || !result.stdout) return false;
+    pairs = result.stdout.split(/\r?\n/).flatMap(line => {
+      const match = line.match(/^\s*(\d+)\s+(\d+)\s*$/);
+      return match ? [{ pid: Number(match[1]), parentPid: Number(match[2]) }] : [];
+    });
+  }
+
+  const childrenByParent = new Map();
+  for (const pair of pairs) {
+    if (!childrenByParent.has(pair.parentPid)) childrenByParent.set(pair.parentPid, []);
+    childrenByParent.get(pair.parentPid).push(pair.pid);
+  }
+  const queue = [...(childrenByParent.get(processId) || [])];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const candidatePid = queue.shift();
+    if (!Number.isInteger(candidatePid) || candidatePid <= 1 || seen.has(candidatePid)) continue;
+    seen.add(candidatePid);
+    const details = await getProcessDetails(candidatePid);
+    if (details && isKnownLiveDeskClientAgentProcess(
+      details.processName,
+      details.commandLine,
+      details.executablePath
+    )) {
+      return true;
+    }
+    queue.push(...(childrenByParent.get(candidatePid) || []));
+  }
+  return false;
+}
+
 async function waitForProcessExit(pid, timeoutMs = EXISTING_RUNTIME_STOP_TIMEOUT_MS) {
   const processId = Number(pid);
   const deadline = Date.now() + timeoutMs;
@@ -692,16 +807,26 @@ async function stopExistingRuntime(existing) {
     return null;
   }
   const commandLineConfirmed = isKnownLiveDeskLauncherProcess(details.processName, details.commandLine);
-  const runtimeProof = commandLineConfirmed
+  const lockInstanceConfirmed = String(existing?.ownerToken || '').trim().length >= 16
+    && String(existing?.ownerInstanceMarker || '').trim()
+      === processInstanceMarker(details);
+  const legacyClientTreeConfirmed = !String(existing?.ownerToken || '').trim()
+    && String(existing?.role || '').trim().toLowerCase() === 'client'
+    && await hasKnownLiveDeskClientAgentDescendant(processId);
+  const runtimeProof = commandLineConfirmed || lockInstanceConfirmed || legacyClientTreeConfirmed
     ? null
     : await probeExistingRuntimeIdentity(existing);
-  if (!commandLineConfirmed && !runtimeProof) {
+  if (!commandLineConfirmed && !lockInstanceConfirmed && !legacyClientTreeConfirmed && !runtimeProof) {
     throw new Error(`Existing runtime pid ${processId} is not a confirmed LiveDesk launcher; it was preserved.`);
   }
 
   const identityProof = commandLineConfirmed
     ? 'command-line'
-    : `runtime-api:${runtimeProof.port}:${runtimeProof.appVersion || 'unknown'}`;
+    : lockInstanceConfirmed
+      ? 'lock-instance'
+      : legacyClientTreeConfirmed
+        ? 'legacy-lock-exact-client-descendant'
+        : `runtime-api:${runtimeProof.port}:${runtimeProof.appVersion || 'unknown'}`;
   console.log(`[LiveDesk] Stopping existing ${existing?.role || 'runtime'} launcher pid ${processId} before starting a fresh runtime (identity=${identityProof}).`);
   if (os.platform() === 'win32') {
     await runQuiet('taskkill.exe', ['/PID', String(processId), '/T', '/F']);
@@ -893,52 +1018,359 @@ async function stopUnixProcessesOnPorts(ports) {
   assertPortCleanupReady(finalRecords, portStates);
 }
 
-async function stopStaleUnixClientAgents() {
-  if (os.platform() === 'win32') return;
-  const candidatePids = new Set();
-  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)) {
-      if (pid > 1 && pid !== process.pid) candidatePids.add(pid);
+async function stopStaleClientAgents() {
+  const classifyLiveDeskProcess = details => {
+    if (isKnownLiveDeskClientAgentProcess(
+      details?.processName,
+      details?.commandLine,
+      details?.executablePath
+    )) return 'agent';
+    if (isKnownLiveDeskCaptureHelperProcess(
+      details?.processName,
+      details?.commandLine,
+      details?.executablePath
+    )) return 'capture-helper';
+    return '';
+  };
+
+  const enumerateCandidatePids = async () => {
+    if (os.platform() === 'win32') {
+      const script = [
+        '$ErrorActionPreference = "Stop";',
+        '$candidates = @(Get-CimInstance Win32_Process | Where-Object {',
+        '  $_.Name -match "^(?i:node(?:\\.exe)?|dotnet(?:\\.exe)?|livedesk-client-fast\\.exe)$" -and',
+        '  [string]$_.CommandLine -match "(?i:livedesk-client-fast|livedesk-client-node\\.js)"',
+        '});',
+        '@($candidates | ForEach-Object { [string]$_.ProcessId }) -join [Environment]::NewLine'
+      ].join(' ');
+      const result = await runQuiet(
+        'powershell.exe',
+        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+        { timeout: 10000, killSignal: 'SIGKILL' }
+      );
+      if (!result.ok && !result.stdout) {
+        throw new Error(
+          `LiveDesk Client lifecycle audit could not enumerate Windows Agent processes: `
+          + `${result.stderr || result.error?.message || 'CIM query failed'}`
+        );
+      }
+      return parseLsofPids(result.stdout);
     }
-  }
 
-  const staleProcesses = [];
-  for (const pid of candidatePids) {
-    const details = await getProcessDetails(pid);
-    if (details && isKnownLiveDeskClientAgentProcess(details.processName, details.commandLine)) {
-      staleProcesses.push({ pid, type: 'agent' });
-    } else if (details && isKnownLiveDeskCaptureHelperProcess(details.processName, details.commandLine)) {
-      staleProcesses.push({ pid, type: 'capture-helper' });
+    // One complete ps snapshot avoids treating pgrep execution errors as
+    // "nothing is running". The strict identity classifier below decides
+    // whether each textual candidate is really a packaged LiveDesk process.
+    const result = await runQuiet(
+      'ps',
+      ['-axo', 'pid=,args='],
+      { timeout: 10000, killSignal: 'SIGKILL' }
+    );
+    if (!result.ok && !result.stdout) {
+      throw new Error(
+        `LiveDesk Client lifecycle audit could not enumerate Unix processes: `
+        + `${result.stderr || result.error?.message || 'ps failed'}`
+      );
     }
-  }
-  if (staleProcesses.length === 0) {
-    if (process.env.LIVEDESK_DEBUG === '1') {
-      console.log('[LiveDesk] Client lifecycle audit: verified stale agents=0 capture-helpers=0.');
+    const candidatePids = [];
+    const patterns = [
+      'livedesk-client-fast',
+      'livedesk-client-node.js',
+      'livedesk-sck-h264',
+      'livedesk-sck-audio',
+      'livedesk-raw-capture-helper.mjs'
+    ];
+    for (const line of result.stdout.split(/\r?\n/)) {
+      if (!patterns.some(pattern => line.includes(pattern))) continue;
+      const match = line.match(/^\s*(\d+)\s+/);
+      const pid = Number(match?.[1] || 0);
+      if (pid > 1 && pid !== process.pid) candidatePids.push(pid);
     }
-    return;
-  }
+    return [...new Set(candidatePids)];
+  };
+
+  const findStaleProcesses = async () => {
+    const found = [];
+    for (const pid of await enumerateCandidatePids()) {
+      if (pid <= 1 || pid === process.pid) continue;
+      const details = await getProcessDetails(pid);
+      if (!details) {
+        if (isPidAlive(pid)) {
+          throw new Error(
+            `LiveDesk Client lifecycle audit could not establish the identity of candidate pid=${pid}; `
+            + 'startup was preserved instead of signaling an unknown process.'
+          );
+        }
+        continue;
+      }
+      const type = classifyLiveDeskProcess(details);
+      if (!type) continue;
+      const instanceMarker = processInstanceMarker(details);
+      if (!instanceMarker) {
+        throw new Error(
+          `LiveDesk Client lifecycle audit could not establish a start marker for verified ${type} pid=${pid}.`
+        );
+      }
+      found.push({
+        pid,
+        type,
+        instanceMarker,
+        processGroupId: Number(details.processGroupId || 0),
+        startOrder: String(details.startOrder || '')
+      });
+    }
+    return found;
+  };
+
+  const getMatchingDetails = async record => {
+    const details = await getProcessDetails(record.pid);
+    if (!details || processInstanceMarker(details) !== record.instanceMarker) return null;
+    if (record.type === 'descendant') return details;
+    return classifyLiveDeskProcess(details) === record.type ? details : null;
+  };
+
+  const waitForExactRecordsExit = async (records, timeoutMs = 4000) => {
+    const deadline = Date.now() + timeoutMs;
+    let remaining = records;
+    while (Date.now() < deadline) {
+      const checks = await Promise.all(remaining.map(async record => (
+        await getMatchingDetails(record) ? record : null
+      )));
+      remaining = checks.filter(Boolean);
+      if (remaining.length === 0) return [];
+      await waitMilliseconds(Math.min(100, Math.max(1, deadline - Date.now())));
+    }
+    const finalChecks = await Promise.all(remaining.map(async record => (
+      await getMatchingDetails(record) ? record : null
+    )));
+    return finalChecks.filter(Boolean);
+  };
+
+  const isUnixGroupAlive = processGroupId => {
+    if (!Number.isInteger(processGroupId) || processGroupId <= 1) return false;
+    try {
+      process.kill(-processGroupId, 0);
+      return true;
+    } catch (error) {
+      return error?.code === 'EPERM';
+    }
+  };
 
-  for (const { pid } of staleProcesses) {
-    try { process.kill(pid, 'SIGTERM'); } catch (error) {
+  const waitForUnixGroupExit = async (processGroupId, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!isUnixGroupAlive(processGroupId)) return true;
+      await waitMilliseconds(Math.min(50, Math.max(1, deadline - Date.now())));
+    }
+    return !isUnixGroupAlive(processGroupId);
+  };
+
+  const terminateUnixAgentGroup = async record => {
+    const details = await getMatchingDetails(record);
+    if (!details) return;
+    const processGroupId = Number(details.processGroupId || 0);
+    if (processGroupId !== record.pid || record.processGroupId !== record.pid) {
+      throw new Error(
+        `verified stale Agent pid=${record.pid} is not its own dedicated process-group leader `
+        + `(pgid=${processGroupId || 'unknown'}); it was preserved to avoid signaling unrelated terminal processes.`
+      );
+    }
+    try {
+      process.kill(-processGroupId, 'SIGTERM');
+    } catch (error) {
       if (error?.code !== 'ESRCH') throw error;
+      return;
     }
-  }
-  await waitMilliseconds(500);
-  for (const { pid } of staleProcesses) {
+    if (await waitForUnixGroupExit(processGroupId, 500)) return;
+    try {
+      process.kill(-processGroupId, 'SIGKILL');
+    } catch (error) {
+      if (error?.code !== 'ESRCH') throw error;
+    }
+    if (!await waitForUnixGroupExit(processGroupId, 4000)) {
+      throw new Error(
+        `verified stale Agent group pgid=${processGroupId} remained alive after SIGKILL; `
+        + 'startup will not overlap its capture descendants.'
+      );
+    }
+  };
+
+  const terminateExactUnixHelper = async record => {
+    if (!await getMatchingDetails(record)) return;
+    try {
+      process.kill(record.pid, 'SIGTERM');
+    } catch (error) {
+      if (error?.code !== 'ESRCH') throw error;
+      return;
+    }
+    if ((await waitForExactRecordsExit([record], 500)).length === 0) return;
+    // The immutable start marker is rechecked immediately before escalation.
+    if (!await getMatchingDetails(record)) return;
     try {
-      process.kill(pid, 0);
-      process.kill(pid, 'SIGKILL');
+      process.kill(record.pid, 'SIGKILL');
     } catch (error) {
       if (error?.code !== 'ESRCH') throw error;
     }
+    const remaining = await waitForExactRecordsExit([record], 4000);
+    if (remaining.length > 0) {
+      throw new Error(`verified stale capture helper pid=${record.pid} remained alive after SIGKILL`);
+    }
+  };
+
+  const enumerateWindowsParentPairs = async () => {
+    const script = '$ErrorActionPreference = "Stop"; @(Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId } }) | ConvertTo-Json -Compress';
+    const result = await runQuiet(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { timeout: 10000, killSignal: 'SIGKILL' }
+    );
+    if (!result.ok || !result.stdout) {
+      throw new Error(
+        `LiveDesk Client lifecycle audit could not snapshot the Windows process tree: `
+        + `${result.stderr || result.error?.message || 'CIM query failed'}`
+      );
+    }
+    const parsed = JSON.parse(result.stdout);
+    return (Array.isArray(parsed) ? parsed : [parsed]).map(item => ({
+      pid: Number(item?.ProcessId || 0),
+      parentPid: Number(item?.ParentProcessId || 0)
+    }));
+  };
+
+  const captureWindowsTreeRecords = async rootRecord => {
+    const pairs = await enumerateWindowsParentPairs();
+    const descendantsByParent = new Map();
+    for (const pair of pairs) {
+      if (!descendantsByParent.has(pair.parentPid)) descendantsByParent.set(pair.parentPid, []);
+      descendantsByParent.get(pair.parentPid).push(pair.pid);
+    }
+    const processIds = [];
+    const queue = [rootRecord.pid];
+    const seen = new Set();
+    while (queue.length > 0) {
+      const pid = queue.shift();
+      if (!Number.isInteger(pid) || pid <= 1 || seen.has(pid)) continue;
+      seen.add(pid);
+      processIds.push(pid);
+      queue.push(...(descendantsByParent.get(pid) || []));
+    }
+    const records = [];
+    for (const pid of processIds) {
+      const details = await getProcessDetails(pid);
+      if (!details) continue;
+      const instanceMarker = processInstanceMarker(details);
+      if (!instanceMarker) {
+        throw new Error(`Windows process-tree verification could not establish a start marker for pid=${pid}.`);
+      }
+      if (pid !== rootRecord.pid && rootRecord.startOrder && details.startOrder) {
+        const rootStart = BigInt(rootRecord.startOrder);
+        const descendantStart = BigInt(details.startOrder);
+        if (descendantStart < rootStart) {
+          throw new Error(
+            `Windows process-tree verification found pid=${pid} with reused parent pid=${rootRecord.pid}; `
+            + 'the older process was preserved instead of passing an ambiguous tree to taskkill.'
+          );
+        }
+      }
+      records.push(pid === rootRecord.pid
+        ? rootRecord
+        : {
+            pid,
+            type: 'descendant',
+            instanceMarker,
+            startOrder: String(details.startOrder || '')
+          });
+    }
+    if (!records.some(record => (
+      record.pid === rootRecord.pid && record.instanceMarker === rootRecord.instanceMarker
+    ))) {
+      return [];
+    }
+    return records;
+  };
+
+  const taskkillExactWindowsRecord = async (record, includeTree) => {
+    const details = await getMatchingDetails(record);
+    if (!details) return;
+    const expectedStart = String(details.startMarker || '').replaceAll("'", "''");
+    const treeArgument = includeTree ? ', "/T"' : '';
+    const script = [
+      '$ErrorActionPreference = "Stop";',
+      `$targetPid = ${record.pid};`,
+      `$expectedStart = '${expectedStart}';`,
+      '$target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1;',
+      'if (-not $target) { exit 0 };',
+      'if ([string]$target.CreationDate -ne $expectedStart) { exit 3 };',
+      `$arguments = @("/PID", [string]$targetPid${treeArgument}, "/F");`,
+      '$taskkill = Start-Process -FilePath "taskkill.exe" -ArgumentList $arguments -NoNewWindow -Wait -PassThru;',
+      'exit $taskkill.ExitCode'
+    ].join(' ');
+    await runQuiet(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { timeout: 15000, killSignal: 'SIGKILL' }
+    );
+  };
+
+  const terminateWindowsAgentTree = async record => {
+    if (!await getMatchingDetails(record)) return;
+    const treeRecords = await captureWindowsTreeRecords(record);
+    if (treeRecords.length === 0) return;
+    await taskkillExactWindowsRecord(record, true);
+    let remaining = await waitForExactRecordsExit(treeRecords, 4000);
+    if (remaining.length > 0) {
+      // These are immutable pre-taskkill descendants of the exact Agent tree,
+      // not globally matched ffmpeg processes.
+      for (const descendant of [...remaining].reverse()) {
+        await taskkillExactWindowsRecord(descendant, true);
+      }
+      remaining = await waitForExactRecordsExit(remaining, 4000);
+    }
+    if (remaining.length > 0) {
+      throw new Error(
+        `verified stale Windows Agent tree pid=${record.pid} retained exact descendant(s): `
+        + remaining.map(item => item.pid).join(', ')
+      );
+    }
+  };
+
+  const stoppedProcesses = new Map();
+  for (let auditRound = 1; auditRound <= 3; auditRound += 1) {
+    const staleProcesses = await findStaleProcesses();
+    if (staleProcesses.length === 0) break;
+    for (const record of staleProcesses) {
+      stoppedProcesses.set(`${record.type}:${record.instanceMarker}`, record);
+    }
+
+    const agents = staleProcesses.filter(record => record.type === 'agent');
+    const helpers = staleProcesses.filter(record => record.type === 'capture-helper');
+    if (os.platform() === 'win32') {
+      for (const record of agents) await terminateWindowsAgentTree(record);
+    } else {
+      for (const record of agents) await terminateUnixAgentGroup(record);
+      for (const record of helpers) await terminateExactUnixHelper(record);
+    }
+  }
+
+  const remainingProcesses = await findStaleProcesses();
+  if (remainingProcesses.length > 0) {
+    throw new Error(
+      'LiveDesk Client startup was stopped because new stale capture processes appeared during cleanup: '
+      + remainingProcesses.map(record => `${record.type} pid=${record.pid}`).join('; ')
+    );
+  }
+
+  const staleProcesses = [...stoppedProcesses.values()];
+  if (staleProcesses.length === 0) {
+    if (process.env.LIVEDESK_DEBUG === '1') {
+      console.log('[LiveDesk] Client lifecycle audit: verified stale agents=0 capture-helpers=0.');
+    }
+    return;
   }
   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(', ')}.`
+    + `capture-helpers=${helperPids.length}; confirmed stopped pids=${staleProcesses.map(item => item.pid).join(', ')}.`
   );
 }
 
@@ -1774,6 +2206,8 @@ async function main() {
   if (topLevel.noSingleInstance || process.env.LIVEDESK_DISABLE_SINGLE_INSTANCE === '1') {
     console.warn('[LiveDesk] Single-instance lock disabled for this run.');
   }
+  const launcherProcessDetails = await getProcessDetails(process.pid);
+  const launcherInstanceMarker = processInstanceMarker(launcherProcessDetails);
   const reportExistingRuntime = existing => {
     const port = DEFAULT_MANAGER_HTTP_PORT;
     openBrowser(`http://127.0.0.1:${port}`);
@@ -1784,6 +2218,7 @@ async function main() {
     : acquireRuntimeLock({
       stateDir: MANAGER_STATE_DIR,
       role: resolvedRole.role,
+      ownerInstanceMarker: launcherInstanceMarker,
       openExisting: () => undefined
     });
 
@@ -1794,6 +2229,7 @@ async function main() {
     lock = acquireRuntimeLock({
       stateDir: MANAGER_STATE_DIR,
       role: resolvedRole.role,
+      ownerInstanceMarker: launcherInstanceMarker,
       openExisting: () => undefined
     });
   }
@@ -1805,6 +2241,7 @@ async function main() {
       lock = acquireRuntimeLock({
         stateDir: MANAGER_STATE_DIR,
         role: resolvedRole.role,
+        ownerInstanceMarker: launcherInstanceMarker,
         openExisting: () => undefined
       });
     }
@@ -1821,7 +2258,13 @@ async function main() {
       DEFAULT_MANAGER_HTTP_PORT
     );
     await stopProcessesOnPorts([clientRuntimePort]);
-    await stopStaleUnixClientAgents();
+    const explicitMultiInstance = topLevel.noSingleInstance
+      || process.env.LIVEDESK_DISABLE_SINGLE_INSTANCE === '1';
+    if (!explicitMultiInstance) {
+      await stopStaleClientAgents();
+    } else if (process.env.LIVEDESK_DEBUG === '1') {
+      console.log('[LiveDesk] Client lifecycle audit skipped for explicit multi-instance mode.');
+    }
   }
 
   if (command === 'client') {