@livedesk/client 0.1.199 → 0.1.201

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

@@ -1,51 +1,460 @@
 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;
+}
+
+/**
+ * Fail-closed wrapper for lifecycle replacement and terminal shutdown.
+ * A bounded drain attempt can fail because CIM/taskkill is temporarily busy;
+ * that must never let the launcher exit and orphan an owned FFmpeg descendant.
+ */
+export async function drainOwnedWindowsAgentTreeUntilStopped(child, {
+    platform = process.platform,
+    retryForeverMs = 1000,
+    waitImpl = waitMilliseconds,
+    reportTerminationFailure = message => console.error(message),
+    ...drainOptions
+} = {}) {
+    if (platform !== 'win32') return { ok: true, remaining: [] };
+    if (child?.livedeskWindowsDrainUntilStoppedPromise) {
+        return child.livedeskWindowsDrainUntilStoppedPromise;
+    }
+
+    child.livedeskWindowsDrainUntilStoppedPromise = (async () => {
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            // drainOwnedWindowsAgentTree memoizes one bounded proof attempt.
+            // Clear only that completed attempt; the immutable tracker remains
+            // attached to the exact child and is refreshed on every retry.
+            child.livedeskWindowsDrainPromise = null;
+            let result;
+            try {
+                result = await drainOwnedWindowsAgentTree(child, {
+                    platform,
+                    waitImpl,
+                    reportTerminationFailure,
+                    ...drainOptions
+                });
+            } catch (error) {
+                result = { ok: false, error, remaining: [] };
+            }
+            if (result?.ok !== false) {
+                return result;
+            }
+            reportTerminationFailure(
+                `[LiveDesk Client] Exact Windows Agent tree is not drained yet `
+                + `(attempt ${attempt}); the launcher will remain alive and retry.`
+            );
+            await waitImpl(Math.max(100, Number(retryForeverMs) || 1000));
+        }
+    })();
+    return child.livedeskWindowsDrainUntilStoppedPromise;
+}
+
+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 +470,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 = drainOwnedWindowsAgentTreeUntilStopped,
     windowsTerminateAttemptLimit = 3,
     windowsTerminateRetryMs = 100,
+    unixTerminateRetryMs = 1000,
     reportTerminationFailure = message => console.error(message),
     exitProcess = code => hostProcess.exit(code)
 } = {}) {
@@ -85,7 +581,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,14 +601,14 @@ export function installAgentTerminationHandlers({
             let finished = false;
             let poll = null;
             let timeout = null;
-            let hardStop = null;
+            let unixRetryTimer = null;
             let windowsRetryTimer = null;
             const finish = () => {
                 if (finished) return;
                 finished = true;
                 if (poll) clearInterval(poll);
                 if (timeout) clearTimeout(timeout);
-                if (hardStop) clearTimeout(hardStop);
+                if (unixRetryTimer) clearTimeout(unixRetryTimer);
                 if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
                 exitProcess(exitCode);
             };
@@ -110,58 +618,41 @@ 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 = () => {
+                // 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.
+                const drainUntilStopped = () => {
                     if (finished) return;
-                    attempt += 1;
-                    let treeTermination;
-                    try {
-                        treeTermination = terminateWindowsTree(processId);
-                    } catch (error) {
-                        treeTermination = { ok: false, error };
+                    if (!child.livedeskTreeStopPromise) {
+                        child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
+                            platform,
+                            maxAttempts: windowsTerminateAttemptLimit,
+                            retryMs: windowsTerminateRetryMs,
+                            retryForeverMs: windowsTerminateRetryMs,
+                            reportTerminationFailure
+                        }));
                     }
-                    Promise.resolve(treeTermination)
+                    child.livedeskTreeStopPromise
                         .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;
-                            }
+                            reportTerminationFailure(
+                                `[LiveDesk Client] Terminal shutdown retained an exact Windows Agent tree: `
+                                + `${result.error?.message || 'bounded drain failed'}. Retrying before exit.`
+                            );
+                            child.livedeskTreeStopPromise = null;
+                            child.livedeskWindowsDrainPromise = null;
                             windowsRetryTimer = setTimeout(
-                                terminateOwnedTree,
-                                burstExhausted ? Math.max(1000, retryMs) : retryMs
+                                drainUntilStopped,
+                                Math.max(100, Number(windowsTerminateRetryMs) || 100)
                             );
                         });
                 };
-                terminateOwnedTree();
+                drainUntilStopped();
                 return;
             }
             const finishWhenTreeStops = () => {
@@ -170,28 +661,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 () => {