@livedesk/client 0.1.198 → 0.1.200

package/bin/livedesk-client.js

@@ -11,7 +11,13 @@ import net from 'node:net';
 import os from 'node:os';
 import { formatClientVersionBanner, readClientPackageVersion } from './client-version.js';
 import { createClientRuntimeServer } from '../src/runtime/client-runtime-server.js';
-import { installAgentTerminationHandlers } from '../src/runtime/agent-process-lifecycle.js';
+import {
+    createWindowsProcessTreeTracker,
+    drainOwnedWindowsAgentTree,
+    drainOwnedUnixAgentTree,
+    installAgentTerminationHandlers,
+    signalAgentTree
+} from '../src/runtime/agent-process-lifecycle.js';
 import { createHubWakeListener } from '../src/runtime/hub-wake-listener.js';
 import {
     inspectLinuxVideoAcceleration,
@@ -67,6 +73,22 @@ let networkChangeMonitor = null;
 const sessionRefreshesInFlight = new WeakMap();
 installAgentTerminationHandlers({ getAgentProcess: () => activeAgentProcess });
 
+function requestActiveAgentStop(signal = 'SIGTERM') {
+    const child = activeAgentProcess;
+    if (!child) return false;
+    if (process.platform === 'win32') {
+        // Internal reconnect/slot/role restarts use the same immutable
+        // PID+CreationDate tree contract as unexpected exit and terminal
+        // shutdown. Store the shared proof promise so no replacement can race.
+        if (!child.livedeskTreeStopPromise) {
+            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTree(child);
+        }
+        return true;
+    }
+    signalAgentTree(child, signal);
+    return true;
+}
+
 export function requestLocalDiscoveryWake(reason = 'local-trigger') {
     const previous = discoveryWakeController;
     discoveryWakeController = new AbortController();
@@ -2783,7 +2805,7 @@ async function startConnectionChoiceServer(supabase, options = {}) {
                     res.end(JSON.stringify({ ok: true, restarting: true, role: 'hub', roleVersion: nextRoleVersion }));
                     setTimeout(() => {
                         try {
-                            activeAgentProcess?.kill();
+                            requestActiveAgentStop();
                         } catch {
                         }
                         try {
@@ -3080,7 +3102,7 @@ async function chooseClientConnection(supabase, options = {}) {
                 writeLocalRoleCache(role, options.deviceId, roleVersion);
                 roleRestartRequest = { role, requestedAt: new Date().toISOString() };
                 requestLocalDiscoveryWake('role-change');
-                try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop observes the role request */ }
+                try { requestActiveAgentStop(); } catch { /* the lifecycle loop observes the role request */ }
                 return { ok: true, restarting: true, role, roleVersion };
             },
             videoAcceleration: linuxVideoAccelerationStatus,
@@ -3098,7 +3120,7 @@ async function chooseClientConnection(supabase, options = {}) {
                     requestedAt: new Date().toISOString()
                 };
                 requestLocalDiscoveryWake('linux-video-acceleration-ready');
-                try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the new ffmpeg preference */ }
+                try { requestActiveAgentStop(); } catch { /* the lifecycle loop restarts with the new ffmpeg preference */ }
             },
             assignSlot: async request => {
                 const result = await requestHubSlotAssignment(request);
@@ -3113,20 +3135,20 @@ async function chooseClientConnection(supabase, options = {}) {
                 };
                 requestLocalDiscoveryWake('slot-updated');
                 setTimeout(() => {
-                    try { activeAgentProcess?.kill(); } catch { /* the lifecycle loop restarts with the saved slot */ }
+                    try { requestActiveAgentStop(); } catch { /* the lifecycle loop restarts with the saved slot */ }
                 }, 150);
                 return { ...result, slotNumber, saved: true, restarting: true };
             },
             onRestart: () => process.kill(process.pid, 'SIGTERM'),
             onShutdown: () => process.kill(process.pid, 'SIGTERM'),
-            onDisconnect: () => activeAgentProcess?.kill(),
+            onDisconnect: () => requestActiveAgentStop(),
             // Ending the current Agent causes the unified lifecycle loop to
             // discard its old manager/pair token and start Supabase discovery
             // again.  Leaving this empty made the Reconnect button a success
             // response with no actual transport work.
             onReconnect: () => {
                 requestLocalDiscoveryWake('manual-reconnect');
-                activeAgentProcess?.kill();
+                requestActiveAgentStop();
             }
         });
         await connectionPage.start();
@@ -4103,6 +4125,7 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
         restartVerified: false
     });
     const ownsProcessGroup = process.platform !== 'win32';
