@livedesk/client 0.1.239 → 0.1.241

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

@@ -1,860 +1,860 @@
-import { execFile } from 'node:child_process';
-
-const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
-const WINDOWS_SPAWN_CLOCK_TOLERANCE_MS = 250;
-
-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 unixMillisecondsForWindowsTicks(ticks) {
-    try {
-        return Number((BigInt(ticks) - 621_355_968_000_000_000n) / 10_000n);
-    } catch {
-        return 0;
-    }
-}
-
-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()
-            });
-        });
-    });
-}
-
-/**
- * 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 -Property ProcessId,ParentProcessId,CreationDate | 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 {
-        parsed = JSON.parse(result.stdout);
-    } catch (error) {
-        throw new Error(`Windows process-tree snapshot returned invalid JSON: ${error?.message || error}`);
-    }
-    return (Array.isArray(parsed) ? parsed : [parsed])
-        .map(normalizeWindowsProcessRecord)
-        .filter(Boolean);
-}
-
-/**
- * Captures only the named immutable identities. Normal Agent startup uses this
- * for the Agent root plus its launcher owner instead of enumerating every
- * process on the computer. Full-table discovery remains a terminal/recovery
- * operation where descendants actually need to be found.
- */
-export async function queryWindowsProcessIdentities(processIds, {
-    execFileImpl = execFile
-} = {}) {
-    const ids = [...new Set((Array.isArray(processIds) ? processIds : [processIds])
-        .map(value => Number(value || 0))
-        .filter(value => Number.isInteger(value) && value > 1))]
-        .slice(0, 8);
-    if (ids.length === 0) return [];
-    const filter = ids.map(pid => `ProcessId = ${pid}`).join(' OR ');
-    const script = [
-        '$ErrorActionPreference = "Stop";',
-        `@(Get-CimInstance Win32_Process -Filter "${filter}" -Property ProcessId,ParentProcessId,CreationDate | 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: 5000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 },
-        execFileImpl
-    );
-    if (!result.ok || !result.stdout) {
-        throw new Error(
-            `Windows process identity query failed: `
-            + `${result.stderr || result.error?.message || 'CIM query returned no process records'}`
-        );
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(result.stdout);
-    } catch (error) {
-        throw new Error(`Windows process identity query returned invalid JSON: ${error?.message || error}`);
-    }
-    return (Array.isArray(parsed) ? parsed : [parsed])
-        .map(normalizeWindowsProcessRecord)
-        .filter(Boolean);
-}
-
-/**
- * Rechecks CreationDate and force-stops the single PID inside the same
- * PowerShell process. PID reuse therefore becomes a harmless identity mismatch
- * instead of terminating the replacement process.
- */
-export async function terminateExactWindowsProcessTree(recordOrRecords, {
-    execFileImpl = execFile
-} = {}) {
-    const targets = (Array.isArray(recordOrRecords) ? recordOrRecords : [recordOrRecords])
-        .map(normalizeWindowsProcessRecord)
-        .filter(Boolean);
-    if (targets.length === 0) {
-        return { ok: false, error: new Error('At least one immutable Windows process record is required.') };
-    }
-    const targetsJson = JSON.stringify(targets.map(target => ({
-        pid: target.pid,
-        startOrder: target.startOrder
-    }))).replaceAll("'", "''");
-    const script = [
-        '$ErrorActionPreference = "Stop";',
-        `$targets = ConvertFrom-Json -InputObject '${targetsJson}';`,
-        '$failures = [System.Collections.Generic.List[string]]::new();',
-        'foreach ($item in $targets) {',
-        '  $targetPid = [int]$item.pid;',
-        '  $expectedStartTicks = [string]$item.startOrder;',
-        '  try {',
-        '    $target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -Property ProcessId,CreationDate -ErrorAction SilentlyContinue | Select-Object -First 1;',
-        '    if (-not $target) { continue };',
-        '    $targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" };',
-        '    if ($targetStartTicks -ne $expectedStartTicks) { continue };',
-        '    Stop-Process -Id $targetPid -Force -ErrorAction Stop;',
-        '  } catch {',
-        '    $failures.Add("pid=$targetPid $($_.Exception.Message)");',
-        '  }',
-        '}',
-        'if ($failures.Count -gt 0) { [Console]::Error.WriteLine(($failures -join "; ")); exit 1 };',
-        'exit 0;'
-    ].join(' ');
-    return runExecFile(
-        'powershell.exe',
-        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
-        { windowsHide: true, timeout: 15000, killSignal: 'SIGKILL' },
-        execFileImpl
-    );
-}
-
-/**
- * Tracks the exact Agent root and only descendants connected through Windows
- * ParentProcessId records. Startup queries only the Agent and launcher
- * identities. Full process-table snapshots are serialized and request-driven
- * by terminal cleanup/recovery; a healthy connected Client owns no recurring
- * PowerShell/CIM timer.
- */
-export function createWindowsProcessTreeTracker(child, {
-    platform = process.platform,
-    queryProcessTableImpl = queryWindowsProcessTable,
-    queryInitialProcessRecordsImpl = null,
-    spawnedAtMs = Date.now(),
-    ownerPid = process.pid,
-    initialRetryDelaysMs = [25, 75, 150],
-    waitImpl = waitMilliseconds,
-    publishTrackedRecords = null,
-    reportPublisherError = error => console.warn(
-        `[LiveDesk Client] Windows owned-process manifest warning: ${error?.message || error}`
-    )
-} = {}) {
-    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 rootExitedAtMs = null;
-    let rootCapturedBeforeExit = false;
-    let lastSnapshotHadRootPid = false;
-    let successfulSnapshotAfterExit = false;
-    let ambiguousRootReuse = false;
-    let lastPublisherError = null;
-
-    const mergeSnapshot = snapshot => {
-        const records = (Array.isArray(snapshot) ? snapshot : [])
-            .map(normalizeWindowsProcessRecord)
-            .filter(Boolean);
-        lastSnapshot = records;
-        const currentByPid = new Map(records.map(record => [record.pid, record]));
-        const currentRoot = currentByPid.get(rootPid) || null;
-        lastSnapshotHadRootPid = Boolean(currentRoot);
-        const rootWasReused = Boolean(
-            rootRecord && currentRoot && !sameWindowsProcess(currentRoot, rootRecord)
-        );
-        if (rootWasReused) {
-            ambiguousRootReuse = true;
-        }
-        if (rootRecord && rootExitedAtMs === null && (!currentRoot || rootWasReused)) {
-            // The exit event can trail the first CIM snapshot that proves the
-            // exact root is gone. Use that proof immediately so a surviving
-            // child first observed in this same snapshot is still owned.
-            // For PID reuse, cap the old lifetime just before the replacement
-            // CreationDate so replacement-root children remain excluded.
-            rootExitedAtMs = rootWasReused
-                ? unixMillisecondsForWindowsTicks(currentRoot.startOrder) - 1
-                : Date.now();
-        }
-        if (rootExitedAtMs !== null) successfulSnapshotAfterExit = 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);
-            }
-        }
-
-        // Windows retains ParentProcessId on surviving direct children after
-        // the root exits. A reused root PID is also safe to bridge only for a
-        // direct child whose immutable creation time is inside the original
-        // root lifetime; children created by the replacement root are rejected
-        // by windowsRecordIsWithinLifetime.
-        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 || rootWasReused)
-                    && 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 initialQuery = typeof queryInitialProcessRecordsImpl === 'function'
-        ? queryInitialProcessRecordsImpl
-        : queryProcessTableImpl === queryWindowsProcessTable
-            ? () => queryWindowsProcessIdentities([rootPid, ownerPid])
-            : queryProcessTableImpl;
-    const boundedInitialRetryDelays = (
-        Array.isArray(initialRetryDelaysMs) ? initialRetryDelaysMs : []
-    )
-        .slice(0, 5)
-        .map(value => Math.min(1000, Math.max(1, Number(value) || 1)));
-
-    const refresh = async ({ initial = false } = {}) => {
-        if (!enabled) return { ok: true, records: [] };
-        if (inFlight) return inFlight;
-        inFlight = Promise.resolve()
-            .then(() => (initial ? initialQuery() : queryProcessTableImpl()))
-            .then(async snapshot => {
-                mergeSnapshot(snapshot);
-                lastError = null;
-                if (typeof publishTrackedRecords === 'function') {
-                    try {
-                        await publishTrackedRecords(
-                            [...tracked.values()].map(record => ({ ...record })),
-                            {
-                                rootPid,
-                                rootRecord: rootRecord ? { ...rootRecord } : null,
-                                snapshot: lastSnapshot.map(record => ({ ...record })),
-                                terminal: stopped
-                            }
-                        );
-                        lastPublisherError = null;
-                    } catch (error) {
-                        // Manifest publication must never break the in-memory
-                        // cleanup proof. Keep tracking, surface diagnostics,
-                        // and retry on the next requested/terminal refresh.
-                        lastPublisherError = error;
-                        try { reportPublisherError(error); } catch { /* diagnostics cannot own lifecycle */ }
-                    }
-                }
-                return {
-                    ok: true,
-                    records: lastSnapshot,
-                    publisherError: lastPublisherError
-                };
-            })
-            .catch(error => {
-                lastError = error;
-                return { ok: false, error, records: lastSnapshot };
-            })
-            .finally(() => {
-                inFlight = null;
-            });
-        return inFlight;
-    };
-
-    const ready = enabled
-        ? (async () => {
-            let result = await refresh({ initial: true });
-            for (const retryDelayMs of boundedInitialRetryDelays) {
-                if (rootRecord || stopped) break;
-                // A just-spawned PID can briefly lag its CIM identity. Retry
-                // only the exact root/launcher filter; never compensate with
-                // a healthy-state full-table timer.
-                await waitImpl(retryDelayMs);
-                result = await refresh({ initial: true });
-            }
-            return result;
-        })()
-        : Promise.resolve({ ok: true, records: [] });
-
-    return {
-        enabled,
-        ready,
-        refresh,
-        stop() {
-            stopped = true;
-        },
-        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,
-        getLastPublisherError: () => lastPublisherError
-    };
-}
-
-/**
- * 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?.()) {
-                    return { ok: true, remaining: [] };
-                }
-                const ordered = [...remaining].sort((left, right) => (
-                    Number(right.depth || 0) - Number(left.depth || 0)
-                ));
-                // One PowerShell invocation receives the descendant-first
-                // immutable snapshot, then rechecks every PID CreationDate
-                // immediately before its own Stop-Process. No taskkill /T
-                // traversal can follow an unverified stale PPID edge.
-                const termination = await terminateExactTreeImpl(ordered, { includeTree: false });
-                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?.()) {
-            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);
-        return true;
-    } catch (error) {
-        return error?.code === 'EPERM';
-    }
-}
-
-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
-        && Number.isInteger(processId)
-        && processId > 1) {
-        try {
-            signalProcess(-processId, signal);
-            return;
-        } catch (error) {
-            if (error?.code !== 'ESRCH') throw error;
-        }
-    }
-    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),
-    drainWindowsTree = drainOwnedWindowsAgentTreeUntilStopped,
-    windowsTerminateAttemptLimit = 3,
-    windowsTerminateRetryMs = 100,
-    windowsRecoveryRetryMs = 1000,
-    unixTerminateRetryMs = 1000,
-    reportTerminationFailure = message => console.error(message),
-    exitProcess = code => hostProcess.exit(code)
-} = {}) {
-    if (typeof getAgentProcess !== 'function') {
-        throw new TypeError('getAgentProcess is required.');
-    }
-
-    let terminating = false;
-    const handlers = new Map();
-    for (const signal of ['SIGINT', 'SIGTERM']) {
-        const handler = () => {
-            if (terminating) return;
-            terminating = true;
-            const exitCode = SIGNAL_EXIT_CODES[signal] || 1;
-            const child = getAgentProcess();
-            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;
-            }
-
-            let finished = false;
-            let poll = null;
-            let timeout = null;
-            let unixRetryTimer = null;
-            let windowsRetryTimer = null;
-            const finish = () => {
-                if (finished) return;
-                finished = true;
-                if (poll) clearInterval(poll);
-                if (timeout) clearTimeout(timeout);
-                if (unixRetryTimer) clearTimeout(unixRetryTimer);
-                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
-                exitProcess(exitCode);
-            };
-            const processId = Number(child?.pid || 0);
-            if (platform === 'win32') {
-                if (!Number.isInteger(processId) || processId <= 1) {
-                    finish();
-                    return;
-                }
-                // 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;
-                    if (!child.livedeskTreeStopPromise) {
-                        child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
-                            platform,
-                            maxAttempts: windowsTerminateAttemptLimit,
-                            retryMs: windowsTerminateRetryMs,
-                            retryForeverMs: windowsRecoveryRetryMs,
-                            reportTerminationFailure
-                        }));
-                    }
-                    child.livedeskTreeStopPromise
-                        .catch(error => ({ ok: false, error }))
-                        .then(result => {
-                            if (result?.ok !== false) {
-                                finish();
-                                return;
-                            }
-                            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(
-                                drainUntilStopped,
-                                Math.max(100, Number(windowsRecoveryRetryMs) || 1000)
-                            );
-                        });
-                };
-                drainUntilStopped();
-                return;
-            }
-            const finishWhenTreeStops = () => {
-                const ownsUnixGroup = child?.livedeskOwnsProcessGroup === true
-                    && Number(child?.pid || 0) > 1;
-                const childAlive = child.exitCode === null && child.signalCode == null;
-                const groupAlive = ownsUnixGroup
-                    && isOwnedUnixProcessGroupAlive(child, platform, signalProcess);
-                // 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 (error) {
-                reportTerminationFailure(
-                    `[LiveDesk Client] Agent tree pid=${processId || 'unknown'} could not receive ${signal} `
-                    + `(${error?.message || error}). Forced cleanup will continue.`
-                );
-            }
-            poll = setInterval(finishWhenTreeStops, 50);
-            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 (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.`
-                        );
-                    }
-                }
-                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);
-        // 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);
-    }
-
-    const dispose = () => {
-        for (const [signal, handler] of handlers) {
-            hostProcess.removeListener(signal, handler);
-        }
-    };
-    // Windows process.kill(pid, 'SIGTERM') can terminate a process without
-    // dispatching its JavaScript SIGTERM listener. Replacement startup must
-    // enter this exact cleanup state machine directly instead of simulating an
-    // operating-system signal.
-    dispose.requestTermination = (signal = 'SIGTERM') => {
-        const normalizedSignal = signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM';
-        handlers.get(normalizedSignal)?.();
-    };
-    return dispose;
-}
+import { execFile } from 'node:child_process';
+
+const SIGNAL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143 });
+const WINDOWS_SPAWN_CLOCK_TOLERANCE_MS = 250;
+
+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 unixMillisecondsForWindowsTicks(ticks) {
+    try {
+        return Number((BigInt(ticks) - 621_355_968_000_000_000n) / 10_000n);
+    } catch {
+        return 0;
+    }
+}
+
+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()
+            });
+        });
+    });
+}
+
+/**
+ * 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 -Property ProcessId,ParentProcessId,CreationDate | 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 {
+        parsed = JSON.parse(result.stdout);
+    } catch (error) {
+        throw new Error(`Windows process-tree snapshot returned invalid JSON: ${error?.message || error}`);
+    }
+    return (Array.isArray(parsed) ? parsed : [parsed])
+        .map(normalizeWindowsProcessRecord)
+        .filter(Boolean);
+}
+
+/**
+ * Captures only the named immutable identities. Normal Agent startup uses this
+ * for the Agent root plus its launcher owner instead of enumerating every
+ * process on the computer. Full-table discovery remains a terminal/recovery
+ * operation where descendants actually need to be found.
+ */
+export async function queryWindowsProcessIdentities(processIds, {
+    execFileImpl = execFile
+} = {}) {
+    const ids = [...new Set((Array.isArray(processIds) ? processIds : [processIds])
+        .map(value => Number(value || 0))
+        .filter(value => Number.isInteger(value) && value > 1))]
+        .slice(0, 8);
+    if (ids.length === 0) return [];
+    const filter = ids.map(pid => `ProcessId = ${pid}`).join(' OR ');
+    const script = [
+        '$ErrorActionPreference = "Stop";',
+        `@(Get-CimInstance Win32_Process -Filter "${filter}" -Property ProcessId,ParentProcessId,CreationDate | 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: 5000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 },
+        execFileImpl
+    );
+    if (!result.ok || !result.stdout) {
+        throw new Error(
+            `Windows process identity query failed: `
+            + `${result.stderr || result.error?.message || 'CIM query returned no process records'}`
+        );
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    } catch (error) {
+        throw new Error(`Windows process identity query returned invalid JSON: ${error?.message || error}`);
+    }
+    return (Array.isArray(parsed) ? parsed : [parsed])
+        .map(normalizeWindowsProcessRecord)
+        .filter(Boolean);
+}
+
+/**
+ * Rechecks CreationDate and force-stops the single PID inside the same
+ * PowerShell process. PID reuse therefore becomes a harmless identity mismatch
+ * instead of terminating the replacement process.
+ */
+export async function terminateExactWindowsProcessTree(recordOrRecords, {
+    execFileImpl = execFile
+} = {}) {
+    const targets = (Array.isArray(recordOrRecords) ? recordOrRecords : [recordOrRecords])
+        .map(normalizeWindowsProcessRecord)
+        .filter(Boolean);
+    if (targets.length === 0) {
+        return { ok: false, error: new Error('At least one immutable Windows process record is required.') };
+    }
+    const targetsJson = JSON.stringify(targets.map(target => ({
+        pid: target.pid,
+        startOrder: target.startOrder
+    }))).replaceAll("'", "''");
+    const script = [
+        '$ErrorActionPreference = "Stop";',
+        `$targets = ConvertFrom-Json -InputObject '${targetsJson}';`,
+        '$failures = [System.Collections.Generic.List[string]]::new();',
+        'foreach ($item in $targets) {',
+        '  $targetPid = [int]$item.pid;',
+        '  $expectedStartTicks = [string]$item.startOrder;',
+        '  try {',
+        '    $target = Get-CimInstance Win32_Process -Filter "ProcessId = $targetPid" -Property ProcessId,CreationDate -ErrorAction SilentlyContinue | Select-Object -First 1;',
+        '    if (-not $target) { continue };',
+        '    $targetStartTicks = if ($target.CreationDate) { [string]$target.CreationDate.ToUniversalTime().Ticks } else { "" };',
+        '    if ($targetStartTicks -ne $expectedStartTicks) { continue };',
+        '    Stop-Process -Id $targetPid -Force -ErrorAction Stop;',
+        '  } catch {',
+        '    $failures.Add("pid=$targetPid $($_.Exception.Message)");',
+        '  }',
+        '}',
+        'if ($failures.Count -gt 0) { [Console]::Error.WriteLine(($failures -join "; ")); exit 1 };',
+        'exit 0;'
+    ].join(' ');
+    return runExecFile(
+        'powershell.exe',
+        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+        { windowsHide: true, timeout: 15000, killSignal: 'SIGKILL' },
+        execFileImpl
+    );
+}
+
+/**
+ * Tracks the exact Agent root and only descendants connected through Windows
+ * ParentProcessId records. Startup queries only the Agent and launcher
+ * identities. Full process-table snapshots are serialized and request-driven
+ * by terminal cleanup/recovery; a healthy connected Client owns no recurring
+ * PowerShell/CIM timer.
+ */
+export function createWindowsProcessTreeTracker(child, {
+    platform = process.platform,
+    queryProcessTableImpl = queryWindowsProcessTable,
+    queryInitialProcessRecordsImpl = null,
+    spawnedAtMs = Date.now(),
+    ownerPid = process.pid,
+    initialRetryDelaysMs = [25, 75, 150],
+    waitImpl = waitMilliseconds,
+    publishTrackedRecords = null,
+    reportPublisherError = error => console.warn(
+        `[LiveDesk Client] Windows owned-process manifest warning: ${error?.message || error}`
+    )
+} = {}) {
+    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 rootExitedAtMs = null;
+    let rootCapturedBeforeExit = false;
+    let lastSnapshotHadRootPid = false;
+    let successfulSnapshotAfterExit = false;
+    let ambiguousRootReuse = false;
+    let lastPublisherError = null;
+
+    const mergeSnapshot = snapshot => {
+        const records = (Array.isArray(snapshot) ? snapshot : [])
+            .map(normalizeWindowsProcessRecord)
+            .filter(Boolean);
+        lastSnapshot = records;
+        const currentByPid = new Map(records.map(record => [record.pid, record]));
+        const currentRoot = currentByPid.get(rootPid) || null;
+        lastSnapshotHadRootPid = Boolean(currentRoot);
+        const rootWasReused = Boolean(
+            rootRecord && currentRoot && !sameWindowsProcess(currentRoot, rootRecord)
+        );
+        if (rootWasReused) {
+            ambiguousRootReuse = true;
+        }
+        if (rootRecord && rootExitedAtMs === null && (!currentRoot || rootWasReused)) {
+            // The exit event can trail the first CIM snapshot that proves the
+            // exact root is gone. Use that proof immediately so a surviving
+            // child first observed in this same snapshot is still owned.
+            // For PID reuse, cap the old lifetime just before the replacement
+            // CreationDate so replacement-root children remain excluded.
+            rootExitedAtMs = rootWasReused
+                ? unixMillisecondsForWindowsTicks(currentRoot.startOrder) - 1
+                : Date.now();
+        }
+        if (rootExitedAtMs !== null) successfulSnapshotAfterExit = 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);
+            }
+        }
+
+        // Windows retains ParentProcessId on surviving direct children after
+        // the root exits. A reused root PID is also safe to bridge only for a
+        // direct child whose immutable creation time is inside the original
+        // root lifetime; children created by the replacement root are rejected
+        // by windowsRecordIsWithinLifetime.
+        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 || rootWasReused)
+                    && 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 initialQuery = typeof queryInitialProcessRecordsImpl === 'function'
+        ? queryInitialProcessRecordsImpl
+        : queryProcessTableImpl === queryWindowsProcessTable
+            ? () => queryWindowsProcessIdentities([rootPid, ownerPid])
+            : queryProcessTableImpl;
+    const boundedInitialRetryDelays = (
+        Array.isArray(initialRetryDelaysMs) ? initialRetryDelaysMs : []
+    )
+        .slice(0, 5)
+        .map(value => Math.min(1000, Math.max(1, Number(value) || 1)));
+
+    const refresh = async ({ initial = false } = {}) => {
+        if (!enabled) return { ok: true, records: [] };
+        if (inFlight) return inFlight;
+        inFlight = Promise.resolve()
+            .then(() => (initial ? initialQuery() : queryProcessTableImpl()))
+            .then(async snapshot => {
+                mergeSnapshot(snapshot);
+                lastError = null;
+                if (typeof publishTrackedRecords === 'function') {
+                    try {
+                        await publishTrackedRecords(
+                            [...tracked.values()].map(record => ({ ...record })),
+                            {
+                                rootPid,
+                                rootRecord: rootRecord ? { ...rootRecord } : null,
+                                snapshot: lastSnapshot.map(record => ({ ...record })),
+                                terminal: stopped
+                            }
+                        );
+                        lastPublisherError = null;
+                    } catch (error) {
+                        // Manifest publication must never break the in-memory
+                        // cleanup proof. Keep tracking, surface diagnostics,
+                        // and retry on the next requested/terminal refresh.
+                        lastPublisherError = error;
+                        try { reportPublisherError(error); } catch { /* diagnostics cannot own lifecycle */ }
+                    }
+                }
+                return {
+                    ok: true,
+                    records: lastSnapshot,
+                    publisherError: lastPublisherError
+                };
+            })
+            .catch(error => {
+                lastError = error;
+                return { ok: false, error, records: lastSnapshot };
+            })
+            .finally(() => {
+                inFlight = null;
+            });
+        return inFlight;
+    };
+
+    const ready = enabled
+        ? (async () => {
+            let result = await refresh({ initial: true });
+            for (const retryDelayMs of boundedInitialRetryDelays) {
+                if (rootRecord || stopped) break;
+                // A just-spawned PID can briefly lag its CIM identity. Retry
+                // only the exact root/launcher filter; never compensate with
+                // a healthy-state full-table timer.
+                await waitImpl(retryDelayMs);
+                result = await refresh({ initial: true });
+            }
+            return result;
+        })()
+        : Promise.resolve({ ok: true, records: [] });
+
+    return {
+        enabled,
+        ready,
+        refresh,
+        stop() {
+            stopped = true;
+        },
+        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,
+        getLastPublisherError: () => lastPublisherError
+    };
+}
+
+/**
+ * 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?.()) {
+                    return { ok: true, remaining: [] };
+                }
+                const ordered = [...remaining].sort((left, right) => (
+                    Number(right.depth || 0) - Number(left.depth || 0)
+                ));
+                // One PowerShell invocation receives the descendant-first
+                // immutable snapshot, then rechecks every PID CreationDate
+                // immediately before its own Stop-Process. No taskkill /T
+                // traversal can follow an unverified stale PPID edge.
+                const termination = await terminateExactTreeImpl(ordered, { includeTree: false });
+                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?.()) {
+            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);
+        return true;
+    } catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+
+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
+        && Number.isInteger(processId)
+        && processId > 1) {
+        try {
+            signalProcess(-processId, signal);
+            return;
+        } catch (error) {
+            if (error?.code !== 'ESRCH') throw error;
+        }
+    }
+    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),
+    drainWindowsTree = drainOwnedWindowsAgentTreeUntilStopped,
+    windowsTerminateAttemptLimit = 3,
+    windowsTerminateRetryMs = 100,
+    windowsRecoveryRetryMs = 1000,
+    unixTerminateRetryMs = 1000,
+    reportTerminationFailure = message => console.error(message),
+    exitProcess = code => hostProcess.exit(code)
+} = {}) {
+    if (typeof getAgentProcess !== 'function') {
+        throw new TypeError('getAgentProcess is required.');
+    }
+
+    let terminating = false;
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const handler = () => {
+            if (terminating) return;
+            terminating = true;
+            const exitCode = SIGNAL_EXIT_CODES[signal] || 1;
+            const child = getAgentProcess();
+            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;
+            }
+
+            let finished = false;
+            let poll = null;
+            let timeout = null;
+            let unixRetryTimer = null;
+            let windowsRetryTimer = null;
+            const finish = () => {
+                if (finished) return;
+                finished = true;
+                if (poll) clearInterval(poll);
+                if (timeout) clearTimeout(timeout);
+                if (unixRetryTimer) clearTimeout(unixRetryTimer);
+                if (windowsRetryTimer) clearTimeout(windowsRetryTimer);
+                exitProcess(exitCode);
+            };
+            const processId = Number(child?.pid || 0);
+            if (platform === 'win32') {
+                if (!Number.isInteger(processId) || processId <= 1) {
+                    finish();
+                    return;
+                }
+                // 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;
+                    if (!child.livedeskTreeStopPromise) {
+                        child.livedeskTreeStopPromise = Promise.resolve().then(() => drainWindowsTree(child, {
+                            platform,
+                            maxAttempts: windowsTerminateAttemptLimit,
+                            retryMs: windowsTerminateRetryMs,
+                            retryForeverMs: windowsRecoveryRetryMs,
+                            reportTerminationFailure
+                        }));
+                    }
+                    child.livedeskTreeStopPromise
+                        .catch(error => ({ ok: false, error }))
+                        .then(result => {
+                            if (result?.ok !== false) {
+                                finish();
+                                return;
+                            }
+                            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(
+                                drainUntilStopped,
+                                Math.max(100, Number(windowsRecoveryRetryMs) || 1000)
+                            );
+                        });
+                };
+                drainUntilStopped();
+                return;
+            }
+            const finishWhenTreeStops = () => {
+                const ownsUnixGroup = child?.livedeskOwnsProcessGroup === true
+                    && Number(child?.pid || 0) > 1;
+                const childAlive = child.exitCode === null && child.signalCode == null;
+                const groupAlive = ownsUnixGroup
+                    && isOwnedUnixProcessGroupAlive(child, platform, signalProcess);
+                // 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 (error) {
+                reportTerminationFailure(
+                    `[LiveDesk Client] Agent tree pid=${processId || 'unknown'} could not receive ${signal} `
+                    + `(${error?.message || error}). Forced cleanup will continue.`
+                );
+            }
+            poll = setInterval(finishWhenTreeStops, 50);
+            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 (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.`
+                        );
+                    }
+                }
+                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);
+        // 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);
+    }
+
+    const dispose = () => {
+        for (const [signal, handler] of handlers) {
+            hostProcess.removeListener(signal, handler);
+        }
+    };
+    // Windows process.kill(pid, 'SIGTERM') can terminate a process without
+    // dispatching its JavaScript SIGTERM listener. Replacement startup must
+    // enter this exact cleanup state machine directly instead of simulating an
+    // operating-system signal.
+    dispose.requestTermination = (signal = 'SIGTERM') => {
+        const normalizedSignal = signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM';
+        handlers.get(normalizedSignal)?.();
+    };
+    return dispose;
+}