@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/subprocess-local/lib/index.js

@@ -8,8 +8,256 @@ import { randomBytes } from "node:crypto";
 import { constants as constants$1, tmpdir } from "node:os";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { MAX_TIMER_DELAY_MS } from "../../timeout/lib/index.js";
+import koffi from "koffi";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { PassThrough } from "node:stream";
+//#region lib/types/windows-inspector.js
+/**
+* Windows process-table operations for terminal readiness, signalling, and
+* teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
+* identity and process-handle wait-state liveness, the shell pid as a pseudo
+* process group (Windows has no POSIX groups), and taskkill tree signalling.
+* The koffi bindings load lazily so
+* non-Windows processes never touch Win32 libraries; all decision logic takes
+* an injectable internals boundary so suites can pin it on any host.
+* @module nomix-subprocess-local/windows-inspector
+*/
+/**
+* Walk a process table from one root in children-first order, retaining only
+* members whose start identity is readable (unreadable members are detector
+* misses, exactly like an unreadable `/proc` entry on Linux).
+* @param entries - the process table snapshot.
+* @param rootPid - the tree root to descend from.
+* @param started - creation-time identity resolver for one member.
+* @returns the root and its current transitive descendants, children first.
+*/
+function windowsProcessTree(entries, rootPid, started) {
+	const root = new Map(entries.map((entry) => [entry.pid, entry])).get(rootPid);
+	if (root === void 0) return [];
+	const byParent = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const children = byParent.get(entry.parentPid) ?? [];
+		children.push(entry);
+		byParent.set(entry.parentPid, children);
+	}
+	const visited = /* @__PURE__ */ new Set();
+	const result = [];
+	const visit = (entry) => {
+		if (visited.has(entry.pid)) return;
+		visited.add(entry.pid);
+		for (const child of byParent.get(entry.pid) ?? []) visit(child);
+		const identity = started(entry.pid);
+		if (identity !== void 0) result.push({
+			pid: entry.pid,
+			started: identity
+		});
+	};
+	visit(root);
+	return result;
+}
+/**
+* Windows {@link ProcessInspector}. The shell pid stands in for a foreground
+* process group: it is a stable pseudo-group that lets the prompt-marker
+* readiness path compare foreground identities, while every actual signal
+* targets the console-wide tree through taskkill (SIGINT is delivered by the
+* terminal handle as a `\x03` input write and never reaches this layer).
+*/
+var WindowsProcessInspector = class {
+	internals;
+	constructor(internals = defaultWindowsProcessInternals()) {
+		this.internals = internals;
+	}
+	foregroundPgid(shellPid) {
+		return shellPid;
+	}
+	isStdinWaiting(_pgid) {
+		return false;
+	}
+	processTree(rootPid) {
+		return windowsProcessTree(this.internals.snapshot(), rootPid, (pid) => this.internals.processState(pid)?.started);
+	}
+	processSession(_sessionId) {
+		return [];
+	}
+	isAlive(identity) {
+		const state = this.internals.processState(identity.pid);
+		return state?.active === true && state.started === identity.started;
+	}
+	signalGroup(pgid, signal) {
+		this.internals.taskkill(pgid, signal === "SIGKILL");
+	}
+	signalProcess(identity, signal) {
+		if (this.isAlive(identity)) this.internals.taskkill(identity.pid, signal === "SIGKILL");
+	}
+};
+/**
+* Create the Windows process inspector.
+* @param internals - injectable process operations; defaults to the koffi-backed table.
+* @returns the Windows inspector.
+*/
+function createWindowsProcessInspector(internals = defaultWindowsProcessInternals()) {
+	return new WindowsProcessInspector(internals);
+}
+/** Terminate one Windows process tree with taskkill, contained like POSIX group signalling. */
+function taskkillTree(pid, force) {
+	if (pid <= 0) return;
+	spawnSync("taskkill", [
+		"/PID",
+		String(pid),
+		"/T",
+		...force ? ["/F"] : []
+	], { stdio: "ignore" });
+}
+/**
+* True for NULL and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
+* @param value - a handle as koffi may hand it back (pointer, null, or 0n).
+* @returns whether the value signals an invalid handle.
+*/
+function isInvalidHandle(value) {
+	if (value === null || value === void 0) return true;
+	const asBigInt = value;
+	return asBigInt === 0n || asBigInt === 18446744073709551615n || asBigInt === -1n;
+}
+const PVOID = koffi.pointer("void");
+/**
+* Resolve the koffi Win32 struct types once. Registration is lazy and cached
+* because koffi's type registry is global per process: test runners that
+* re-evaluate this module (a hoisted `vi.mock` re-imports the graph) must not
+* re-register the names.
+*/
+function win32Structs() {
+	if (cachedStructs !== void 0) return cachedStructs;
+	const PROCESSENTRY32W = koffi.struct("PROCESSENTRY32W", {
+		dwSize: "uint32",
+		cntUsage: "uint32",
+		th32ProcessID: "uint32",
+		th32DefaultHeapID: PVOID,
+		th32ModuleID: "uint32",
+		cCntThreads: "uint32",
+		th32ParentProcessID: "uint32",
+		pcPriClassBase: "int32",
+		dwFlags: "uint32",
+		szExeFile: koffi.array("char16", 260)
+	});
+	const FILETIME = koffi.struct("FILETIME", {
+		dwLowDateTime: "uint32",
+		dwHighDateTime: "uint32"
+	});
+	/* v8 ignore start -- a layout-mismatch guard fires only on ABI breakage; the windows-native suites exercise the real struct. */
+	if (PROCESSENTRY32W.size !== 568) throw new Error(`PROCESSENTRY32W layout mismatch: koffi computed ${PROCESSENTRY32W.size}, Windows headers say 568`);
+	/* v8 ignore stop */
+	cachedStructs = {
+		PROCESSENTRY32W,
+		FILETIME
+	};
+	return cachedStructs;
+}
+let cachedStructs;
+const TH32CS_SNAPPROCESS = 2;
+const WAIT_OBJECT_0 = 0;
+const WAIT_TIMEOUT = 258;
+let cachedBindings;
+/**
+* Resolve the lazy Win32 bindings (throws the first binding failure, fail-closed).
+* @returns the cached binding table.
+*/
+function win32Bindings() {
+	if (cachedBindings !== void 0) return cachedBindings;
+	const { PROCESSENTRY32W, FILETIME } = win32Structs();
+	const kernel32 = koffi.load("kernel32.dll");
+	const bind = (name, result, args) => kernel32.func("__stdcall", name, result, args);
+	cachedBindings = {
+		createToolhelp32Snapshot: bind("CreateToolhelp32Snapshot", PVOID, ["uint32", "uint32"]),
+		process32FirstW: bind("Process32FirstW", "int", [PVOID, koffi.pointer(PROCESSENTRY32W)]),
+		process32NextW: bind("Process32NextW", "int", [PVOID, koffi.pointer(PROCESSENTRY32W)]),
+		openProcess: bind("OpenProcess", PVOID, [
+			"uint32",
+			"int",
+			"uint32"
+		]),
+		getProcessTimes: bind("GetProcessTimes", "int", [
+			PVOID,
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME),
+			koffi.pointer(FILETIME)
+		]),
+		waitForSingleObject: bind("WaitForSingleObject", "uint32", [PVOID, "uint32"]),
+		closeHandle: bind("CloseHandle", "int", [PVOID])
+	};
+	return cachedBindings;
+}
+/**
+* Allocate koffi memory as a branded {@link NativePtr}; koffi's TS types are
+* `any`, so the cast goes through `unknown` to keep the unsafe surface here.
+* @param type - the koffi type to allocate.
+* @param count - element count.
+* @returns the branded allocation pointer.
+*/
+function allocNative(type, count) {
+	return koffi.alloc(type, count);
+}
+/** Enumerate the current process table through Toolhelp32. */
+function snapshotWindowsProcesses(bindings) {
+	const { PROCESSENTRY32W } = win32Structs();
+	const snapshot = bindings.createToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
+	/* v8 ignore next -- an invalid snapshot for the process flag is not producible through the public API;
+	the guard mirrors POSIX's unreadable-proc tolerance and isInvalidHandle is unit-tested. */
+	if (isInvalidHandle(snapshot)) return [];
+	const entries = [];
+	try {
+		const entry = allocNative(PROCESSENTRY32W, 1);
+		koffi.encode(entry, "uint32", PROCESSENTRY32W.size);
+		let ok = bindings.process32FirstW(snapshot, entry);
+		while (ok !== 0) {
+			const record = koffi.decode(entry, PROCESSENTRY32W);
+			entries.push({
+				pid: record.th32ProcessID,
+				parentPid: record.th32ParentProcessID
+			});
+			ok = bindings.process32NextW(snapshot, entry);
+		}
+	} finally {
+		bindings.closeHandle(snapshot);
+	}
+	return entries;
+}
+/** Read one process's creation identity and current wait state. */
+function windowsProcessState(bindings, pid) {
+	const { FILETIME } = win32Structs();
+	const handle = bindings.openProcess(1052672, 0, pid);
+	if (isInvalidHandle(handle)) return void 0;
+	try {
+		const creation = allocNative(FILETIME, 1);
+		const exit = allocNative(FILETIME, 1);
+		const kernel = allocNative(FILETIME, 1);
+		const user = allocNative(FILETIME, 1);
+		/* v8 ignore next -- a GetProcessTimes failure after a successful open races process exit and
+		cannot be staged deterministically; the absent-process path is covered and the caller
+		treats undefined as a detector miss. */
+		if (bindings.getProcessTimes(handle, creation, exit, kernel, user) === 0) return void 0;
+		const record = koffi.decode(creation, FILETIME);
+		const wait = bindings.waitForSingleObject(handle, 0);
+		/* v8 ignore next -- an opened process handle has exactly one of these two
+		zero-time wait states; an unexpected Win32 failure is an unreadable process. */
+		if (wait !== WAIT_OBJECT_0 && wait !== WAIT_TIMEOUT) return void 0;
+		return {
+			started: `${record.dwHighDateTime}:${record.dwLowDateTime}`,
+			active: wait === WAIT_TIMEOUT
+		};
+	} finally {
+		bindings.closeHandle(handle);
+	}
+}
+/** The koffi-backed default internals; bindings resolve lazily on first use. */
+function defaultWindowsProcessInternals() {
+	return {
+		snapshot: () => snapshotWindowsProcesses(win32Bindings()),
+		processState: (pid) => windowsProcessState(win32Bindings(), pid),
+		taskkill: taskkillTree
+	};
+}
+//#endregion
 //#region lib/types/process-inspector.js
 /** Platform process-table inspection for terminal readiness, signals, and teardown. */
 /* v8 ignore start -- thin OS bindings; injected logic is unit-tested and real platform composition exercises them. */
