pi-background-tasks 2.5.0 → 2.6.0

package/dist/src/core/windows-taskkill.js

@@ -0,0 +1,185 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { win32 } from 'node:path';
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_CAPTURE_BYTES = 8 * 1024;
+class BoundedCapture {
+    maxBytes;
+    chunks = [];
+    capturedBytes = 0;
+    truncated = false;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    append(data) {
+        const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+        if (buffer.length === 0)
+            return;
+        const remaining = this.maxBytes - this.capturedBytes;
+        if (remaining > 0) {
+            const kept = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);
+            this.chunks.push(kept);
+            this.capturedBytes += kept.length;
+        }
+        if (buffer.length > Math.max(0, remaining))
+            this.truncated = true;
+    }
+    text() {
+        return Buffer.concat(this.chunks, this.capturedBytes).toString('utf8');
+    }
+    isTruncated() {
+        return this.truncated;
+    }
+}
+function lookupEnv(env, name) {
+    const direct = env[name];
+    if (direct !== undefined)
+        return direct;
+    const lowerName = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === lowerName)
+            return env[key];
+    }
+    return undefined;
+}
+function validateWindowsRoot(raw, label) {
+    const value = raw.trim();
+    if (value.length === 0)
+        throw new Error(`${label} is empty; cannot resolve taskkill.exe`);
+    if (value.includes('\0'))
+        throw new Error(`${label} contains a NUL byte; cannot resolve taskkill.exe`);
+    if (!win32.isAbsolute(value)) {
+        throw new Error(`${label} must be an absolute Windows path; cannot resolve taskkill.exe`);
+    }
+    return value;
+}
+export function resolveTaskkillPath(env = process.env) {
+    const systemRoot = lookupEnv(env, 'SystemRoot');
+    if (systemRoot !== undefined) {
+        return win32.join(validateWindowsRoot(systemRoot, 'SystemRoot'), 'System32', 'taskkill.exe');
+    }
+    const windir = lookupEnv(env, 'WINDIR');
+    if (windir !== undefined) {
+        return win32.join(validateWindowsRoot(windir, 'WINDIR'), 'System32', 'taskkill.exe');
+    }
+    throw new Error('Cannot resolve taskkill.exe: SystemRoot is missing and WINDIR fallback is missing');
+}
+function validatePid(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        throw new Error(`Invalid Windows taskkill pid ${String(pid)}; expected a positive safe integer`);
+    }
+}
+function validatePhase(phase) {
+    if (phase !== 'terminate' && phase !== 'force') {
+        throw new Error(`Invalid Windows taskkill phase ${String(phase)}`);
+    }
+}
+function positiveFiniteInteger(value, fallback, label) {
+    const candidate = value ?? fallback;
+    if (!Number.isFinite(candidate) || candidate <= 0) {
+        throw new Error(`${label} must be a positive finite number`);
+    }
+    return Math.max(1, Math.floor(candidate));
+}
+function outcome(exitCode, signal, stdout, stderr) {
+    return {
+        exitCode,
+        signal,
+        stdout: stdout.text(),
+        stderr: stderr.text(),
+        stdoutTruncated: stdout.isTruncated(),
+        stderrTruncated: stderr.isTruncated(),
+    };
+}
+function defaultSpawn(command, args, options) {
+    return nodeSpawn(command, args, options);
+}
+export function runWindowsTaskkill(pid, phase, options = {}) {
+    validatePid(pid);
+    validatePhase(phase);
+    const env = options.env ?? process.env;
+    const taskkill = resolveTaskkillPath(env);
+    const timeoutMs = positiveFiniteInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');
+    const maxCaptureBytes = positiveFiniteInteger(options.maxCaptureBytes, DEFAULT_MAX_CAPTURE_BYTES, 'maxCaptureBytes');
+    const spawn = options.spawn ?? defaultSpawn;
+    const abortSignal = options.signal;
+    const args = ['/PID', String(pid), '/T'];
+    if (phase === 'force')
+        args.push('/F');
+    if (abortSignal?.aborted) {
+        const stdout = new BoundedCapture(maxCaptureBytes);
+        const stderr = new BoundedCapture(maxCaptureBytes);
+        stderr.append('Windows taskkill was aborted before launch');
+        return Promise.resolve(outcome(null, null, stdout, stderr));
+    }
+    return new Promise((resolve) => {
+        const stdout = new BoundedCapture(maxCaptureBytes);
+        const stderr = new BoundedCapture(maxCaptureBytes);
+        let settled = false;
+        let timeout;
+        let child;
+        let abortListener;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (abortSignal !== undefined && abortListener !== undefined) {
+                abortSignal.removeEventListener('abort', abortListener);
+            }
+            resolve(result);
+        };
+        const stopHelper = (reason) => {
+            stderr.append(reason);
+            if (child !== undefined) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch (error) {
+                    stderr.append(`; helper kill failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            settle(outcome(null, null, stdout, stderr));
+        };
+        const spawnOptions = {
+            env,
+            shell: false,
+            windowsVerbatimArguments: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        try {
+            child = spawn(taskkill, args, spawnOptions);
+        }
+        catch (error) {
+            stderr.append(`Windows taskkill spawn failed: ${error instanceof Error ? error.message : String(error)}`);
+            settle(outcome(null, null, stdout, stderr));
+            return;
+        }
+        child.stdout?.on('data', (data) => {
+            stdout.append(data);
+        });
+        child.stderr?.on('data', (data) => {
+            stderr.append(data);
+        });
+        child.on('error', (error) => {
+            stderr.append(`Windows taskkill spawn error: ${error.message}`);
+            settle(outcome(null, null, stdout, stderr));
+        });
+        child.on('close', (code, signal) => {
+            settle(outcome(code, signal, stdout, stderr));
+        });
+        abortListener = () => {
+            stopHelper('Windows taskkill was aborted');
+        };
+        abortSignal?.addEventListener('abort', abortListener, { once: true });
+        // This timeout is the settlement guarantee for a taskkill helper that never
+        // exits. It must keep the event loop alive: an unref'd timer lets the loop
+        // drain first and leaves this promise pending forever. `settle()` always
+        // clears it, so keeping it referenced cannot leak.
+        timeout = setTimeout(() => {
+            stopHelper(`Windows taskkill timed out after ${String(timeoutMs)}ms`);
+        }, timeoutMs);
+    });
+}
+//# sourceMappingURL=windows-taskkill.js.map

package/dist/src/core/windows-taskkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-taskkill.js","sourceRoot":"","sources":["../../../src/core/windows-taskkill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAqB,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AA0ClC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAChC,MAAM,yBAAyB,GAAG,CAAC,GAAG,IAAI,CAAC;AAE3C,MAAM,cAAc;IAKW;IAJZ,MAAM,GAAa,EAAE,CAAC;IAC/B,aAAa,GAAG,CAAC,CAAC;IAClB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAEjD,MAAM,CAAC,IAAqB;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC;QACrD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;YACjF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC;QACpC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACpE,CAAC;IAED,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzE,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAsB,EAAE,IAAY;IACrD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,mBAAmB,CAAC,GAAW,EAAE,KAAa;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,wCAAwC,CAAC,CAAC;IAC1F,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,mDAAmD,CAAC,CAAC;IACvG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gEAAgE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAChD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;IAC/F,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,mFAAmF,CAAC,CAAC;AACvG,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IACnG,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAuB;IAC5C,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAyB,EAAE,QAAgB,EAAE,KAAa;IACvF,MAAM,SAAS,GAAG,KAAK,IAAI,QAAQ,CAAC;IACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,mCAAmC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,OAAO,CACd,QAAuB,EACvB,MAA6B,EAC7B,MAAsB,EACtB,MAAsB;IAEtB,OAAO;QACL,QAAQ;QACR,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;QACrB,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE;QACrC,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,OAAe,EAAE,IAAc,EAAE,OAAqB;IAC1E,OAAO,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,KAAuB,EACvB,UAAkC,EAAE;IAEpC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjB,aAAa,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,qBAAqB,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAC5F,MAAM,eAAe,GAAG,qBAAqB,CAC3C,OAAO,CAAC,eAAe,EACvB,yBAAyB,EACzB,iBAAiB,CAClB,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,WAAW,EAAE,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,4CAA4C,CAAC,CAAC;QAC5D,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,EAAE;QAC9C,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;QACnD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,OAAmC,CAAC;QACxC,IAAI,KAA8C,CAAC;QACnD,IAAI,aAAuC,CAAC;QAE5C,MAAM,MAAM,GAAG,CAAC,MAAuB,EAAQ,EAAE;YAC/C,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,OAAO,KAAK,SAAS;gBAAE,YAAY,CAAC,OAAO,CAAC,CAAC;YACjD,IAAI,WAAW,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;gBAC7D,WAAW,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,MAAM,UAAU,GAAG,CAAC,MAAc,EAAQ,EAAE;YAC1C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACxB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,MAAM,CAAC,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACnG,CAAC;YACH,CAAC;YACD,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC,CAAC;QAEF,MAAM,YAAY,GAAiB;YACjC,GAAG;YACH,KAAK,EAAE,KAAK;YACZ,wBAAwB,EAAE,KAAK;YAC/B,WAAW,EAAE,IAAI;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC;QAEF,IAAI,CAAC;YACH,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,kCAAkC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC1G,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,MAAM,CAAC,MAAM,CAAC,iCAAiC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAChE,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YACjC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QAEH,aAAa,GAAG,GAAG,EAAE;YACnB,UAAU,CAAC,8BAA8B,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,WAAW,EAAE,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAEtE,4EAA4E;QAC5E,2EAA2E;QAC3E,yEAAyE;QACzE,mDAAmD;QACnD,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YACxB,UAAU,CAAC,oCAAoC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxE,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { spawn as nodeSpawn, type SpawnOptions } from 'node:child_process';\nimport { win32 } from 'node:path';\n\nexport type WindowsKillPhase = 'terminate' | 'force';\n\nexport interface TaskkillOutcome {\n  readonly exitCode: number | null;\n  readonly signal: NodeJS.Signals | null;\n  readonly stdout: string;\n  readonly stderr: string;\n  readonly stdoutTruncated: boolean;\n  readonly stderrTruncated: boolean;\n}\n\ninterface TaskkillOutputStream {\n  on(event: 'data', listener: (data: Buffer | string) => void): unknown;\n}\n\ninterface WindowsTaskkillChildProcess {\n  readonly stdout?: TaskkillOutputStream | null | undefined;\n  readonly stderr?: TaskkillOutputStream | null | undefined;\n  kill(signal?: NodeJS.Signals): boolean;\n  on(event: 'error', listener: (error: Error) => void): unknown;\n  on(\n    event: 'close',\n    listener: (code: number | null, signal: NodeJS.Signals | null) => void,\n  ): unknown;\n}\n\ntype WindowsTaskkillSpawn = (\n  command: string,\n  args: string[],\n  options: SpawnOptions,\n) => WindowsTaskkillChildProcess;\n\nexport interface WindowsTaskkillOptions {\n  readonly spawn?: WindowsTaskkillSpawn;\n  readonly env?: NodeJS.ProcessEnv;\n  readonly timeoutMs?: number;\n  readonly signal?: AbortSignal;\n  readonly maxCaptureBytes?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 5000;\nconst DEFAULT_MAX_CAPTURE_BYTES = 8 * 1024;\n\nclass BoundedCapture {\n  private readonly chunks: Buffer[] = [];\n  private capturedBytes = 0;\n  private truncated = false;\n\n  constructor(private readonly maxBytes: number) {}\n\n  append(data: Buffer | string): void {\n    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');\n    if (buffer.length === 0) return;\n    const remaining = this.maxBytes - this.capturedBytes;\n    if (remaining > 0) {\n      const kept = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);\n      this.chunks.push(kept);\n      this.capturedBytes += kept.length;\n    }\n    if (buffer.length > Math.max(0, remaining)) this.truncated = true;\n  }\n\n  text(): string {\n    return Buffer.concat(this.chunks, this.capturedBytes).toString('utf8');\n  }\n\n  isTruncated(): boolean {\n    return this.truncated;\n  }\n}\n\nfunction lookupEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {\n  const direct = env[name];\n  if (direct !== undefined) return direct;\n  const lowerName = name.toLowerCase();\n  for (const key of Object.keys(env)) {\n    if (key.toLowerCase() === lowerName) return env[key];\n  }\n  return undefined;\n}\n\nfunction validateWindowsRoot(raw: string, label: string): string {\n  const value = raw.trim();\n  if (value.length === 0) throw new Error(`${label} is empty; cannot resolve taskkill.exe`);\n  if (value.includes('\\0')) throw new Error(`${label} contains a NUL byte; cannot resolve taskkill.exe`);\n  if (!win32.isAbsolute(value)) {\n    throw new Error(`${label} must be an absolute Windows path; cannot resolve taskkill.exe`);\n  }\n  return value;\n}\n\nexport function resolveTaskkillPath(env: NodeJS.ProcessEnv = process.env): string {\n  const systemRoot = lookupEnv(env, 'SystemRoot');\n  if (systemRoot !== undefined) {\n    return win32.join(validateWindowsRoot(systemRoot, 'SystemRoot'), 'System32', 'taskkill.exe');\n  }\n\n  const windir = lookupEnv(env, 'WINDIR');\n  if (windir !== undefined) {\n    return win32.join(validateWindowsRoot(windir, 'WINDIR'), 'System32', 'taskkill.exe');\n  }\n\n  throw new Error('Cannot resolve taskkill.exe: SystemRoot is missing and WINDIR fallback is missing');\n}\n\nfunction validatePid(pid: number): void {\n  if (!Number.isSafeInteger(pid) || pid <= 0) {\n    throw new Error(`Invalid Windows taskkill pid ${String(pid)}; expected a positive safe integer`);\n  }\n}\n\nfunction validatePhase(phase: WindowsKillPhase): void {\n  if (phase !== 'terminate' && phase !== 'force') {\n    throw new Error(`Invalid Windows taskkill phase ${String(phase)}`);\n  }\n}\n\nfunction positiveFiniteInteger(value: number | undefined, fallback: number, label: string): number {\n  const candidate = value ?? fallback;\n  if (!Number.isFinite(candidate) || candidate <= 0) {\n    throw new Error(`${label} must be a positive finite number`);\n  }\n  return Math.max(1, Math.floor(candidate));\n}\n\nfunction outcome(\n  exitCode: number | null,\n  signal: NodeJS.Signals | null,\n  stdout: BoundedCapture,\n  stderr: BoundedCapture,\n): TaskkillOutcome {\n  return {\n    exitCode,\n    signal,\n    stdout: stdout.text(),\n    stderr: stderr.text(),\n    stdoutTruncated: stdout.isTruncated(),\n    stderrTruncated: stderr.isTruncated(),\n  };\n}\n\nfunction defaultSpawn(command: string, args: string[], options: SpawnOptions): WindowsTaskkillChildProcess {\n  return nodeSpawn(command, args, options);\n}\n\nexport function runWindowsTaskkill(\n  pid: number,\n  phase: WindowsKillPhase,\n  options: WindowsTaskkillOptions = {},\n): Promise<TaskkillOutcome> {\n  validatePid(pid);\n  validatePhase(phase);\n  const env = options.env ?? process.env;\n  const taskkill = resolveTaskkillPath(env);\n  const timeoutMs = positiveFiniteInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');\n  const maxCaptureBytes = positiveFiniteInteger(\n    options.maxCaptureBytes,\n    DEFAULT_MAX_CAPTURE_BYTES,\n    'maxCaptureBytes',\n  );\n  const spawn = options.spawn ?? defaultSpawn;\n  const abortSignal = options.signal;\n\n  const args = ['/PID', String(pid), '/T'];\n  if (phase === 'force') args.push('/F');\n\n  if (abortSignal?.aborted) {\n    const stdout = new BoundedCapture(maxCaptureBytes);\n    const stderr = new BoundedCapture(maxCaptureBytes);\n    stderr.append('Windows taskkill was aborted before launch');\n    return Promise.resolve(outcome(null, null, stdout, stderr));\n  }\n\n  return new Promise<TaskkillOutcome>((resolve) => {\n    const stdout = new BoundedCapture(maxCaptureBytes);\n    const stderr = new BoundedCapture(maxCaptureBytes);\n    let settled = false;\n    let timeout: NodeJS.Timeout | undefined;\n    let child: WindowsTaskkillChildProcess | undefined;\n    let abortListener: (() => void) | undefined;\n\n    const settle = (result: TaskkillOutcome): void => {\n      if (settled) return;\n      settled = true;\n      if (timeout !== undefined) clearTimeout(timeout);\n      if (abortSignal !== undefined && abortListener !== undefined) {\n        abortSignal.removeEventListener('abort', abortListener);\n      }\n      resolve(result);\n    };\n\n    const stopHelper = (reason: string): void => {\n      stderr.append(reason);\n      if (child !== undefined) {\n        try {\n          child.kill('SIGKILL');\n        } catch (error) {\n          stderr.append(`; helper kill failed: ${error instanceof Error ? error.message : String(error)}`);\n        }\n      }\n      settle(outcome(null, null, stdout, stderr));\n    };\n\n    const spawnOptions: SpawnOptions = {\n      env,\n      shell: false,\n      windowsVerbatimArguments: false,\n      windowsHide: true,\n      stdio: ['ignore', 'pipe', 'pipe'],\n    };\n\n    try {\n      child = spawn(taskkill, args, spawnOptions);\n    } catch (error) {\n      stderr.append(`Windows taskkill spawn failed: ${error instanceof Error ? error.message : String(error)}`);\n      settle(outcome(null, null, stdout, stderr));\n      return;\n    }\n\n    child.stdout?.on('data', (data) => {\n      stdout.append(data);\n    });\n    child.stderr?.on('data', (data) => {\n      stderr.append(data);\n    });\n    child.on('error', (error) => {\n      stderr.append(`Windows taskkill spawn error: ${error.message}`);\n      settle(outcome(null, null, stdout, stderr));\n    });\n    child.on('close', (code, signal) => {\n      settle(outcome(code, signal, stdout, stderr));\n    });\n\n    abortListener = () => {\n      stopHelper('Windows taskkill was aborted');\n    };\n    abortSignal?.addEventListener('abort', abortListener, { once: true });\n\n    // This timeout is the settlement guarantee for a taskkill helper that never\n    // exits. It must keep the event loop alive: an unref'd timer lets the loop\n    // drain first and leaves this promise pending forever. `settle()` always\n    // clears it, so keeping it referenced cannot leak.\n    timeout = setTimeout(() => {\n      stopHelper(`Windows taskkill timed out after ${String(timeoutMs)}ms`);\n    }, timeoutMs);\n  });\n}\n"]}