@x1a0f3n9/dsh-subprocess-local 0.1.5-rc.2

package/lib/types/process-inspector.d.ts

@@ -0,0 +1,135 @@
+/** Platform process-table inspection for terminal readiness, signals, and teardown. */
+import type { SubprocessTerminalSignal } from '@x1a0f3n9/dsh-subprocess';
+/** PID plus start identity, preventing teardown escalation after PID reuse. */
+export interface ProcessIdentity {
+    pid: number;
+    started: string;
+}
+interface FileStatus {
+    readonly rdev: number;
+    isCharacterDevice(): boolean;
+}
+/**
+ * One observation of the platform process table, shared by every question a
+ * single readiness poll or teardown pass asks.
+ *
+ * The table is read at most once, on the first question that needs it — a
+ * `/bin/ps` fork on macOS, a `/proc` walk on Linux, a Toolhelp32 enumeration on
+ * Windows. Later questions never re-read it, which is what keeps a poll's cost
+ * independent of how many descendants the running command spawned. Windows
+ * liveness needs no table at all: wait state is a per-handle question there, so
+ * a snapshot asked only for liveness never enumerates.
+ *
+ * A snapshot answers what the process table showed, which is what batch
+ * filtering wants and what signalling must not use: {@link ProcessInspector.isAlive}
+ * is the fence a signal takes, because it reads current state instead.
+ */
+export interface ProcessSnapshot {
+    /**
+     * Return the root and its transitive descendants as observed, children first.
+     * @param rootPid - tree root to descend from.
+     * @returns Observed root and descendants, children before parents.
+     */
+    tree(rootPid: number): ProcessIdentity[];
+    /**
+     * Return observed members of one POSIX process session.
+     * @param sessionId - POSIX session identifier.
+     * @returns Observed session members, empty where the platform's table omits session ids.
+     */
+    session(sessionId: number): ProcessIdentity[];
+    /**
+     * Return whether the exact identity was a non-quiescent process.
+     * @param identity - PID plus start identity to match.
+     * @returns Whether that exact identity — not merely that PID — was running.
+     */
+    alive(identity: ProcessIdentity): boolean;
+}
+/** Injectable OS process operations used by one local PTY session. */
+export interface ProcessInspector {
+    foregroundPgid(shellPid: number): number | undefined;
+    /**
+     * Report whether the foreground group waits on the terminal shell's stdin.
+     *
+     * @param pgid Foreground process-group identifier.
+     * @param shellPid Persistent terminal shell process identifier.
+     * @returns Whether a group member is blocked reading the shell's terminal input.
+     */
+    isStdinWaiting(pgid: number, shellPid: number): boolean;
+    /**
+     * Read the process table once and answer tree, session, and liveness from it.
+     * @returns A process-table observation whose reads are shared.
+     */
+    snapshot(): ProcessSnapshot;
+    /**
+     * Return whether the exact identity is a non-quiescent process right now.
+     *
+     * Reads the narrowest per-identity source the platform offers rather than a
+     * whole table, so a signalling round can re-check every target without
+     * paying for a scan. Callers filtering many members at once want
+     * {@link ProcessSnapshot.alive} instead.
+     *
+     * @param identity - PID plus start identity to match.
+     * @returns Whether that exact identity — not merely that PID — is running.
+     */
+    isAlive(identity: ProcessIdentity): boolean;
+    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    /**
+     * Signal one exact process identity, fenced against PID reuse.
+     *
+     * The fence reads current state immediately before the signal. An observation
+     * taken earlier in the same round cannot stand in for it: the observation
+     * preserves the original PID-to-start-time pairing, so a recycled PID would
+     * still match and take a signal meant for the process that exited.
+     *
+     * @param identity - PID plus start identity to signal.
+     * @param signal - termination signal to deliver.
+     */
+    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/** Testable boundary around filesystem, process-table, and signal syscalls. */
+export interface ProcessInspectorInternals {
+    readFile(path: string): string;
+    readDir(path: string): string[];
+    readLink(path: string): string;
+    stat(path: string): FileStatus;
+    open(path: string): number;
+    read(fd: number, buffer: Buffer, length: number, position: number): number;
+    close(fd: number): void;
+    exec(file: string, args: string[]): string;
+    kill(pid: number, signal: NodeJS.Signals): void;
+}
+interface ProcStat {
+    pid: number;
+    parentPid: number;
+    pgrp: number;
+    session: number;
+    state: string;
+    ttyDevice: number;
+    tpgid: number;
+    started: string;
+}
+/**
+ * Parse fields used from Linux `/proc/<pid>/stat`, including parenthesized comm text.
+ * @param text - complete stat line.
+ * @returns Parsed identity/group fields, or undefined for malformed input.
+ */
+export declare function parseProcStat(text: string): ProcStat | undefined;
+/**
+ * Report whether a Linux process group has an executing member. `false`
+ * means the group contains only zombie/dead entries; `undefined` means the
+ * process table could not prove either outcome.
+ * @param processGroupId - POSIX process-group id to inspect.
+ * @param internals - injectable process-table operations.
+ * @returns Live-member presence, or `undefined` when unavailable/absent.
+ */
+export declare function linuxProcessGroupHasLiveMembers(processGroupId: number, internals?: ProcessInspectorInternals): boolean | undefined;
+/**
+ * Create the supported platform inspector or fail at plugin load.
+ * @param platform - target Node platform.
+ * @param arch - target CPU architecture for Linux syscall numbers.
+ * @param internals - filesystem/process boundary, injectable for deterministic tests.
+ * @returns Platform process inspector.
+ */
+export declare function createProcessInspector(platform?: NodeJS.Platform, arch?: NodeJS.Architecture, internals?: ProcessInspectorInternals): ProcessInspector;
+export {};
+//# sourceMappingURL=process-inspector.d.ts.map

package/lib/types/runner-launch.d.ts

@@ -0,0 +1,66 @@
+/** Parent-side invocation and bootstrap state for the private native runner. */
+import type { StdioOptions } from 'node:child_process';
+import type { SubprocessSpawnSpec } from '@x1a0f3n9/dsh-subprocess';
+/** The one private environment variable consumed before target state is restored. */
+export declare const SUBPROCESS_RUNNER_ENV: "DSH_SUBPROCESS_RUNNER";
+/** Sentinel used by the packaged bootstrap for the Windows IPC runner. */
+export declare const WINDOWS_RUNNER_SELECTION: "windows";
+/** Non-empty command tuple used to launch the private runner entry. */
+export type RunnerInvocation = [string, ...string[]];
+/**
+ * Resolve the source, built, or packaged entry that calls the same runner core.
+ * @returns executable and arguments for the active runtime form.
+ */
+export declare function spawnRunnerInvocation(): RunnerInvocation;
+/**
+ * Check the concrete runner executable and entry paths without executing a probe mode.
+ * @param invocation - resolved executable and runner-entry arguments.
+ * @returns whether every concrete executable or entry path is accessible.
+ */
+export declare function runnerInvocationAvailable(invocation?: RunnerInvocation): boolean;
+/**
+ * Build the bootstrap-safe environment; target overrides arrive through request/IPC.
+ * @param selection - private runner selector or Linux launch-request locator.
+ * @param invocation - resolved runner invocation whose source form needs the workspace paths map.
+ * @returns environment for the runner before target state is restored.
+ */
+export declare function runnerEnvironment(selection: string, invocation?: RunnerInvocation): NodeJS.ProcessEnv;
+/**
+ * Read and delete the private selector before importing or restoring target state.
+ * @param env - mutable environment containing the private selector.
+ * @returns the consumed selector, or undefined when no runner was requested.
+ */
+export declare function consumeRunnerSelection(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Require the private argv delimiter and at least one target argv entry.
+ * @param argv - private runner arguments.
+ * @returns copied target argv after the private delimiter.
+ */
+export declare function parseRunnerTargetArgv(argv: readonly string[]): string[];
+/**
+ * Build direct Linux target stdio, or isolated Windows runner stdio with IPC
+ * on fd 3 and target carriers on fd 4 through fd 6.
+ * @param spec - ordinary subprocess request whose stdio modes are preserved.
+ * @param ipc - whether to isolate the runner and add its private Node IPC descriptor.
+ * @param stdinCarrier - runner fd 4 carrier; Windows ignore passes an opened null-device fd.
+ * @returns child-process stdio options for the runner.
+ */
+export declare function runnerStdio(spec: SubprocessSpawnSpec, ipc: boolean, stdinCarrier?: 'pipe' | number): StdioOptions;
+/**
+ * Resolve the executable path with libuv/Node Windows spawn search order while
+ * preserving the caller's original command-line argv entry separately.
+ * @param command - original target argv[0].
+ * @param cwd - final target working directory used for relative search roots.
+ * @param env - final target environment containing the child PATH.
+ * @param exists - injectable non-directory candidate probe used by tests.
+ * @param currentEnv - runner environment supplying PATH fallback and cwd-search policy.
+ * @returns a resolved application name suitable for `CreateProcessW`, or undefined when no candidate exists.
+ */
+export declare function resolveWindowsExecutable(command: string, cwd: string, env: Readonly<Record<string, string>>, exists?: (candidate: string) => boolean, currentEnv?: Readonly<Record<string, string | undefined>>): string | undefined;
+/**
+ * Materialize and synchronously validate the final target environment.
+ * @param spec - final target argv, cwd, and environment overrides.
+ * @returns complete target environment after Node-equivalent validation.
+ */
+export declare function targetEnvironment(spec: Pick<SubprocessSpawnSpec, 'argv' | 'cwd' | 'env'>): Record<string, string>;
+//# sourceMappingURL=runner-launch.d.ts.map

package/lib/types/runner-protocol.d.ts

@@ -0,0 +1,109 @@
+/** Closed private transports shared by the native subprocess runner. */
+/** Target state restored by the Linux bootstrap after systemd establishes the scope. */
+export interface LinuxLaunchRequest {
+    cwd: string;
+    env: Record<string, string>;
+}
+/** Bounded Node-shaped error fields allowed across a private runner boundary. */
+export interface SerializedRunnerError {
+    name: string;
+    message: string;
+    code?: string;
+    syscall?: string;
+    path?: string;
+}
+/** A Linux pre-exec failure published beside its consumed request. */
+export type LinuxStartupError = {
+    type: 'error';
+    error: SerializedRunnerError;
+};
+/** The only parent-to-runner start message on Windows. */
+export interface WindowsStartRequest {
+    type: 'start';
+    cwd: string;
+    env: Record<string, string>;
+}
+/** The only parent-to-runner control message on Windows. */
+export interface WindowsTerminateRequest {
+    type: 'terminate';
+}
+/** Exactly one direct-result branch is sent by a connected Windows runner. */
+export type WindowsRunnerResult = {
+    type: 'target-exit';
+    exitCode: number;
+} | {
+    type: 'error';
+    error: SerializedRunnerError;
+};
+/** Private paths owned by one Linux ordinary or PTY spawn. */
+export interface LinuxLaunchFiles {
+    directory: string;
+    requestPath: string;
+    startupErrorPath: string;
+}
+/**
+ * Create a private 0700 directory and one complete 0600 launch request.
+ * @param request - target cwd and complete environment for the bootstrap.
+ * @returns private paths owned by this launch.
+ */
+export declare function createLinuxLaunchFiles(request: LinuxLaunchRequest): LinuxLaunchFiles;
+/**
+ * Derive the only permitted startup-error path from an absolute request locator.
+ * @param requestPath - absolute path to the private launch-request file.
+ * @returns validated sibling paths for this launch.
+ */
+export declare function linuxLaunchFilesFromLocator(requestPath: string): LinuxLaunchFiles;
+/**
+ * Strictly read and remove a one-shot Linux launch request.
+ * @param requestPath - private launch-request path to consume.
+ * @returns validated target cwd and environment.
+ */
+export declare function consumeLinuxLaunchRequest(requestPath: string): LinuxLaunchRequest;
+/**
+ * Publish one strict 0600 Linux pre-exec error.
+ * @param files - private paths for this launch.
+ * @param error - bounded spawn or runner failure to publish.
+ */
+export declare function writeLinuxStartupError(files: LinuxLaunchFiles, error: LinuxStartupError): void;
+/**
+ * Read the Linux pre-exec error, if the bootstrap published one.
+ * @param path - expected startup-error path.
+ * @returns the validated failure, or undefined when none was published.
+ */
+export declare function readLinuxStartupError(path: string): LinuxStartupError | undefined;
+/**
+ * Strictly parse the single Windows start message.
+ * @param value - untrusted IPC payload.
+ * @returns validated target start request.
+ */
+export declare function parseWindowsStartRequest(value: unknown): WindowsStartRequest;
+/**
+ * Return true only for the exact, payload-free Windows terminate control.
+ * @param value - untrusted IPC payload.
+ * @returns whether the payload is the exact terminate request.
+ */
+export declare function isWindowsTerminateRequest(value: unknown): value is WindowsTerminateRequest;
+/**
+ * Strictly parse one of the two Windows direct-result branches.
+ * @param value - untrusted IPC payload.
+ * @returns validated direct-result message.
+ */
+export declare function parseWindowsRunnerResult(value: unknown): WindowsRunnerResult;
+/**
+ * Convert an unknown failure into the bounded cross-process error record.
+ * @param error - failure caught at the process boundary.
+ * @returns bounded serializable error fields.
+ */
+export declare function serializeRunnerError(error: unknown): SerializedRunnerError;
+/**
+ * Rebuild a Node-shaped Error from a strict runner record.
+ * @param serialized - validated bounded error fields.
+ * @returns reconstructed Error with supported Node fields.
+ */
+export declare function deserializeRunnerError(serialized: SerializedRunnerError): Error;
+/**
+ * Best-effort removal of only the private paths created for this Linux spawn.
+ * @param files - exact private paths owned by this launch.
+ */
+export declare function cleanupLinuxLaunchFiles(files: LinuxLaunchFiles): void;
+//# sourceMappingURL=runner-protocol.d.ts.map

package/lib/types/spawn-runner.d.ts

@@ -0,0 +1,36 @@
+/** One-shot Linux exec bootstrap and Windows Job-owning subprocess runner. */
+import { closeHandleChecked, isJobEmpty, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from '@x1a0f3n9/dsh-win32-process';
+import type { CurrentTokenProcessBindings } from '@x1a0f3n9/dsh-win32-process';
+import { resolveWindowsExecutable } from './runner-launch.ts';
+type RunnerHost = Pick<NodeJS.Process, 'env' | 'exitCode' | 'connected' | 'cwd' | 'chdir' | 'on' | 'off' | 'once' | 'disconnect'> & {
+    send?: NodeJS.Process['send'];
+};
+/** Injectable operations used by the protocol-owner tests. */
+export interface SpawnRunnerInternals {
+    execve(file: string, argv: string[], env: Record<string, string>): never;
+    loadWin32ProcessBindings(): CurrentTokenProcessBindings;
+    spawnCurrentTokenJobProcess: typeof spawnCurrentTokenJobProcess;
+    closeFileDescriptor(fileDescriptor: number): void;
+    resolveWindowsExecutable: typeof resolveWindowsExecutable;
+    pollProcessExit: typeof pollProcessExit;
+    isJobEmpty: typeof isJobEmpty;
+    terminateJob: typeof terminateJob;
+    closeHandleChecked: typeof closeHandleChecked;
+}
+/**
+ * Execute the selected Linux bootstrap or Windows Job runner.
+ * @param selection - Windows sentinel or Linux launch-request locator.
+ * @param argv - private runner arguments beginning with the target delimiter.
+ * @param host - process transport and lifecycle host.
+ * @param internals - native and filesystem operations used by the runner.
+ */
+export declare function runSpawnRunner(selection: string, argv: readonly string[], host?: RunnerHost, internals?: SpawnRunnerInternals): Promise<void>;
+/**
+ * Best-effort reporting for failures before the selected runner established its owner.
+ * @param selection - Windows sentinel, Linux launch-request locator, or no selection.
+ * @param error - failure raised before normal runner settlement.
+ * @param host - process transport and lifecycle host.
+ */
+export declare function reportSpawnRunnerFailure(selection: string | undefined, error: unknown, host?: RunnerHost): Promise<void>;
+export {};
+//# sourceMappingURL=spawn-runner.d.ts.map

package/lib/types/spawn.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Process plumbing for the local subprocess service: ordinary process launch
+ * with per-stream stdio dispositions, tail-keep collection with spill
+ * files, provider-owned range signalling, and common termination scheduling.
+ * POSIX owners stage TERM before KILL; Windows owners terminate immediately.
+ * This layer reacts to an abort signal; callers own deadlines, teardown
+ * ladders, and cause classification.
+ * @module dsh-subprocess-local/spawn
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { CollectedOutput, SubprocessHandle, SubprocessSpawnSpec } from '@x1a0f3n9/dsh-subprocess';
+import type { ManagedProcessLaunch } from './managed-owner.ts';
+type SpawnProcess = (program: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/**
+ * Build a child environment: explicit caller entries override the scrubbed
+ * parent base using the target platform's environment-key semantics. A string
+ * deliberately restores or overrides an entry; an explicit `undefined`
+ * tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
+ * @returns the environment to hand to `spawn` for the child process.
+ */
+export declare function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
+/** Injectable process, spill, and platform operations. */
+export interface SpawnInternals {
+    /** Process spawner (defaults to `node:child_process` `spawn`). */
+    spawn?: SpawnProcess;
+    /** Directory for spill files (defaults to the OS temp dir). */
+    spillDir?: string;
+    /** Windows tree-termination runner (defaults to `taskkill /PID <pid> /T /F`). */
+    taskkill?: (pid: number) => void;
+    /** Host platform override for signalling decisions. */
+    platform?: NodeJS.Platform;
+    /** Linux process-group member probe (defaults to `/proc` inspection). */
+    linuxProcessGroupHasLiveMembers?: (processGroupId: number) => boolean | undefined;
+}
+/**
+ * Local-only synchronous final termination used by the owning service during
+ * host exit and as the last fallback after failed normal disposal. It is
+ * intentionally absent from the public subprocess seam.
+ */
+export interface LocalSubprocessHandle extends SubprocessHandle {
+    /** Force-terminate the current tree synchronously without starting timers or waits. */
+    terminateForHostExit(): void;
+}
+/**
+ * Prepare fallible output storage before starting a managed native process.
+ * @param internals - optional caller-owned spill directory.
+ * @returns binding inputs whose spill directory is ready for use.
+ */
+export declare function prepareManagedProcessBinding(internals?: Pick<SpawnInternals, 'spillDir'>): {
+    spillDir: string;
+};
+/**
+ * Collects one stream with a bounded in-memory tail. With a spill cap, on
+ * first overflow a spill file is created and every chunk (including those
+ * already collected) is appended there while the full stream remains within
+ * the cap; without one, only the in-memory tail is ever retained (the
+ * diagnostic-tail shape — a language server's stderr).
+ *
+ * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
+ * end of command output; the spill file covers the head.
+ */
+export declare class OutputCollector {
+    private readonly maxBytes;
+    private readonly maxSpillBytes;
+    private readonly label;
+    private readonly spillDir;
+    private chunks;
+    private bytes;
+    private dropped;
+    private spillFd;
+    private spillFile;
+    private spillDisabled;
+    /** Total bytes ever pushed (not just retained). */
+    private total;
+    constructor(maxBytes: number, maxSpillBytes: number | undefined, label: string, spillDir: string);
+    /**
+     * Ingest one stream chunk, counting it toward the whole-stream total. On
+     * first overflow of the in-memory cap a spill file is opened (when spilling
+     * is enabled) and every chunk (already-collected ones included) is appended
+     * there from then on; the in-memory tail then drops whole chunks from its
+     * head (or the head of a single over-cap chunk) until it fits the cap again.
+     * @param chunk - the raw bytes from one stream 'data' event.
+     */
+    push(chunk: Buffer): void;
+    /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
+    private spillAll;
+    /** Stop spilling and remove the file once it can no longer hold the complete stream. */
+    private discardSpill;
+    /**
+     * Incremental read in whole-stream byte coordinates: returns everything
+     * pushed since `fromByte`. When `fromByte` has already slid out of the
+     * in-memory tail window, the read is `lossy` — it returns the whole
+     * retained tail and the gap is only recoverable from the spill file.
+     * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+     * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
+     */
+    readFrom(fromByte: number): {
+        text: string;
+        nextOffset: number;
+        lossy: boolean;
+        spillPath?: string;
+    };
+    /**
+     * Close the spill file once the stream has ended. A failed close (delayed
+     * writeback fault) stops advertising the spill path — the file may be
+     * missing its tail — while every in-memory read keeps working. Idempotent;
+     * the spawn path seals both collectors at settlement so reads after exit
+     * never point at a still-open file.
+     */
+    seal(): void;
+    /**
+     * Seal the spill file and return the final output.
+     * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
+     */
+    finalize(): CollectedOutput;
+}
+/**
+ * Send `sig` to a detached POSIX process group. Never throws: delivery races
+ * process exit and may run in a timer callback, so failures are contained and
+ * a missing pid is a no-op.
+ * @param pid - the group leader's pid, when the spawn published one.
+ * @param sig - the signal to deliver to the whole group.
+ */
+export declare function killGroup(pid: number | undefined, sig: NodeJS.Signals): void;
+/**
+ * Terminate one Windows process tree with `taskkill /T /F`. Contained like
+ * POSIX group signalling — delivery races tree exit, so an absent tree, a
+ * nonzero status, or a missing taskkill binary must not break idempotent
+ * teardown.
+ * @param pid - root process id, when the spawn published one.
+ */
+export declare function taskkillProcessTree(pid: number | undefined): void;
+/**
+ * Validate the synchronous portion of one ordinary spawn request.
+ * @param spec - exact target request.
+ * @throws when grace, cancellation, or argv is invalid before launch.
+ */
+export declare function validateSubprocessSpec(spec: SubprocessSpawnSpec): void;
+/**
+ * Bind platform launch facts to the existing stdio, outcome, abort, and termination lifecycle.
+ * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
+ * @param launch - platform streams, direct outcome, and managed-range owner.
+ * @param internals - test-only spill-directory override.
+ * @returns live subprocess handle.
+ */
+export declare function bindManagedProcess(spec: SubprocessSpawnSpec, launch: ManagedProcessLaunch, internals?: Pick<SpawnInternals, 'spillDir'>): LocalSubprocessHandle;
+/**
+ * Spawn one detached PGID/taskkill fallback and bind the common lifecycle.
+ * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
+ * @param internals - test-only spill-directory, platform, and taskkill overrides.
+ * @returns live subprocess handle.
+ */
+export declare function spawnSubprocess(spec: SubprocessSpawnSpec, internals?: SpawnInternals): LocalSubprocessHandle;
+export {};
+//# sourceMappingURL=spawn.d.ts.map

package/lib/types/terminal.d.ts

@@ -0,0 +1,69 @@
+/** Local node-pty terminal-process implementation for the subprocess seam. */
+import { PassThrough } from 'node:stream';
+import type { IPty } from 'node-pty';
+import type { SubprocessOutcome, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@x1a0f3n9/dsh-subprocess';
+import type { BoundProcessOwner } from './managed-owner.ts';
+import type { ProcessInspector } from './process-inspector.ts';
+/**
+ * A local terminal whose native managed range or fallback process-session
+ * ownership stays below the PTY backend.
+ * The seam's terminate() promise — no write, inspection, or signal in flight
+ * after settlement — holds here without operation tracking only because every
+ * handle call completes synchronously under the hood (node-pty write, ps-based
+ * inspection). A first genuinely asynchronous step in any handle call must add
+ * the tracking a remote provider needs.
+ */
+export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
+    private readonly terminal;
+    private readonly inspector;
+    private readonly graceMs;
+    private readonly platform;
+    private readonly managedOwner?;
+    private readonly resolveManagedOutcome?;
+    readonly pid: number;
+    readonly output: PassThrough;
+    readonly done: Promise<SubprocessOutcome>;
+    private readonly outcome;
+    private readonly dataDisposable;
+    private readonly exitDisposable;
+    private cleanup;
+    private managedOwnerCleaned;
+    private exited;
+    private trackedDescendants;
+    /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
+    private readonly rootIdentity;
+    /**
+     * @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, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined);
+    /** Whether node-pty has not yet published the top-level exit event. */
+    get running(): boolean;
+    write(data: string): Promise<void>;
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+    terminate(): Promise<void>;
+    /**
+     * Force-terminate the observable session synchronously during Node's exit
+     * event. This does not claim quiescence and does not replace terminate().
+     */
+    terminateForHostExit(): void;
+    private forceStopShell;
+    private survivors;
+    private descendants;
+    private waitForMembers;
+    private signalMembers;
+    private forceStopDescendants;
+    private unionMembers;
+    private stopDescendants;
+    private stopShell;
+    private stopShellWindows;
+    private waitForWindowsShellExit;
+    private closeOnce;
+    private cleanupManagedOwner;
+    private closeManagedRange;
+    private settleExitIfGone;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/lib/types/windows-inspector.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 dsh-subprocess-local/windows-inspector
+ */
+import type { SubprocessTerminalSignal } from '@x1a0f3n9/dsh-subprocess';
+import type { ProcessIdentity, ProcessInspector, ProcessSnapshot } 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, _shellPid: number): boolean;
+    isAlive(identity: ProcessIdentity): boolean;
+    snapshot(): ProcessSnapshot;
+    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