@@ -295,6 +543,7 @@ var MacProcessInspector = class extends PosixProcessInspector {
 function createProcessInspector(platform = process.platform, arch = process.arch, internals = DEFAULT_INTERNALS) {
 	if (platform === "linux") return new LinuxProcessInspector(arch, internals);
 	if (platform === "darwin") return new MacProcessInspector(internals);
+	if (platform === "win32") return createWindowsProcessInspector();
 	throw new Error(`subprocess-local: terminal inspection is unsupported on platform ${platform}`);
 }
 //#endregion
@@ -724,6 +973,7 @@ var LocalTerminalHandle = class {
 	terminal;
 	inspector;
 	graceMs;
+	platform;
 	pid;
 	output = new PassThrough();
 	done;
@@ -739,11 +989,13 @@ var LocalTerminalHandle = class {
 	* @param terminal - allocated node-pty process.
 	* @param inspector - platform process/session operations.
 	* @param graceMs - TERM-to-KILL and exit-wait grace.
+	* @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
 	*/
-	constructor(terminal, inspector, graceMs) {
+	constructor(terminal, inspector, graceMs, platform = process.platform) {
 		this.terminal = terminal;
 		this.inspector = inspector;
 		this.graceMs = graceMs;
+		this.platform = platform;
 		this.pid = terminal.pid;
 		this.rootIdentity = inspector.processTree(this.pid).find((member) => member.pid === this.pid);
 		this.done = this.outcome.promise;
@@ -777,6 +1029,13 @@ var LocalTerminalHandle = class {
 		const foreground = await this.inspectForeground();
 		if (foreground === void 0) throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`);
 		if (signal === "SIGKILL" && foreground.processGroupId === this.pid) throw new Error("refusing to SIGKILL the terminal shell; terminate the terminal session instead");
+		if (this.platform === "win32") {
+			if (signal === "SIGINT") {
+				this.terminal.write("");
+				return foreground.processGroupId;
+			}
+			if (signal === "SIGTSTP" || signal === "SIGHUP") throw new Error(`signal ${signal} is unsupported on Windows; only SIGINT, SIGTERM, and SIGKILL are available`);
+		}
 		this.inspector.signalGroup(foreground.processGroupId, signal);
 		return foreground.processGroupId;
 	}
@@ -862,6 +1121,10 @@ var LocalTerminalHandle = class {
 		return this.survivors(this.unionMembers(survivors, this.descendants()));
 	}
 	async stopShell() {
+		if (this.platform === "win32") {
+			await this.stopShellWindows();
+			return;
+		}
 		if (!this.exited) {
 			try {
 				this.terminal.kill("SIGTERM");
@@ -876,15 +1139,54 @@ var LocalTerminalHandle = class {
 		}
 		if (!this.exited) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
 	}
+	async stopShellWindows() {
+		const shellGone = () => this.exited || this.rootIdentity !== void 0 && !this.inspector.isAlive(this.rootIdentity);
+		if (!shellGone() && this.rootIdentity !== void 0) {
+			this.inspector.signalProcess(this.rootIdentity, "SIGTERM");
+			await this.waitForWindowsShellExit();
+		}
+		if (!shellGone() && this.rootIdentity === void 0) {
+			try {
+				this.terminal.kill();
+			} catch (_topLevelAlreadyExitedDuringKill) {}
+			await Promise.race([this.done.then(() => void 0), delay(this.graceMs)]);
+		}
+		if (!shellGone() && this.rootIdentity !== void 0) {
+			this.inspector.signalProcess(this.rootIdentity, "SIGKILL");
+			await this.waitForWindowsShellExit();
+		}
+		if (!shellGone()) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
+	}
+	async waitForWindowsShellExit() {
+		const until = Date.now() + this.graceMs;
+		while (!this.exited && Date.now() < until) {
+			if (this.rootIdentity !== void 0 && !this.inspector.isAlive(this.rootIdentity)) return;
+			await delay(Math.min(25, Math.max(1, until - Date.now())));
+		}
+	}
 	async closeOnce() {
 		let survivors = await this.stopDescendants();
 		if (survivors.length > 0) throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map((member) => member.pid).join(", ")}`);
 		await this.stopShell();
 		survivors = await this.stopDescendants();
 		if (survivors.length > 0) throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map((member) => member.pid).join(", ")}`);
+		this.settleExitIfGone();
 		this.dataDisposable.dispose();
 		this.exitDisposable.dispose();
 	}
+	settleExitIfGone() {
+		if (this.platform !== "win32") return;
+		if (this.exited) return;
+		/* v8 ignore next -- stopShellWindows() verified the shell is gone or threw;
+		the identity re-check is a defensive fence for a future caller. */
+		if (this.rootIdentity !== void 0 && this.inspector.isAlive(this.rootIdentity)) return;
+		this.exited = true;
+		this.output.end();
+		this.outcome.resolve({
+			exitCode: null,
+			signal: null
+		});
+	}
 };
 //#endregion
 //#region lib/types/index.js

package/dist/kernel/subprocess-local/lib/types/process-inspector.js

@@ -1,6 +1,7 @@
 /** Platform process-table inspection for terminal readiness, signals, and teardown. */
 import { closeSync, openSync, readFileSync, readdirSync, readSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import { createWindowsProcessInspector } from "./windows-inspector.js";
 /* v8 ignore start -- thin OS bindings; injected logic is unit-tested and real platform composition exercises them. */
 const DEFAULT_INTERNALS = {
     readFile: path => readFileSync(path, 'utf8'),
@@ -278,6 +279,8 @@ export function createProcessInspector(platform = process.platform, arch = proce
         return new LinuxProcessInspector(arch, internals);
     if (platform === 'darwin')
         return new MacProcessInspector(internals);
+    if (platform === 'win32')
+        return createWindowsProcessInspector();
     throw new Error(`subprocess-local: terminal inspection is unsupported on platform ${platform}`);
 }
 //# sourceMappingURL=process-inspector.js.map

package/dist/kernel/subprocess-local/lib/types/terminal.d.ts

@@ -15,6 +15,7 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly terminal;
     private readonly inspector;
     private readonly graceMs;
+    private readonly platform;
     readonly pid: number;
     readonly output: PassThrough;
     readonly done: Promise<SubprocessOutcome>;
@@ -30,8 +31,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
      * @param terminal - allocated node-pty process.
      * @param inspector - platform process/session operations.
      * @param graceMs - TERM-to-KILL and exit-wait grace.
+     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
      */
-    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number);
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform);
     write(data: string): Promise<void>;
     inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
     signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
@@ -50,6 +52,9 @@ export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
     private unionMembers;
     private stopDescendants;
     private stopShell;
+    private stopShellWindows;
+    private waitForWindowsShellExit;
     private closeOnce;
+    private settleExitIfGone;
 }
 //# sourceMappingURL=terminal.d.ts.map

package/dist/kernel/subprocess-local/lib/types/terminal.js

@@ -26,6 +26,7 @@ export class LocalTerminalHandle {
     terminal;
     inspector;
     graceMs;
+    platform;
     pid;
     output = new PassThrough();
     done;
@@ -41,11 +42,13 @@ export class LocalTerminalHandle {
      * @param terminal - allocated node-pty process.
      * @param inspector - platform process/session operations.
      * @param graceMs - TERM-to-KILL and exit-wait grace.
+     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
      */
-    constructor(terminal, inspector, graceMs) {
+    constructor(terminal, inspector, graceMs, platform = process.platform) {
         this.terminal = terminal;
         this.inspector = inspector;
         this.graceMs = graceMs;
+        this.platform = platform;
         this.pid = terminal.pid;
         this.rootIdentity = inspector.processTree(this.pid).find(member => member.pid === this.pid);
         this.done = this.outcome.promise;
@@ -88,6 +91,19 @@ export class LocalTerminalHandle {
         if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
             throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead');
         }
+        if (this.platform === 'win32') {
+            if (signal === 'SIGINT') {
+                // Windows has no process-group signalling: a `\x03` input write is the
+                // Ctrl-C delivery path conhost turns into a console-wide CTRL_C event
+                // for attached processes. node-pty's signal kills throw on Windows, so
+                // no signal ever reaches the inspector.
+                this.terminal.write('\x03');
+                return foreground.processGroupId;
+            }
+            if (signal === 'SIGTSTP' || signal === 'SIGHUP') {
+                throw new Error(`signal ${signal} is unsupported on Windows; only SIGINT, SIGTERM, and SIGKILL are available`);
+            }
+        }
         this.inspector.signalGroup(foreground.processGroupId, signal);
         return foreground.processGroupId;
     }
@@ -197,6 +213,10 @@ export class LocalTerminalHandle {
         return this.survivors(this.unionMembers(survivors, this.descendants()));
     }
     async stopShell() {
+        if (this.platform === 'win32') {
+            await this.stopShellWindows();
+            return;
+        }
         if (!this.exited) {
             try {
                 this.terminal.kill('SIGTERM');
@@ -218,6 +238,44 @@ export class LocalTerminalHandle {
         if (!this.exited)
             throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
     }
+    async stopShellWindows() {
+        // node-pty's Windows kill(signal) throws ("Signals not supported on
+        // windows"), and its bare kill() delegates to a console-list agent that
+        // fails when the parent has no console. taskkill tree escalation is the
+        // teardown path, fenced on the shell's start identity like every
+        // descendant; a root identity miss falls back to the bare kill. taskkill
+        // termination also does not reliably fire node-pty's exit notification
+        // (the same console-list agent), so the tiers verify the shell's absence
+        // through the inspector instead of waiting on `done` alone.
+        const shellGone = () => this.exited || (this.rootIdentity !== undefined && !this.inspector.isAlive(this.rootIdentity));
+        if (!shellGone() && this.rootIdentity !== undefined) {
+            this.inspector.signalProcess(this.rootIdentity, 'SIGTERM');
+            await this.waitForWindowsShellExit();
+        }
+        if (!shellGone() && this.rootIdentity === undefined) {
+            try {
+                this.terminal.kill();
+            }
+            catch (_topLevelAlreadyExitedDuringKill) {
+                // The exit callback is authoritative.
+            }
+            await Promise.race([this.done.then(() => undefined), delay(this.graceMs)]);
+        }
+        if (!shellGone() && this.rootIdentity !== undefined) {
+            this.inspector.signalProcess(this.rootIdentity, 'SIGKILL');
+            await this.waitForWindowsShellExit();
+        }
+        if (!shellGone())
+            throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`);
+    }
+    async waitForWindowsShellExit() {
+        const until = Date.now() + this.graceMs;
+        while (!this.exited && Date.now() < until) {
+            if (this.rootIdentity !== undefined && !this.inspector.isAlive(this.rootIdentity))
+                return;
+            await delay(Math.min(25, Math.max(1, until - Date.now())));
+        }
+    }
     async closeOnce() {
         let survivors = await this.stopDescendants();
         if (survivors.length > 0) {
@@ -228,8 +286,27 @@ export class LocalTerminalHandle {
         if (survivors.length > 0) {
             throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`);
         }
+        this.settleExitIfGone();
         this.dataDisposable.dispose();
         this.exitDisposable.dispose();
     }
+    settleExitIfGone() {
+        // An externally taskkilled Windows shell may never fire node-pty's exit
+        // notification (its console-list agent fails without a parent console),
+        // which would leave `done` — and every consumer awaiting it — unsettled
+        // forever. Teardown has just verified the shell's absence through the
+        // inspector, so a missing exit event is itself the outcome.
+        if (this.platform !== 'win32')
+            return;
+        if (this.exited)
+            return;
+        /* v8 ignore next -- stopShellWindows() verified the shell is gone or threw;
+           the identity re-check is a defensive fence for a future caller. */
+        if (this.rootIdentity !== undefined && this.inspector.isAlive(this.rootIdentity))
+            return;
+        this.exited = true;
+        this.output.end();
+        this.outcome.resolve({ exitCode: null, signal: null });
+    }
 }
 //# sourceMappingURL=terminal.js.map

package/dist/kernel/subprocess-local/lib/types/windows-inspector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Windows process-table operations for terminal readiness, signalling, and
+ * teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
+ * identity and process-handle wait-state liveness, the shell pid as a pseudo
+ * process group (Windows has no POSIX groups), and taskkill tree signalling.
+ * The koffi bindings load lazily so
+ * non-Windows processes never touch Win32 libraries; all decision logic takes
+ * an injectable internals boundary so suites can pin it on any host.
+ * @module nomix-subprocess-local/windows-inspector
+ */
+import type { SubprocessTerminalSignal } from '../../../subprocess/lib/index.js';
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts';
+/** One Toolhelp32 process-table row. */
+export interface ProcessEntry {
+    pid: number;
+    parentPid: number;
+}
+/** Creation identity plus the process object's current wait state. */
+export interface WindowsProcessState {
+    /** GetProcessTimes creation identity used to fence PID reuse. */
+    started: string;
+    /** Whether a zero-time process-handle wait reports the process still running. */
+    active: boolean;
+}
+/** Injectable Windows process operations used by one local PTY session. */
+export interface WindowsProcessInspectorInternals {
+    /** Enumerate the current process table (pid/parent pairs). */
+    snapshot(): ProcessEntry[];
+    /** Return one process's creation identity and wait state, or undefined when unreadable. */
+    processState(pid: number): WindowsProcessState | undefined;
+    /** Terminate one process tree; `force` maps to taskkill `/F`. */
+    taskkill(pid: number, force: boolean): void;
+}
+/**
+ * Walk a process table from one root in children-first order, retaining only
+ * members whose start identity is readable (unreadable members are detector
+ * misses, exactly like an unreadable `/proc` entry on Linux).
+ * @param entries - the process table snapshot.
+ * @param rootPid - the tree root to descend from.
+ * @param started - creation-time identity resolver for one member.
+ * @returns the root and its current transitive descendants, children first.
+ */
+export declare function windowsProcessTree(entries: ProcessEntry[], rootPid: number, started: (pid: number) => string | undefined): ProcessIdentity[];
+/**
+ * Windows {@link ProcessInspector}. The shell pid stands in for a foreground
+ * process group: it is a stable pseudo-group that lets the prompt-marker
+ * readiness path compare foreground identities, while every actual signal
+ * targets the console-wide tree through taskkill (SIGINT is delivered by the
+ * terminal handle as a `\x03` input write and never reaches this layer).
+ */
+export declare class WindowsProcessInspector implements ProcessInspector {
+    private readonly internals;
+    constructor(internals?: WindowsProcessInspectorInternals);
+    foregroundPgid(shellPid: number): number;
+    isStdinWaiting(_pgid: number): boolean;
+    processTree(rootPid: number): ProcessIdentity[];
+    processSession(_sessionId: number): ProcessIdentity[];
+    isAlive(identity: ProcessIdentity): boolean;
+    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/**
+ * Create the Windows process inspector.
+ * @param internals - injectable process operations; defaults to the koffi-backed table.
+ * @returns the Windows inspector.
+ */
+export declare function createWindowsProcessInspector(internals?: WindowsProcessInspectorInternals): WindowsProcessInspector;
+declare const nativePtr: unique symbol;
+/** Koffi 3 native pointer (a BigInt address), branded so it cannot silently enter numeric contexts. */
+export type NativePtr = bigint & {
+    readonly [nativePtr]: true;
+};
+/**
+ * True for NULL and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
+ * @param value - a handle as koffi may hand it back (pointer, null, or 0n).
+ * @returns whether the value signals an invalid handle.
+ */
+export declare function isInvalidHandle(value: NativePtr | null | undefined): boolean;
+export {};
+//# sourceMappingURL=windows-inspector.d.ts.map