@qlzt/dsh-subprocess-local 0.0.0-stage → 0.2.1-alpha.2

package/lib/types/output.d.ts

@@ -0,0 +1,137 @@
+import type { CollectedOutput } from '@qlzt/dsh-subprocess';
+/**
+ * Receives one spill failure so the owner can log it through its own logger.
+ * Called at most once per collector, after the spill has been discarded and
+ * the in-memory tail has kept collecting. A reporter that throws is contained
+ * and its failure written to stderr.
+ * @param error - the `node:fs` failure from opening or appending the spill file.
+ * @param label - the stream label of the collector that failed.
+ */
+export type SpillFailureReporter = (error: unknown, label: string) => void;
+/** Spill storage for one collected stream; `undefined` means tail-only collection. */
+export interface SpillOptions {
+    /** Whole-stream byte cap beyond which an incomplete spill is discarded. */
+    maxBytes: number;
+    /** Private directory receiving the spill file. */
+    dir: string;
+    /** Owner-side report of a spill open or write failure. */
+    onFailure: SpillFailureReporter;
+}
+/**
+ * Build the reporter an owner passes as {@link SpillOptions.onFailure}: one
+ * error-level log line naming the owner and stream, with the failure appended
+ * so its `code`, `syscall`, and `path` reach the log.
+ * @param logger - the owner's plugin logger.
+ * @param owner - the component named in the line.
+ * @returns the reporter.
+ */
+export declare function logSpillFailure(logger: {
+    error(message: string, ...detail: unknown[]): void;
+}, owner: string): SpillFailureReporter;
+/** Inputs a managed native process needs before its output streams are bound. */
+export interface ManagedProcessBinding {
+    /** Directory receiving spill files. */
+    spillDir: string;
+    /** Receives a spill open or write failure. */
+    onSpillFailure: SpillFailureReporter;
+}
+/**
+ * Prepare fallible output storage before starting a managed native process.
+ * This is the explicit resolve step for spill inputs: the spill directory
+ * defaults to the private per-process directory, and the failure reporter
+ * defaults to a stderr line when the caller has no logger.
+ * @param internals - optional caller-owned spill directory and failure reporter.
+ * @returns binding inputs whose spill directory is ready for use.
+ */
+export declare function prepareManagedProcessBinding(internals?: {
+    spillDir?: string;
+    onSpillFailure?: SpillFailureReporter;
+}): ManagedProcessBinding;
+/**
+ * Collects one stream with a bounded in-memory tail. With spill options, 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 them, only the in-memory tail is ever retained (the
+ * diagnostic-tail shape — a language server's stderr).
+ *
+ * Spilling is best-effort: a spill open or write failure discards the spill,
+ * reports once through {@link SpillOptions.onFailure}, and never interrupts
+ * in-memory collection, because `push()` runs inside the stream's `'data'`
+ * listener where a thrown error would become an uncaught exception.
+ *
+ * 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 label;
+    private readonly spill;
+    private chunks;
+    private bytes;
+    private dropped;
+    private spillFd;
+    private spillFile;
+    private spillDisabled;
+    /** Total bytes ever pushed (not just retained). */
+    private total;
+    /**
+     * @param maxBytes - in-memory tail cap in bytes.
+     * @param label - stream label used in spill file names and failure reports.
+     * @param spill - spill storage; omit for tail-only collection.
+     */
+    constructor(maxBytes: number, label: string, spill: SpillOptions | undefined);
+    /**
+     * 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).
+     * Runs inside the stream's `'data'` listener, so every filesystem failure is
+     * contained here: the spill is discarded, reported once, and collection
+     * continues with the in-memory tail alone.
+     */
+    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;
+    };
+    /**
+     * Copy the retained raw tail with its position in the complete observed stream.
+     * @returns independent tail bytes and the total byte count before truncation.
+     */
+    snapshot(): {
+        bytes: Buffer;
+        totalBytes: number;
+    };
+    /**
+     * 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;
+}
+//# sourceMappingURL=output.d.ts.map

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

@@ -0,0 +1,138 @@
+/** Platform process-table inspection for terminal readiness, signals, and teardown. */
+import type { SubprocessTerminalSignal } from '@qlzt/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 {
+    /** Whether the process-table scan omitted no unreadable rows; absent means unverified. */
+    readonly complete?: boolean;
+    /**
+     * 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.
+     * @throws when the platform process table cannot be enumerated.
+     */
+    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,68 @@
+/** Parent-side invocation and bootstrap state for the private native runner. */
+import type { StdioOptions } from 'node:child_process';
+import type { SubprocessSpawnSpec } from '@qlzt/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; optional control uses fd 7.
+ * @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'> & {
+    stdio?: SubprocessSpawnSpec['stdio'];
+}): Record<string, string>;
+//# sourceMappingURL=runner-launch.d.ts.map

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

@@ -0,0 +1,111 @@
+/** 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>;
+    control?: 'pipe';
+}
+/** 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>;
+    control?: 'pipe';
+}
+/** 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/shell-activity.d.ts

@@ -0,0 +1,37 @@
+import type { SubprocessTerminalActivity, SubprocessTerminalSpawnSpec } from '@qlzt/dsh-subprocess';
+/** Opt-in startup integration and revision tracking for one ordinary interactive shell. */
+export declare class ShellActivity {
+    private readonly directory;
+    readonly argv: readonly string[];
+    readonly env: Record<string, string>;
+    private revision;
+    private observed;
+    private invalidated;
+    private state;
+    /**
+     * @param directory - private startup and status file directory.
+     * @param argv - shell launch preserving supported user startup files.
+     * @param env - environment with any temporary startup redirect.
+     */
+    constructor(directory: string, argv: readonly string[], env: Record<string, string>);
+    /** Invalidate prompt evidence before delivering input or a foreground signal. */
+    invalidate(): void;
+    /**
+     * Read the latest top-level shell transition, fenced against input since that transition.
+     * @param pid - original shell process id.
+     * @returns lifecycle evidence; process ownership must be checked separately.
+     */
+    inspect(pid: number): SubprocessTerminalActivity;
+    /** Remove private startup and status files after process quiescence. */
+    dispose(): void;
+    private read;
+}
+/**
+ * Prepare optional Bash or Zsh integration for a plain, non-login interactive launch.
+ * @param spec - terminal request; custom arguments and wrapped executables remain unmodified.
+ * @param env - scrubbed target environment.
+ * @param platform - execution platform.
+ * @returns private integration, or undefined for unsupported launches.
+ */
+export declare function prepareShellActivity(spec: SubprocessTerminalSpawnSpec, env: Record<string, string>, platform: NodeJS.Platform): ShellActivity | undefined;
+//# sourceMappingURL=shell-activity.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 '@qlzt/dsh-win32-process';
+import type { CurrentTokenProcessBindings } from '@qlzt/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>, control?: 'pipe'): 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,86 @@
+/**
+ * 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 { SubprocessHandle, SubprocessSpawnSpec } from '@qlzt/dsh-subprocess';
+import type { ManagedProcessLaunch } from './managed-owner.ts';
+import { type SpillFailureReporter } from './output.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;
+    /** Receives spill open/write failures; the runtime supplies its plugin logger, bare callers get a stderr line. */
+    onSpillFailure?: SpillFailureReporter;
+    /** 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;
+}
+/**
+ * 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 - spill-directory override and spill failure reporter.
+ * @returns live subprocess handle.
+ */
+export declare function bindManagedProcess(spec: SubprocessSpawnSpec, launch: ManagedProcessLaunch, internals?: Pick<SpawnInternals, 'spillDir' | 'onSpillFailure'>): 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