+    const agentSpawnedAtMs = Date.now();
     const child = spawn(command, args, {
         env,
         stdio: 'inherit',
@@ -4113,24 +4136,78 @@ function spawnAgent(command, args, env = process.env, onStart = null) {
         windowsHide: true
     });
     child.livedeskOwnsProcessGroup = ownsProcessGroup;
+    child.livedeskWindowsTreeTracker = createWindowsProcessTreeTracker(child, {
+        spawnedAtMs: agentSpawnedAtMs
+    });
     activeAgentProcess = child;
     if (typeof onStart === 'function') {
         onStart(child);
     }
 
-    return new Promise(resolve => {
-        child.once('error', error => {
-            console.error(`Failed to launch ${command}: ${error.message}`);
-            resolve({ code: 1, signal: null });
-        });
-        child.once('exit', (code, signal) => {
-            if (activeAgentProcess === child) {
-                activeAgentProcess = null;
-            }
-            resolve({ code: code ?? 0, signal });
-        });
-    });
-}
+    return new Promise(resolve => {
+        let settling = false;
+        child.once('error', error => {
+            if (settling) return;
+            settling = true;
+            child.livedeskWindowsTreeTracker?.stop?.();
+            if (activeAgentProcess === child) {
+                activeAgentProcess = null;
+            }
+            console.error(`Failed to launch ${command}: ${error.message}`);
+            resolve({ code: 1, signal: null });
+        });
+        child.once('exit', (code, signal) => {
+            if (settling) return;
+            settling = true;
+            child.livedeskWindowsTreeTracker?.markRootExited?.();
+            // The Unix Agent is a dedicated process-group leader. Its exit
+            // event proves only that the leader stopped; SCK/FFmpeg capture
+            // descendants can still own that PGID. Keep active ownership and
+            // do not let the lifecycle loop launch a replacement until the
+            // complete group has drained.
+            void (async () => {
+                try {
+                    if (process.platform === 'win32') {
+                        if (!child.livedeskTreeStopPromise) {
+                            child.livedeskTreeStopPromise = drainOwnedWindowsAgentTree(child);
+                        }
+                        const windowsTreeStop = await child.livedeskTreeStopPromise;
+                        if (windowsTreeStop?.ok === false) {
+                            throw new Error(
+                                `exact Windows Agent tree drain failed: `
+                                + `${windowsTreeStop.error?.message || 'bounded immutable-tree cleanup failed'}`
+                            );
+                        }
+                    }
+                    await drainOwnedUnixAgentTree(child);
+                } catch (error) {
+                    console.error(
+                        `[LiveDesk Client] Could not drain exited Agent tree pid=${child.pid || 'unknown'}: `
+                        + `${error?.message || error}`
+                    );
+                    // Block this lifecycle iteration from spawning a
+                    // replacement, but settle explicitly so the launcher
+                    // terminates instead of hanging forever.
+                    child.livedeskWindowsTreeTracker?.stop?.();
+                    if (activeAgentProcess === child) {
+                        activeAgentProcess = null;
+                    }
+                    resolve({
+                        code: 1,
+                        signal: null,
+                        lifecycleFailure: String(error?.message || error)
+                    });
+                    return;
+                }
+                child.livedeskWindowsTreeTracker?.stop?.();
+                if (activeAgentProcess === child) {
+                    activeAgentProcess = null;
+                }
+                resolve({ code: code ?? 0, signal });
+            })();
+        });
+    });
+}
 
 function shouldUseFast(parsed) {
     if (parsed.engine === 'node') {
@@ -4286,9 +4363,36 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                     pid: child.pid,
                     startedAt: new Date().toISOString(),
                     state: 'running'
-                });
-            });
-        }
+                });
+            });
+        }
+        // Contract: once the owned Agent exits, the local runtime must stop
+        // advertising its old PID before any restart or Hub rediscovery.
+        // Keeping a dead PID makes status diagnostics lie and causes manual
+        // reconnect to target a process that no longer exists.
+        prepared.connectionPage?.update({
+            agent: {
+                requestedEngine: prepared.engine,
+                state: 'stopped',
+                pid: 0,
+                stoppedAt: new Date().toISOString(),
+                exitCode: Number.isInteger(result?.code) ? result.code : null,
+                exitSignal: result?.signal || ''
+            }
+        });
+        if (result?.lifecycleFailure) {
+            prepared.connectionPage?.update({
+                agent: {
+                    requestedEngine: prepared.engine,
+                    state: 'failed',
+                    pid: 0,
+                    error: result.lifecycleFailure
+                },
+                message: 'LiveDesk stopped because the previous Windows capture tree could not be drained safely.'
+            });
+            connectionPage?.close?.();
+            throw new Error(result.lifecycleFailure);
+        }
         const requestedRoleRestart = connectionPage?.getRoleRestartRequest?.();
         if (requestedRoleRestart?.role) {
             if (isTruthy(process.env.LIVEDESK_DESKTOP_HOST)) process.exit(43);
@@ -4302,7 +4406,8 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
             connectionPage?.update({
                 agent: {
                     requestedEngine: prepared.engine,
-                    state: 'reconnecting'
+                    state: 'reconnecting',
+                    pid: 0
                 },
                 message: restart.reason === 'slot-updated'
                     ? `Slot ${String(restart.slotNumber || prepared.slot || '').padStart(3, '0')} saved. Restarting the LiveDesk Agent.`
@@ -4331,10 +4436,11 @@ export async function runClientRuntime(argv = process.argv.slice(2)) {
                 ? 'LiveDesk Hub pair token changed. Refreshing Hub discovery now.'
                 : 'LiveDesk Hub connection ended. Looking for the current Hub now.');
             connectionPage?.update({
-                agent: {
-                    requestedEngine: prepared.engine,
-                    state: 'reconnecting'
-                },
+                agent: {
+                    requestedEngine: prepared.engine,
+                    state: 'reconnecting',
+                    pid: 0
+                },
                 manager: '',
                 message: 'The previous Hub is unavailable. LiveDesk is finding the current Hub automatically.'
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.198",
+  "version": "0.1.200",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -41,10 +41,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@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"
+    "@livedesk/fast-linux-x64": "0.1.407",
+    "@livedesk/fast-osx-arm64": "0.1.407",
+    "@livedesk/fast-osx-x64": "0.1.407",
+    "@livedesk/fast-win-x64": "0.1.407"
   },
   "publishConfig": {
     "access": "public"

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

@@ -1,51 +1,411 @@
 import { execFile } from 'node:child_process';
 
 const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
+const DEFAULT_WINDOWS_TREE_SNAPSHOT_MS = 10_000;
+const WINDOWS_SPAWN_CLOCK_TOLERANCE_MS = 250;
 
-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 normalizeWindowsProcessRecord(value) {
+    const pid = Number(value?.pid ?? value?.ProcessId ?? 0);
+    const parentPid = Number(value?.parentPid ?? value?.ParentProcessId ?? 0);
+    const startMarker = String(value?.startMarker ?? value?.CreationDate ?? '').trim();
+    const startOrder = String(value?.startOrder ?? value?.CreationUtcTicks ?? '').trim();
+    if (!Number.isInteger(pid)
+        || pid <= 1
+        || !startMarker
+        || !/^\d+$/.test(startOrder)) return null;
+    return { pid, parentPid, startMarker, startOrder };
+}
+
+function windowsRecordKey(record) {
+    return `${Number(record?.pid || 0)}:${String(record?.startOrder || '')}`;
+}
+
+function sameWindowsProcess(left, right) {
+    return Number(left?.pid || 0) === Number(right?.pid || 0)
+        && String(left?.startOrder || '') === String(right?.startOrder || '')
+        && String(left?.startMarker || '') === String(right?.startMarker || '');
+}
+
+function windowsTicksForUnixMilliseconds(milliseconds) {
+    return BigInt(Math.trunc(Number(milliseconds) || 0)) * 10_000n + 621_355_968_000_000_000n;
+}
+
+function windowsRecordIsWithinLifetime(record, spawnedAtMs, exitedAtMs = null) {
+    if (!record?.startOrder) return false;
+    try {
+        const order = BigInt(record.startOrder);
+        // spawnedAtMs is recorded immediately before spawn(). A small 250ms
+        // tolerance covers clock conversion/scheduling without admitting an
+        // old process whose stale ParentProcessId happens to equal the Agent.
+        const lower = windowsTicksForUnixMilliseconds(
+            Math.max(0, spawnedAtMs - WINDOWS_SPAWN_CLOCK_TOLERANCE_MS)
         );
+        const upper = exitedAtMs === null
+            ? windowsTicksForUnixMilliseconds(Date.now() + 5000)
+            : windowsTicksForUnixMilliseconds(exitedAtMs);
+        return order >= lower && order <= upper;
+    } catch {
+        return false;
+    }
+}
+
+function runExecFile(command, args, options = {}, execFileImpl = execFile) {
+    return new Promise(resolve => {
+        execFileImpl(command, args, options, (error, stdout, stderr) => {
+            resolve({
+                ok: !error,
+                error: error || null,
+                stdout: String(stdout || '').trim(),
+                stderr: String(stderr || '').trim()
+            });
+        });
     });
 }
 
-function isOwnedUnixProcessGroupAlive(child, platform, signalProcess) {
-    const processId = Number(child?.pid || 0);
-    if (platform === 'win32'
-        || child?.livedeskOwnsProcessGroup !== true
-        || !Number.isInteger(processId)
-        || processId <= 1) {
-        return false;
+/**
+ * Returns immutable PID + CreationDate records only. Command lines are
+ * intentionally excluded so no globally named ffmpeg process can become a
+ * termination target.
+ */
+export async function queryWindowsProcessTable({
+    execFileImpl = execFile
+} = {}) {
+    const script = [
+        '$ErrorActionPreference = "Stop";',
+        '@(Get-CimInstance Win32_Process | ForEach-Object {',
+        '  $creation = [string]$_.CreationDate;',
+        '  $ticks = if ($_.CreationDate) { [string]$_.CreationDate.ToUniversalTime().Ticks } else { "" };',
+        '  [pscustomobject]@{ ProcessId = [int]$_.ProcessId; ParentProcessId = [int]$_.ParentProcessId; CreationDate = $creation; CreationUtcTicks = $ticks }',
+        '}) | ConvertTo-Json -Compress'
+    ].join(' ');
+    const result = await runExecFile(
+        'powershell.exe',
+        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+        { windowsHide: true, timeout: 10000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024 },
+        execFileImpl
+    );
+    if (!result.ok || !result.stdout) {
+        throw new Error(
+            `Windows process-tree snapshot failed: `
+            + `${result.stderr || result.error?.message || 'CIM query returned no process records'}`
+        );
     }
+    let parsed;
     try {
-        signalProcess(-processId, 0);
-        return true;
+        parsed = JSON.parse(result.stdout);
     } catch (error) {
-        return error?.code === 'EPERM';
+        throw new Error(`Windows process-tree snapshot returned invalid JSON: ${error?.message || error}`);
+    }
+    return (Array.isArray(parsed) ? parsed : [parsed])
+        .map(normalizeWindowsProcessRecord)
+        .filter(Boolean);
+}
+
+/**
+ * Rechecks CreationDate inside the same PowerShell process immediately before
+ * taskkill. PID reuse therefore becomes a harmless identity mismatch instead
+ * of terminating the replacement process.
+ */
+export async function terminateExactWindowsProcessTree(record, {
+    includeTree = true,
+    execFileImpl = execFile
+} = {}) {
+    const target = normalizeWindowsProcessRecord(record);
+    if (!target) {
+        return { ok: false, error: new Error('An immutable Windows process record is required.') };
     }
+    const expectedStartTicks = target.startOrder;
+    const treeArgument = includeTree ? ', "/T"' : '';
+    const script = [
+        '$ErrorActionPreference = "Stop";',
+        `$targetPid = ${target.pid};`,
+        `$expectedStartTicks = '${expectedStartTicks}';`,
+        '$target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -ErrorAction SilentlyContinue | Select-Object -First 1;',
+        'if (-not $target) { exit 0 };',
+        '$targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" };',
+        'if ($targetStartTicks -ne $expectedStartTicks) { exit 0 };',
+        `$arguments = @("/PID", [string]$targetPid${treeArgument}, "/F");`,
+        '$taskkill = Start-Process -FilePath "taskkill.exe" -ArgumentList $arguments -NoNewWindow -Wait -PassThru;',
+        'exit $taskkill.ExitCode'
+    ].join(' ');
+    return runExecFile(
+        'powershell.exe',
+        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+        { windowsHide: true, timeout: 15000, killSignal: 'SIGKILL' },
+        execFileImpl
+    );
 }
 
-function isProcessIdAlive(processId, signalProcess) {
-    if (!Number.isInteger(processId) || processId <= 1) {
+/**
+ * Tracks the exact Agent root and only descendants connected through Windows
+ * ParentProcessId records. The default 10-second cadence is deliberately low
+ * overhead; refreshes are serialized and the timer is unref'd. A final
+ * snapshot covers normal direct FFmpeg children even between timer samples.
+ */
+export function createWindowsProcessTreeTracker(child, {
+    platform = process.platform,
+    queryProcessTableImpl = queryWindowsProcessTable,
+    snapshotIntervalMs = DEFAULT_WINDOWS_TREE_SNAPSHOT_MS,
+    spawnedAtMs = Date.now(),
+    setIntervalImpl = setInterval,
+    clearIntervalImpl = clearInterval
+} = {}) {
+    const rootPid = Number(child?.pid || 0);
+    const enabled = platform === 'win32' && Number.isInteger(rootPid) && rootPid > 1;
+    const tracked = new Map();
+    let rootRecord = null;
+    let lastSnapshot = [];
+    let lastError = null;
+    let inFlight = null;
+    let stopped = false;
+    let timer = null;
+    let rootExitedAtMs = null;
+    let rootCapturedBeforeExit = false;
+    let lastSnapshotHadRootPid = false;
+    let successfulSnapshotAfterExit = false;
+    let ambiguousRootReuse = false;
+
+    const mergeSnapshot = snapshot => {
+        const records = (Array.isArray(snapshot) ? snapshot : [])
+            .map(normalizeWindowsProcessRecord)
+            .filter(Boolean);
+        lastSnapshot = records;
+        if (rootExitedAtMs !== null) successfulSnapshotAfterExit = true;
+        const currentByPid = new Map(records.map(record => [record.pid, record]));
+        const currentRoot = currentByPid.get(rootPid) || null;
+        lastSnapshotHadRootPid = Boolean(currentRoot);
+        if (rootRecord && currentRoot && !sameWindowsProcess(currentRoot, rootRecord)) {
+            ambiguousRootReuse = true;
+        }
+        if (!rootRecord
+            && currentRoot
+            && windowsRecordIsWithinLifetime(currentRoot, spawnedAtMs, rootExitedAtMs)) {
+            rootCapturedBeforeExit = rootExitedAtMs === null;
+            rootRecord = {
+                ...currentRoot,
+                depth: 0,
+                targetable: rootCapturedBeforeExit
+            };
+            if (rootRecord.targetable) {
+                tracked.set(windowsRecordKey(rootRecord), rootRecord);
+            }
+        }
+
+        const exactCurrentByPid = new Map();
+        if (rootRecord && currentRoot && sameWindowsProcess(currentRoot, rootRecord)) {
+            exactCurrentByPid.set(rootPid, rootRecord);
+        }
+        for (const record of tracked.values()) {
+            const current = currentByPid.get(record.pid);
+            if (current && sameWindowsProcess(current, record)) {
+                exactCurrentByPid.set(record.pid, record);
+            }
+        }
+
+        // If the root PID is absent, Windows retains ParentProcessId on its
+        // surviving direct children. If the PID has already been reused, do
+        // not infer any new lineage through that ambiguous numeric PID.
+        const rootAbsent = !currentRoot;
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const record of records) {
+                if (record.pid === rootPid || tracked.has(windowsRecordKey(record))) continue;
+                if (!windowsRecordIsWithinLifetime(record, spawnedAtMs, rootExitedAtMs)) continue;
+                let parent = exactCurrentByPid.get(record.parentPid) || null;
+                if (!parent
+                    && rootExitedAtMs !== null
+                    && rootAbsent
+                    && record.parentPid === rootPid) {
+                    parent = rootRecord || { pid: rootPid, depth: 0 };
+                }
+                if (!parent) continue;
+                const descendant = { ...record, depth: Number(parent.depth || 0) + 1 };
+                tracked.set(windowsRecordKey(descendant), descendant);
+                exactCurrentByPid.set(descendant.pid, descendant);
+                changed = true;
+            }
+        }
+    };
+
+    const refresh = async () => {
+        if (!enabled) return { ok: true, records: [] };
+        if (inFlight) return inFlight;
+        inFlight = Promise.resolve()
+            .then(() => queryProcessTableImpl())
+            .then(snapshot => {
+                mergeSnapshot(snapshot);
+                lastError = null;
+                return { ok: true, records: lastSnapshot };
+            })
+            .catch(error => {
+                lastError = error;
+                return { ok: false, error, records: lastSnapshot };
+            })
+            .finally(() => {
+                inFlight = null;
+            });
+        return inFlight;
+    };
+
+    const ready = enabled ? refresh() : Promise.resolve({ ok: true, records: [] });
+    if (enabled) {
+        const boundedInterval = Math.max(5000, Number(snapshotIntervalMs) || DEFAULT_WINDOWS_TREE_SNAPSHOT_MS);
+        timer = setIntervalImpl(() => {
+            if (!stopped) void refresh();
+        }, boundedInterval);
+        timer?.unref?.();
+    }
+
+    return {
+        enabled,
+        ready,
+        refresh,
+        stop() {
+            stopped = true;
+            if (timer) clearIntervalImpl(timer);
+            timer = null;
+        },
+        getRootRecord: () => rootRecord ? { ...rootRecord } : null,
+        markRootExited(exitedAtMs = Date.now()) {
+            if (rootExitedAtMs === null) {
+                rootExitedAtMs = Number(exitedAtMs) || Date.now();
+                successfulSnapshotAfterExit = false;
+            }
+        },
+        hasSafeFinalSnapshot() {
+            return rootCapturedBeforeExit
+                || (rootExitedAtMs !== null && successfulSnapshotAfterExit && !lastSnapshotHadRootPid);
+        },
+        hasAmbiguousRootReuse: () => ambiguousRootReuse,
+        getTrackedRecords: () => [...tracked.values()].map(record => ({ ...record })),
+        getCurrentExactRecords() {
+            const currentByPid = new Map(lastSnapshot.map(record => [record.pid, record]));
+            return [...tracked.values()]
+                .filter(record => sameWindowsProcess(currentByPid.get(record.pid), record))
+                .map(record => ({ ...record }));
+        },
+        getLastError: () => lastError
+    };
+}
+
+/**
+ * Bounded exact-tree drain used by internal restarts, unexpected exits, and
+ * terminal shutdown. A nonzero taskkill is not itself failure: each attempt is
+ * followed by a fresh immutable snapshot, and an already-gone tree succeeds.
+ */
+export async function drainOwnedWindowsAgentTree(child, {
+    platform = process.platform,
+    queryProcessTableImpl = queryWindowsProcessTable,
+    terminateExactTreeImpl = terminateExactWindowsProcessTree,
+    maxAttempts = 3,
+    retryMs = 100,
+    waitImpl = waitMilliseconds,
+    reportTerminationFailure = message => console.error(message)
+} = {}) {
+    if (platform !== 'win32') return { ok: true, remaining: [] };
+    if (child?.livedeskWindowsDrainPromise) return child.livedeskWindowsDrainPromise;
+
+    child.livedeskWindowsDrainPromise = (async () => {
+        const tracker = child?.livedeskWindowsTreeTracker
+            || createWindowsProcessTreeTracker(child, { platform, queryProcessTableImpl });
+        child.livedeskWindowsTreeTracker = tracker;
+        if (child?.exitCode !== null && child?.exitCode !== undefined) {
+            tracker.markRootExited?.();
+        }
+        tracker.stop();
+        await tracker.ready;
+        const attempts = Math.max(1, Number(maxAttempts) || 3);
+        let identityRefresh = await tracker.refresh();
+        let identityAttempt = 1;
+        let rootRecord = tracker.getRootRecord();
+        while ((!rootRecord || rootRecord.targetable === false)
+            && !tracker.hasSafeFinalSnapshot?.()
+            && identityAttempt < attempts) {
+            await waitImpl(Math.max(25, Number(retryMs) || 100));
+            identityAttempt += 1;
+            identityRefresh = await tracker.refresh();
+            rootRecord = tracker.getRootRecord();
+        }
+        if ((!rootRecord || rootRecord.targetable === false)
+            && !tracker.hasSafeFinalSnapshot?.()) {
+            const error = identityRefresh?.error || tracker.getLastError()
+                || new Error(
+                    `Agent pid=${Number(child?.pid || 0)} could not establish an immutable root identity `
+                    + 'or a safe root-absent exit snapshot.'
+                );
+            return { ok: false, error, remaining: [] };
+        }
+
+        let lastError = null;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            const refresh = await tracker.refresh();
+            if (!refresh.ok) {
+                lastError = refresh.error;
+            } else {
+                const remaining = tracker.getCurrentExactRecords();
+                if (remaining.length === 0
+                    && tracker.hasSafeFinalSnapshot?.()
+                    && !tracker.hasAmbiguousRootReuse?.()) {
+                    return { ok: true, remaining: [] };
+                }
+                const ordered = [...remaining].sort((left, right) => (
+                    Number(left.depth || 0) - Number(right.depth || 0)
+                ));
+                for (const record of ordered) {
+                    const termination = await terminateExactTreeImpl(record, { includeTree: true });
+                    if (termination?.ok === false) lastError = termination.error || lastError;
+                }
+            }
+            if (attempt < attempts) {
+                await waitImpl(Math.max(25, Number(retryMs) || 100));
+            }
+        }
+
+        const finalRefresh = await tracker.refresh();
+        const remaining = finalRefresh.ok ? tracker.getCurrentExactRecords() : tracker.getTrackedRecords();
+        if (finalRefresh.ok
+            && remaining.length === 0
+            && tracker.hasSafeFinalSnapshot?.()
+            && !tracker.hasAmbiguousRootReuse?.()) {
+            return { ok: true, remaining: [] };
+        }
+        const error = finalRefresh.error || lastError || new Error(
+            tracker.hasAmbiguousRootReuse?.()
+                ? `Agent pid=${Number(child?.pid || 0)} was reused before exact descendant cleanup completed.`
+                : `Exact Windows Agent tree retained pid(s): ${remaining.map(record => record.pid).join(', ')}`
+        );
+        reportTerminationFailure(
+            `[LiveDesk Client] Exact Windows Agent tree could not be drained after `
+            + `${attempts} bounded attempt(s): ${error?.message || error}`
+        );
+        return { ok: false, error, remaining };
+    })();
+    return child.livedeskWindowsDrainPromise;
+}
+
+export function isOwnedUnixProcessGroupAlive(child, platform = process.platform, signalProcess = (pid, signal) => process.kill(pid, signal)) {
+    const processId = Number(child?.pid || 0);
+    if (platform === 'win32'
+        || child?.livedeskOwnsProcessGroup !== true
+        || !Number.isInteger(processId)
+        || processId <= 1) {
         return false;
     }
     try {
-        signalProcess(processId, 0);
+        signalProcess(-processId, 0);
         return true;
     } catch (error) {
         return error?.code === 'EPERM';
     }
 }
 
-function signalAgentTree(child, signal, platform, signalProcess) {
+export function signalAgentTree(
+    child,
+    signal,
+    platform = process.platform,
+    signalProcess = (pid, requestedSignal) => process.kill(pid, requestedSignal)
+) {
     const processId = Number(child?.pid || 0);
     if (platform !== 'win32'
         && child?.livedeskOwnsProcessGroup === true
@@ -61,15 +421,102 @@ function signalAgentTree(child, signal, platform, signalProcess) {
     child.kill(signal);
 }
 
+function waitMilliseconds(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+/**
+ * Contract:
+ * - Applies only to a Unix Agent that this launcher spawned as a dedicated
+ *   detached process-group leader.
+ * - Resolves only after the owned PGID no longer exists.
+ * - Never searches for, or signals, ffmpeg/SCK processes by global name.
+ * - A surviving capture descendant keeps the original PGID alive, so group
+ *   signaling drains it without having to identify that descendant globally.
+ */
+export async function drainOwnedUnixAgentTree(child, {
+    platform = process.platform,
+    signalProcess = (pid, signal) => process.kill(pid, signal),
+    gracefulSignal = 'SIGTERM',
+    gracefulTimeoutMs = 1000,
+    hardRetryMs = 1000,
+    pollMs = 50,
+    reportTerminationFailure = message => console.error(message)
+} = {}) {
+    const processId = Number(child?.pid || 0);
+    const ownsUnixGroup = platform !== 'win32'
+        && child?.livedeskOwnsProcessGroup === true
+        && Number.isInteger(processId)
+        && processId > 1;
+    if (!ownsUnixGroup || !isOwnedUnixProcessGroupAlive(child, platform, signalProcess)) {
+        return;
+    }
+
+    const signalOwnedGroup = signal => {
+        try {
+            signalProcess(-processId, signal);
+            return true;
+        } catch (error) {
+            if (error?.code === 'ESRCH') return false;
+            throw error;
+        }
+    };
+    try {
+        signalOwnedGroup(gracefulSignal);
+    } catch (error) {
+        reportTerminationFailure(
+            `[LiveDesk Client] Exited Agent group pid=${processId} rejected ${gracefulSignal} `
+            + `(${error?.message || error}); forced cleanup will continue.`
+        );
+    }
+
+    const gracefulDeadline = Date.now() + Math.max(100, Number(gracefulTimeoutMs) || 1000);
+    const boundedPollMs = Math.max(10, Number(pollMs) || 50);
+    while (Date.now() < gracefulDeadline) {
+        if (!isOwnedUnixProcessGroupAlive(child, platform, signalProcess)) return;
+        await waitMilliseconds(Math.min(boundedPollMs, Math.max(1, gracefulDeadline - Date.now())));
+    }
+
+    let failureReported = false;
+    const retryMs = Math.max(100, Number(hardRetryMs) || 1000);
+    while (isOwnedUnixProcessGroupAlive(child, platform, signalProcess)) {
+        try {
+            signalOwnedGroup('SIGKILL');
+        } catch (error) {
+            if (!failureReported) {
+                failureReported = true;
+                reportTerminationFailure(
+                    `[LiveDesk Client] Exited Agent group pid=${processId} rejected SIGKILL `
+                    + `(${error?.message || error}). The launcher will not start a replacement until the group drains.`
+                );
+            }
+        }
+        if (!isOwnedUnixProcessGroupAlive(child, platform, signalProcess)) return;
+        if (!failureReported) {
+            failureReported = true;
+            reportTerminationFailure(
+                `[LiveDesk Client] Exited Agent group pid=${processId} still has capture descendants after SIGKILL. `
+                + 'The launcher will not start a replacement until the group drains.'
+            );
+        }
+        const retryDeadline = Date.now() + retryMs;
+        while (Date.now() < retryDeadline) {
+            if (!isOwnedUnixProcessGroupAlive(child, platform, signalProcess)) return;
+            await waitMilliseconds(Math.min(boundedPollMs, Math.max(1, retryDeadline - Date.now())));
+        }
+    }
+}
+
 export function installAgentTerminationHandlers({
     hostProcess = process,
     getAgentProcess,
     shutdownTimeoutMs = 8000,
     platform = process.platform,
     signalProcess = (pid, signal) => process.kill(pid, signal),
-    terminateWindowsTree = terminateWindowsProcessTree,
+    drainWindowsTree = drainOwnedWindowsAgentTree,
     windowsTerminateAttemptLimit = 3,
     windowsTerminateRetryMs = 100,
+    unixTerminateRetryMs = 1000,
     reportTerminationFailure = message => console.error(message),
     exitProcess = code => hostProcess.exit(code)
 } = {}) {
@@ -85,7 +532,19 @@ export function installAgentTerminationHandlers({
             terminating = true;
             const exitCode = SIGNAL_EXIT_CODES[signal] || 1;
             const child = getAgentProcess();
-            if (!child || child.exitCode !== null) {
+            if (!child) {
+                exitProcess(exitCode);
+                return;
+            }
+            const exitedUnixLeaderStillOwnsGroup = platform !== 'win32'
+                && child?.livedeskOwnsProcessGroup === true
+                && child.exitCode !== null
+                && isOwnedUnixProcessGroupAlive(child, platform, signalProcess);
+            // Windows must still drain immutable recorded descendants when
+            // Ctrl+C arrives after the Agent leader has already exited.
+            if (platform !== 'win32'
+                && child.exitCode !== null
+                && !exitedUnixLeaderStillOwnsGroup) {
                 exitProcess(exitCode);
                 return;
             }
@@ -93,15 +552,13 @@ export function installAgentTerminationHandlers({
             let finished = false;
             let poll = null;
             let timeout = null;
-            let hardStop = null;
-            let windowsRetryTimer = null;
+            let unixRetryTimer = null;
             const finish = () => {
                 if (finished) return;
                 finished = true;
                 if (poll) clearInterval(poll);
                 if (timeout) clearTimeout(timeout);
-                if (hardStop) clearTimeout(hardStop);
-                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
+                if (unixRetryTimer) clearTimeout(unixRetryTimer);
                 exitProcess(exitCode);
             };
             const processId = Number(child?.pid || 0);
@@ -110,58 +567,29 @@ export function installAgentTerminationHandlers({
                     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
+                // Use the same immutable PID + CreationDate drain as internal
+                // restarts and unexpected Agent exits. The promise is stored
+                // on the child so spawnAgent cannot race ahead and launch a
+                // replacement while terminal shutdown is still draining.
+                if (!child.livedeskTreeStopPromise) {
+                    child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
+                        platform,
+                        maxAttempts: windowsTerminateAttemptLimit,
+                        retryMs: windowsTerminateRetryMs,
+                        reportTerminationFailure
+                    }));
+                }
+                child.livedeskTreeStopPromise
+                    .catch(error => ({ ok: false, error }))
+                    .then(result => {
+                        if (result?.ok === false) {
+                            reportTerminationFailure(
+                                `[LiveDesk Client] Terminal shutdown preserved an undrained exact Windows Agent tree: `
+                                + `${result.error?.message || 'bounded drain failed'}`
                             );
-                        });
-                };
-                terminateOwnedTree();
+                        }
+                        finish();
+                    });
                 return;
             }
             const finishWhenTreeStops = () => {
@@ -170,28 +598,60 @@ export function installAgentTerminationHandlers({
                 const childAlive = child.exitCode === null && child.signalCode == null;
                 const groupAlive = ownsUnixGroup
                     && isOwnedUnixProcessGroupAlive(child, platform, signalProcess);
-                if (!childAlive && !groupAlive) {
+                // A missing owned process group proves that both its Agent
+                // leader and capture descendants are gone even if Node has not
+                // delivered the child exit event yet.
+                if (ownsUnixGroup ? !groupAlive : !childAlive) {
                     finish();
                 }
             };
             child.once('exit', finishWhenTreeStops);
             try {
                 signalAgentTree(child, signal, platform, signalProcess);
-            } catch {
-                finish();
-                return;
+            } catch (error) {
+                reportTerminationFailure(
+                    `[LiveDesk Client] Agent tree pid=${processId || 'unknown'} could not receive ${signal} `
+                    + `(${error?.message || error}). Forced cleanup will continue.`
+                );
             }
             poll = setInterval(finishWhenTreeStops, 50);
-            timeout = setTimeout(() => {
+            const retryMs = Math.max(100, Number(unixTerminateRetryMs) || 1000);
+            let hardFailureReported = false;
+            const terminateOwnedUnixTree = () => {
+                if (finished) return;
+                finishWhenTreeStops();
+                if (finished) return;
                 try {
                     signalAgentTree(child, 'SIGKILL', platform, signalProcess);
-                } catch {
+                } catch (error) {
+                    if (!hardFailureReported) {
+                        hardFailureReported = true;
+                        reportTerminationFailure(
+                            `[LiveDesk Client] Agent tree pid=${processId || 'unknown'} rejected SIGKILL `
+                            + `(${error?.message || error}). The launcher will remain alive and retry.`
+                        );
+                    }
                 }
-                hardStop = setTimeout(finish, 250);
+                finishWhenTreeStops();
+                if (finished) return;
+                if (!hardFailureReported) {
+                    hardFailureReported = true;
+                    reportTerminationFailure(
+                        `[LiveDesk Client] Agent tree pid=${processId || 'unknown'} is still alive after SIGKILL. `
+                        + 'The launcher will remain alive and keep retrying so capture descendants are not orphaned.'
+                    );
+                }
+                unixRetryTimer = setTimeout(terminateOwnedUnixTree, retryMs);
+            };
+            timeout = setTimeout(() => {
+                terminateOwnedUnixTree();
             }, Math.max(100, Number(shutdownTimeoutMs) || 3000));
         };
         handlers.set(signal, handler);
-        hostProcess.once(signal, handler);
+        // Keep the listener installed while cleanup is in progress. A second
+        // Ctrl+C must not restore Node's default immediate exit and orphan the
+        // process group that the first signal is still draining.
+        hostProcess.on(signal, handler);
     }
 
     return () => {