fix(apex): defensive LS shutdown to prevent orphaned processes

- Await client.stop() with 3s timeout so LS can gracefully close DB
- Force-kill child Apex LS processes only when stop() times out
- Do not push client to subscriptions; cleanup only in deactivate()
- Dynamic JDWP port (0) to avoid port-in-use when previous session orphaned
- Explicit outputChannel dispose, client.dispose(), setClientInstance clear
@W-21681520@

Author: peternhale

packages/salesforcedx-vscode-apex/src/index.ts

@@ -22,6 +22,9 @@ import {
 import { nls } from './messages';
 import { getTelemetryService, setTelemetryService } from './telemetry/telemetry';
 
+/** Time to await graceful LSP shutdown before force-kill. LS uses this to close its internal DB. */
+const DEACTIVATE_STOP_TIMEOUT_MS = 3000;
+
 export const activate = async (context: vscode.ExtensionContext) => {
   const vscodeCoreExtension = await getVscodeCoreExtension();
   const workspaceContext = vscodeCoreExtension.exports.WorkspaceContext.getInstance();
@@ -97,7 +100,23 @@ const registerCommands = (context: vscode.ExtensionContext): vscode.Disposable =
 };
 
 export const deactivate = async () => {
-  await languageClientManager.getClientInstance()?.stop();
+  const client = languageClientManager.getClientInstance();
+  if (client) {
+    let timedOut = false;
+    const stopPromise = client.stop();
+    const timeoutPromise = new Promise<void>(resolve =>
+      setTimeout(() => {
+        timedOut = true;
+        resolve();
+      }, DEACTIVATE_STOP_TIMEOUT_MS)
+    );
+    await Promise.race([stopPromise, timeoutPromise]);
+    if (timedOut) {
+      languageClientManager.killChildApexProcesses();
+    }
+  } else {
+    languageClientManager.killChildApexProcesses();
+  }
   getTelemetryService().sendExtensionDeactivationEvent();
 };
 

packages/salesforcedx-vscode-apex/src/languageServer.ts

@@ -41,7 +41,8 @@ import {
 } from './settings';
 import { getTelemetryService } from './telemetry/telemetry';
 
-const JDWP_DEBUG_PORT = 2739;
+/** Use 0 for dynamic JDWP port to avoid "address in use" when previous LS orphaned (e.g. Extension Host not shut down cleanly). */
+const JDWP_DEBUG_PORT = 0;
 const APEX_LANGUAGE_SERVER_MAIN = 'apex.jorje.lsp.ApexLanguageServerLauncher';
 const SUSPEND_LANGUAGE_SERVER_STARTUP = process.env.SUSPEND_LANGUAGE_SERVER_STARTUP === 'true';
 const LANGUAGE_SERVER_LOG_LEVEL = process.env.LANGUAGE_SERVER_LOG_LEVEL ?? 'ERROR';

packages/salesforcedx-vscode-apex/src/languageUtils/languageClientManager.ts

@@ -322,7 +322,8 @@ export class LanguageClientManager {
           activationTime: startTime
         });
         await this.indexerDoneHandler(retrieveEnableSyncInitJobs(), languageClient, languageServerStatusBarItem);
-        extensionContext.subscriptions.push(this.getClientInstance()!);
+        // Do NOT push client to subscriptions - cleanup is handled only in deactivate() with timeout + force-kill.
+        // Pushing to subscriptions causes client.dispose() to run on shutdown, which can block if LS doesn't exit.
       } else {
         const errorMessage = nls.localize('unknown');
         this.setStatus(ClientStatus.Error, `${nls.localize('apex_language_server_failed_activate')} - ${errorMessage}`);
@@ -422,6 +423,42 @@ export class LanguageClientManager {
     process.kill(pid, 'SIGKILL');
   }
 
+  /**
+   * Find and SIGKILL Apex LS processes that are direct children of the current process.
+   * Used when LSP shutdown times out so the extension host can exit (child's stdio pipes close).
+   */
+  public killChildApexProcesses(): void {
+    const isWindows = process.platform === 'win32';
+    if (!this.canRunCheck(isWindows)) {
+      return;
+    }
+    const parentPid = process.pid;
+    const cmd = isWindows
+      ? `powershell.exe -command "Get-CimInstance -ClassName Win32_Process | Where-Object { $_.ParentProcessId -eq ${parentPid} } | ForEach-Object { [PSCustomObject]@{ ProcessId = $_.ProcessId; CommandLine = $_.CommandLine } } | Format-Table -HideTableHeaders"`
+      : 'ps -e -o pid,ppid,command';
+    try {
+      const stdout = execSync(cmd).toString();
+      const lines = stdout.trim().split(/\r?\n/g);
+      for (const line of lines) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 3) continue;
+        const pid = parseInt(parts[0], 10);
+        const ppid = parseInt(parts[1], 10);
+        const command = parts.slice(2).join(' ');
+        if (Number.isNaN(pid) || Number.isNaN(ppid)) continue;
+        if (ppid === parentPid && command.includes('apex-jorje-lsp.jar')) {
+          try {
+            this.terminateProcess(pid);
+          } catch {
+            // Process may already be gone
+          }
+        }
+      }
+    } catch {
+      // Ignore ps/exec errors
+    }
+  }
+
   public canRunCheck(isWindows: boolean): boolean {
     if (isWindows) {
       try {

packages/salesforcedx-vscode-apex/test/jest/index.test.ts

@@ -251,9 +251,11 @@ describe('index tests', () => {
       stopSpy = jest.fn();
       telemetryServiceMock = new MockTelemetryService();
       (getTelemetryService as jest.Mock).mockReturnValue(telemetryServiceMock);
-      jest
-        .spyOn(languageClientManager, 'getClientInstance')
-        .mockReturnValue({ stop: stopSpy } as unknown as ApexLanguageClient);
+      jest.spyOn(languageClientManager, 'getClientInstance').mockReturnValue({
+        stop: stopSpy,
+        dispose: jest.fn(),
+        outputChannel: { dispose: jest.fn() }
+      } as unknown as ApexLanguageClient);
     });
 
     it('should call stop on the language client', async () => {