@orkestrel/process 0.0.2 → 0.0.4

package/dist/src/server/index.d.cts

@@ -1,6 +1,14 @@
 import { Buffer as Buffer_2 } from 'node:buffer';
+import { DetachOptions } from '@orkestrel/process';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { ExecutableOptions } from '@orkestrel/process';
+import { ExecuteInput } from '@orkestrel/process';
+import { ExecuteOptions } from '@orkestrel/process';
+import { ExecuteResult } from '@orkestrel/process';
+import { ExecuteResult as ExecuteResult_2 } from '@orkestrel/process';
+import { ExecuteSyncOptions } from '@orkestrel/process';
 import { ProcessCommand } from '@orkestrel/process';
+import { ProcessCommand as ProcessCommand_2 } from '@orkestrel/process';
 import { ProcessEventMap } from '@orkestrel/process';
 import { ProcessExit } from '@orkestrel/process';
 import { ProcessInterface } from '@orkestrel/process';
@@ -8,45 +16,106 @@ import { ProcessManagerEventMap } from '@orkestrel/process';
 import { ProcessManagerInterface } from '@orkestrel/process';
 import { ProcessManagerOptions } from '@orkestrel/process';
 import { ProcessOptions } from '@orkestrel/process';
-import { RunOptions } from '@orkestrel/process';
-import { RunResult } from '@orkestrel/process';
+import { SpawnInput } from '@orkestrel/process';
 
 /**
- * Builds one settled {@link RunResult} from a completed one-shot run's captured bytes and exit.
+ * Builds the executable candidates an explicit platform would search.
  *
  * @remarks
- * `failed` is derived: a run failed when it timed out, was ended by a signal, or exited with a
- * code other than `0` — a `null` code from a spawn fault is therefore a failure. Both output
- * buffers are byte-bounded by `limit` before decoding.
- *
- * @param command - The diagnostic command line
- * @param stdout - The captured standard output bytes
- * @param stderr - The captured standard error bytes
- * @param code - The exit code, or `null` when a signal or spawn fault ended the run
- * @param signal - The terminating signal, or `null`
- * @param timedOut - If `true`, the run's own timeout elapsed; if `false`, it did not
- * @param limit - The maximum captured bytes for each stream
+ * Windows alone needs this list: the host searches the working directory before `PATH` and applies
+ * `PATHEXT`, and Node reproduces neither for a direct spawn. Within each searched directory the
+ * literal name is tried first and each `PATHEXT` candidate after it, whether or not the name already
+ * carries an extension — so `report.txt` resolves to a `report.txt` file where one exists and to
+ * `report.txt.cmd` where none does. The lookup reads the child's effective environment, so an
+ * overridden `PATH` selects the executable the child would have found. A POSIX host resolves the
+ * file itself, so the candidate list there is empty. An appended extension is spelled the way
+ * `PATHEXT` spells it rather than the way the directory entry does, which the case-insensitive host
+ * treats as the same file. A non-Windows platform returns an empty list because `execvp` performs
+ * its own lookup.
+ *
+ * @param file - The command executable name or path
+ * @param workspace - The directory searched first
+ * @param environment - The child's effective environment
+ * @param platform - The platform whose lookup rules apply
+ * @returns The ordered absolute candidate paths
+ *
+ * @example
+ * ```ts
+ * buildExecutableCandidates('git', 'C:\\work', { PATH: 'C:\\bin' }, 'win32')
+ * ```
+ */
+export declare function buildExecutableCandidates(file: string, workspace: string, environment: Readonly<Record<string, string | undefined>>, platform: NodeJS.Platform): readonly string[];
+
+/**
+ * Builds one settled {@link ExecuteResult} from a completed run's captured bytes and terminal facts.
+ *
+ * @remarks
+ * `failed` is derived: a run failed when it timed out, was aborted, ended on a host fault, was ended
+ * by a signal, or exited with a code other than `0` — a `null` code from a spawn fault is therefore
+ * a failure. Each byte field is bounded by `limit` on a code-point boundary here, which is the one
+ * place the captured bytes are decoded.
+ *
+ * @param input - The captured bytes, terminal state, and capture limit
  * @returns The frozen run outcome
  *
  * @example
  * ```ts
- * buildRunResult('git status', Buffer.from('ok'), Buffer.alloc(0), 0, null, false, 1024)
+ * buildExecuteResult({
+ * 	command: 'git status',
+ * 	stdout: Buffer.from('ok'),
+ * 	stderr: Buffer.alloc(0),
+ * 	code: 0,
+ * 	signal: null,
+ * 	expired: false,
+ * 	aborted: false,
+ * 	truncated: false,
+ * 	limit: 1_024,
+ * }).failed // false
  * ```
  */
-export declare function buildRunResult(command: string, stdout: Buffer_2, stderr: Buffer_2, code: number | null, signal: string | null, timedOut: boolean, limit: number): RunResult;
+export declare function buildExecuteResult(input: ExecuteInput): ExecuteResult;
 
 /**
- * Renders one command into its diagnostic command line.
+ * Builds a spawn form from a resolved file and an explicit platform.
+ *
+ * @remarks
+ * A resolved `.cmd` or `.bat` script cannot be spawned directly **on Windows**, so it runs there
+ * through an explicitly quoted `cmd.exe /d /s /c` command line with the argument vector passed
+ * verbatim. No path uses a shell, so a metacharacter in an argument is never interpreted. `cmd.exe`
+ * expands `%NAME%` before it parses quotes, so no quoting can carry a percent sign through to a
+ * Windows batch target: an argument carrying one is refused there rather than silently rewritten.
+ * The whole batch path is Windows-only. A POSIX host has no `cmd.exe` and no restriction on spawning
+ * a file directly, so a target named `worker.cmd` spawns directly there and receives a percent sign
+ * as literal text.
+ *
+ * @param command - The executable and its argument vector
+ * @param file - The resolved executable file
+ * @param environment - The child's effective environment
+ * @param platform - The platform whose batch rules apply
+ * @returns The file, argument vector, and verbatim flag to spawn with
+ * @throws A {@link ProcessError} coded `invalid` when `platform` is `win32`, the resolved target is a batch script, and an argument carries a percent sign
+ *
+ * @example
+ * ```ts
+ * buildPlatformSpawn({ file: 'node', arguments: ['--version'] }, 'node', {}, 'linux').verbatim // false
+ * ```
+ */
+export declare function buildPlatformSpawn(command: ProcessCommand, file: string, environment: Readonly<Record<string, string | undefined>>, platform: NodeJS.Platform): SpawnInput;
+
+/**
+ * Builds the resolved spawn form of one command for the current host.
  *
  * @param command - The executable and its argument vector
- * @returns The space-joined command line, for a {@link RunResult} and error messages
+ * @param options - The directory searched first and the child's effective environment
+ * @returns The file, argument vector, and verbatim flag to spawn with
+ * @throws A {@link ProcessError} coded `invalid` when the host is Windows, the resolved target is a batch script, and an argument carries a percent sign
  *
  * @example
  * ```ts
- * commandLine({ file: 'git', arguments: ['status'] }) // 'git status'
+ * buildSpawn({ file: 'node', arguments: ['--version'] }).verbatim // false
  * ```
  */
-export declare function commandLine(command: ProcessCommand): string;
+export declare function buildSpawn(command: ProcessCommand, options?: ExecutableOptions): SpawnInput;
 
 /**
  * Creates one supervised child process.
@@ -82,16 +151,144 @@ export declare function createProcess(options: ProcessOptions): ProcessInterface
  */
 export declare function createProcessManager(options?: ProcessManagerOptions): ProcessManagerInterface;
 
+/**
+ * Spawns one command as a detached process and returns without waiting for it.
+ *
+ * @remarks
+ * The child owns no stdio and is unreferenced, so it outlives this process and nothing here observes
+ * its outcome. The error listener is attached before the child is unreferenced, so a post-spawn host
+ * fault is swallowed rather than crashing the caller; an invalid command is refused before anything
+ * is spawned.
+ *
+ * @param command - The executable, arguments, and optional environment
+ * @param options - The working directory the detached child starts in
+ * @returns Nothing
+ * @throws A {@link ProcessError} coded `invalid` when the working directory or a command string is malformed
+ *
+ * @example
+ * ```ts
+ * detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
+ * ```
+ */
+export declare function detach(command: ProcessCommand_2, options?: DetachOptions): void;
+
+/**
+ * Runs one command to completion, buffering its output, and settles with the outcome.
+ *
+ * @remarks
+ * The executable is resolved through {@link buildSpawn}, so no run uses a shell. On a POSIX host the
+ * child is detached, which is what lets its whole process group be terminated. Standard output and
+ * error are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}) and `truncated` reports
+ * whether either stream exceeded it. A positive `timeout` and an aborting `signal` both terminate the
+ * child through the same bounded stop, and only the earliest is recorded: a timeout reports
+ * `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
+ * a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
+ * covers a terminated run alone: a run with no `timeout` and no `signal` settles on stdio completion
+ * rather than on process exit, so a descendant that inherited the child's stdio holds the run open
+ * after the child itself has gone. Give such a run a `timeout`. The child's `environment` merges over
+ * the parent unless the command is `isolated`, then `options.environment` on top, and `options.input`
+ * overrides `command.input`. Unless `strict` is `false`, a failed run rejects with a
+ * {@link createExecuteError} carrying the {@link ExecuteResult}. An invalid option or command string rejects
+ * before the child is spawned, because an async function cannot throw synchronously.
+ *
+ * @param command - The executable, arguments, and optional environment and input
+ * @param options - Working directory, timeout, grace, signal, capture limit, and failure delivery
+ * @returns The settled run outcome
+ * @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link ExecuteResult} when the run failed and `strict` is not `false`
+ *
+ * @example
+ * ```ts
+ * const result = await execute({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+ * ```
+ */
+export declare function execute(command: ProcessCommand_2, options?: ExecuteOptions): Promise<ExecuteResult_2>;
+
+/**
+ * Runs one command to completion synchronously, buffering its output, and returns the outcome.
+ *
+ * @remarks
+ * The synchronous counterpart of {@link execute}, spawned through the same resolver and never through a
+ * shell. The host offers no cooperative termination window and no in-flight cancellation, so this
+ * contract carries neither. A positive `timeout` ends only the root process and can leave
+ * descendants running; use {@link execute} or {@link Process} when timeout must terminate the tree. A
+ * timeout and an output overflow both end the root with `SIGKILL`: an overflow reports `truncated`
+ * and `failed` together and trims the partial output to `limit`, where {@link execute} keeps reading and
+ * reports `truncated` without failing. The environment and input follow the same merge as
+ * {@link execute}. Unless `strict` is `false`, a failed run throws a {@link createExecuteError}
+ * carrying the {@link ExecuteResult}.
+ *
+ * @param command - The executable, arguments, and optional environment and input
+ * @param options - Working directory, timeout, capture limit, and failure delivery
+ * @returns The run outcome
+ * @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link ExecuteResult} when the run failed and `strict` is not `false`
+ *
+ * @example
+ * ```ts
+ * const result = executeSync({ file: 'git', arguments: ['--version'] }, { strict: false })
+ * ```
+ */
+export declare function executeSync(command: ProcessCommand_2, options?: ExecuteSyncOptions): ExecuteResult_2;
+
+/**
+ * Renders one command into its diagnostic command line.
+ *
+ * @param command - The executable and its argument vector
+ * @returns The space-joined command line, for an {@link ExecuteResult} and error messages
+ *
+ * @example
+ * ```ts
+ * formatCommand({ file: 'git', arguments: ['status'] }) // 'git status'
+ * ```
+ */
+export declare function formatCommand(command: ProcessCommand): string;
+
+/**
+ * Checks whether a child process has reached its native exit.
+ *
+ * @remarks
+ * The host sets exactly one of these fields when the process ends, so together they are the
+ * authoritative liveness answer. Reading them before each signal is what keeps a signal from being
+ * initiated against a pid the host may have reused.
+ *
+ * @param child - The child boundary
+ * @returns True when the process has exited; false while it is live
+ *
+ * @example
+ * ```ts
+ * isExited({ exitCode: 0, signalCode: null }) // true
+ * ```
+ */
+export declare function isExited(child: Pick<ProcessChild, 'exitCode' | 'signalCode'>): boolean;
+
+/**
+ * Checks whether a path names a regular file.
+ *
+ * @remarks
+ * Existence alone does not make a lookup hit: a directory named `git` on `PATH` is not the `git`
+ * command. An unreadable or malformed path reports `false` rather than throwing.
+ *
+ * @param target - The absolute or relative path to inspect
+ * @returns True when the path resolves to a regular file; false otherwise
+ *
+ * @example
+ * ```ts
+ * isFile(process.execPath) // true
+ * ```
+ */
+export declare function isFile(target: string): boolean;
+
 /**
  * Signals one owned child process, or its detached process group on a POSIX host.
  *
  * @remarks
  * On a POSIX host a child spawned `detached` leads its own process group, so signalling the
- * negated pid reaches the whole tree. On Windows, or when no pid is available, the signal goes to
- * the child directly. A throw during signalling is swallowed: the process can exit and win the
- * signal race, and the child's close event remains the authoritative terminal state.
+ * negated pid reaches the whole tree. When no group owns the pid and the host reports `ESRCH`, the
+ * signal falls back to the child directly. On Windows, or when no pid is available, the signal also
+ * goes to the child directly. Every other throw during signalling is swallowed: the process can
+ * exit between the caller's liveness check and this call, and the child's native exit remains the
+ * authoritative terminal state.
  *
- * @param child - The child process signal boundary
+ * @param child - The child boundary
  * @param signal - The signal to deliver
  * @returns Nothing
  *
@@ -100,40 +297,87 @@ export declare function createProcessManager(options?: ProcessManagerOptions): P
  * killProcess(child, 'SIGTERM')
  * ```
  */
-export declare function killProcess(child: {
-    readonly pid?: number | undefined;
-    kill(signal: NodeJS.Signals): boolean;
-}, signal: NodeJS.Signals): void;
+export declare function killProcess(child: Pick<ProcessChild, 'pid' | 'kill'>, signal: NodeJS.Signals): void;
+
+/**
+ * Kills one Windows process tree through `taskkill`.
+ *
+ * @remarks
+ * Windows has no process group a signal can reach, so the whole tree is ended by the host utility,
+ * addressed by its absolute `System32` path so a `PATH` override cannot substitute another program.
+ * The call is bounded: it is killed itself when `timeout` elapses, which is what keeps a termination
+ * from waiting on the host indefinitely. A tree is discoverable only while its root lives, so a
+ * descendant that outlives the root is beyond this mechanism.
+ *
+ * @param pid - The root process id of the tree to end
+ * @param timeout - The milliseconds the utility is given before it is killed
+ * @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
+ *
+ * @example
+ * ```ts
+ * await killTree(child.pid ?? 0, 5_000)
+ * ```
+ */
+export declare function killTree(pid: number, timeout: number): Promise<boolean>;
+
+/**
+ * Merges environment overrides into the environment one child receives on the current host.
+ *
+ * @param isolated - If `true`, the parent environment is excluded; if `false`, the overrides layer over it
+ * @param base - The command's own environment overrides
+ * @param override - Per-invocation overrides applied last
+ * @returns The environment for a spawn, carrying no unset key
+ *
+ * @example
+ * ```ts
+ * mergeEnvironment(true, { TOKEN: 'a' }) // { TOKEN: 'a' }
+ * ```
+ */
+export declare function mergeEnvironment(isolated: boolean, base?: Readonly<Record<string, string | undefined>>, override?: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
 
 /**
- * Merges environment overrides over the current process environment.
+ * Merges environment layers under an explicit platform's key rules.
  *
  * @remarks
- * Later maps override earlier ones and an `undefined` value unsets a key. The base is the parent
- * process environment, so a child inherits it unless a key is overridden or unset.
+ * Later maps override earlier ones and an `undefined` value unsets a key. For `win32` the keys fold
+ * case-insensitively and the last writer wins, so `PATH` followed by `Path` yields one variable
+ * rather than two the host would resolve unpredictably.
  *
+ * @param platform - The platform whose key rules apply
+ * @param parent - The parent environment layer
+ * @param isolated - If `true`, the parent environment is excluded; if `false`, the overrides layer over it
  * @param base - The command's own environment overrides
  * @param override - Per-invocation overrides applied last
- * @returns The merged environment for a spawn
+ * @returns The environment for a spawn, carrying no unset key
  *
  * @example
  * ```ts
- * mergeEnvironment({ TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+ * mergePlatformEnvironment('linux', {}, false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
  * ```
  */
-export declare function mergeEnvironment(base?: Readonly<Record<string, string | undefined>>, override?: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
+export declare function mergePlatformEnvironment(platform: NodeJS.Platform, parent: Readonly<Record<string, string | undefined>>, isolated: boolean, base?: Readonly<Record<string, string | undefined>>, override?: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
 
 /**
- * One supervised child process with eagerly framed output and bounded termination.
+ * One supervised child process with framed output, a bounded backlog, and bounded termination.
  *
  * @remarks
- * Standard output is drained eagerly through `readline`, so `exit` resolves and a late consumer of
- * `lines` still receives every framed line, including a final line written without a trailing
- * newline. Standard error is decoded and forwarded live as the `stderr` event while a byte-bounded
- * raw tail is retained as `evidence`. The typed `emitter` also carries the child `error` cause on a
- * spawn fault and the terminal `exit`, alongside the `exit` promise. `stop` terminates the child
- * through `SIGTERM`, then `SIGKILL` after
- * `grace`, and is idempotent; `destroy` stops the child and destroys the emitter last.
+ * Standard output is framed through `readline` into a single-consumer stream: each line goes to
+ * exactly one waiting iterator, so concurrent iterators split the output rather than each receiving
+ * all of it. While no consumer has ever requested an iterator, stdout keeps draining so `exit` still
+ * resolves, and retention stops at the `backlog` mark: a
+ * consumer attaching later receives the retained head, a gap, then the live stream. After an iterator
+ * has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
+ * nothing before termination and the child feels real backpressure. The mark is soft — the ordinary backlog can
+ * overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
+ * reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
+ * and `truncated` reports the omission. Standard error is decoded and forwarded live as the `stderr`
+ * event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries the
+ * child `error` cause on a spawn fault and the terminal `exit`, alongside the `exit` promise. `pid`,
+ * `code`, and `signal` read the spawned child directly, so the native exit is readable before the
+ * `exit` promise settles on stdio close. `stop` ends the whole tree and reports whether the native
+ * exit was observed; `destroy` stops the child, destroys stdin so every pending `send` settles, and
+ * destroys the emitter last. `destroy` resolving does not imply the child's stdio has closed, so
+ * `exit` and `lines` can still be outstanding when a descendant holds an inherited pipe.
  *
  * @example
  * ```ts
@@ -142,7 +386,6 @@ export declare function mergeEnvironment(base?: Readonly<Record<string, string |
  * const child = new Process({
  * 	command: { file: 'node', arguments: ['--version'] },
  * 	workspace: process.cwd(),
- * 	grace: 5000,
  * })
  * const exit = await child.exit
  * await child.destroy()
@@ -151,48 +394,134 @@ export declare function mergeEnvironment(base?: Readonly<Record<string, string |
 export declare class Process implements ProcessInterface {
     #private;
     /**
-     * Spawn one child process and begin eager stream capture.
+     * Spawn one child process and begin stream capture.
      *
-     * @param options - Command, workspace, termination, evidence, stdin, and observation settings
+     * @param options - Command, workspace, termination, capture, stdin, and observation settings
+     * @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
      */
     constructor(options: ProcessOptions);
+    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    get pid(): number | undefined;
+    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+    get code(): number | null;
+    /** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+    get signal(): string | null;
     /** The typed lifecycle observation surface. */
     get emitter(): EmitterInterface<ProcessEventMap>;
-    /** The eagerly captured stdout lines, in arrival order, ending when the child's stdout closes. */
+    /** The captured stdout lines, in arrival order, ending when the child's stdout closes. */
     get lines(): AsyncIterable<string>;
     /** The decoded byte-bounded stderr tail. */
     get evidence(): string;
+    /** True when the `lines` stream omitted output after a retention bound was reached. */
+    get truncated(): boolean;
     /** The terminal child state, observed once from the close event. */
     get exit(): Promise<ProcessExit>;
     /**
      * Write one line to the open standard-input channel.
      *
+     * @remarks
+     * Never rejects. The promise settles when the host reports the line handled, so a line written to
+     * a child that is not reading stays pending until the child drains it or the channel closes. Every
+     * terminal teardown path destroys stdin, so a pending write always settles by teardown; a caller
+     * that needs its own deadline arms a timer and calls `stop`.
+     *
      * @param text - The line text without its trailing newline
-     * @returns True when the channel accepted the line without backpressure; false otherwise
+     * @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
      */
-    send(text: string): boolean;
+    send(text: string): Promise<boolean>;
     /**
      * Terminate the child process tree and await its observed exit.
      *
-     * @returns A promise that resolves after bounded termination
+     * @remarks
+     * Never rejects, and every call shares one termination.
+     *
+     * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
      */
-    stop(): Promise<void>;
+    stop(): Promise<boolean>;
     /**
-     * Stop the child and destroy the observation emitter.
+     * Stop the child, close its standard-input channel, and destroy the observation emitter.
+     *
+     * @remarks
+     * Always resolves, including when termination was never confirmed.
      *
      * @returns The stable barrier shared by every call
      */
     destroy(): Promise<void>;
 }
 
+/**
+ * The Node-side contracts of `@orkestrel/process/server`.
+ *
+ * @remarks
+ * The host-independent contracts live in `@orkestrel/process`. This module declares only what a
+ * Node child process boundary requires, which the published contracts cannot express without
+ * naming `node:child_process` types.
+ */
+/**
+ * The child boundary the termination helpers drive.
+ *
+ * @remarks
+ * A `ChildProcess` satisfies this structurally, and so does any object carrying the same
+ * members, which is what lets a caller drive `stopChild` over a child it spawned itself. Each helper
+ * takes the slice of this contract it reads: `exitCode` and `signalCode` are the host's
+ * authoritative liveness answer, `pid` addresses a POSIX process group, `kill` delivers one signal,
+ * `once` reports the native exit, and `off` releases that listener when the wait ends at its
+ * deadline instead.
+ *
+ * A non-detached child stays in its caller's process group, so no group carries its pid. `kill` is
+ * the route that reaches it: `killProcess` signals the negated `pid` first and falls back to `kill`
+ * when the host reports that no group owns that pid.
+ */
+export declare interface ProcessChild {
+    /** The process id the host assigned, or `undefined` when the spawn never produced one. */
+    readonly pid?: number | undefined;
+    /** The exit code, or `null` while the process is live or a signal ended it. */
+    readonly exitCode: number | null;
+    /** The terminating signal name, or `null` while the process is live or it exited on its own. */
+    readonly signalCode: string | null;
+    /**
+     * Deliver one signal to the process.
+     *
+     * @param signal - The signal to deliver
+     * @returns True when the host accepted the signal; false otherwise
+     */
+    kill(signal: NodeJS.Signals): boolean;
+    /**
+     * Register a one-shot listener for the native exit.
+     *
+     * @param event - The `exit` event name
+     * @param listener - The listener invoked after the process exits
+     * @returns Whatever the emitter returns, which the helpers ignore
+     */
+    once(event: 'exit', listener: () => void): unknown;
+    /**
+     * Release one previously registered exit listener.
+     *
+     * @remarks
+     * `waitForExit` calls this when its deadline elapses before the exit, so a child that outlives
+     * several bounded waits accumulates no listeners.
+     *
+     * @param event - The `exit` event name
+     * @param listener - The listener registered through `once`
+     * @returns Whatever the emitter returns, which the helpers ignore
+     */
+    off(event: 'exit', listener: () => void): unknown;
+}
+
 /**
  * A keyed registry of live supervised child processes.
  *
  * @remarks
  * A child launched under an id joins the registry and emits `launch`; when it settles it removes
- * itself and emits `exit`, so `count` and `processes` reflect only live children. `launch` throws
- * a {@link createDuplicateError} when the id is already live — a spawn fault surfaces through the
- * returned child's `exit`, never from `launch`. `destroy` stops every child, then destroys the
+ * itself and emits `exit`, so `count` and `processes` reflect only live children. The id is reserved
+ * before the child is constructed and released when construction throws, so a refused launch never
+ * strands its key. Eviction follows the child's own `exit` promise, which no listener can forge, so
+ * it lands one microtask after the child's public `exit` event: a listener on that event still sees
+ * the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
+ * and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
+ * getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
+ * `exit`, never from `launch`. `destroy` awaits every child's own teardown, which destroys each
+ * child's observation emitter and leaves every subscription on it silently inert, then destroys the
  * registry emitter last.
  *
  * @example
@@ -203,7 +532,6 @@ export declare class Process implements ProcessInterface {
  * const child = manager.launch('build', {
  * 	command: { file: 'node', arguments: ['build.js'] },
  * 	workspace: process.cwd(),
- * 	grace: 5000,
  * })
  * await child.exit
  * await manager.destroy()
@@ -237,107 +565,208 @@ export declare class ProcessManager implements ProcessManagerInterface {
     /**
      * Spawn and register one child under `id`.
      *
+     * @remarks
+     * {@link Process} reads every option before it spawns, so a caller's own option getter runs while
+     * nothing has started and a throw from one strands no process. A getter that begins `destroy`
+     * without throwing is the one remaining race, and it leaves a bounded residual: the child is
+     * already spawned, so the launch is refused with a {@link createProtocolError} and that child is
+     * torn down asynchronously, bounded by `grace` plus the confirmation window. The `protocol`
+     * refusal throws synchronously before the `destroy` barrier settles. The barrier does not cover
+     * that child's asynchronous teardown.
+     *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
      * @returns The launched child
-     * @throws A {@link ProcessError} coded `duplicate` when `id` is already live
+     * @throws A {@link ProcessError} coded `duplicate` when `id` is already live, `protocol` when the registry is being destroyed, or `invalid` when an option or command string is malformed
      */
     launch(id: string, options: ProcessOptions): ProcessInterface;
     /**
      * Terminate the named children and await their exit.
      *
      * @param ids - The registry keys to stop
-     * @returns True when every named child stopped, false when any id was not live
+     * @returns True when every named child was live and its exit was confirmed; false otherwise
      */
     stop(ids: readonly string[]): Promise<boolean>;
     /**
      * Terminate one child and await its exit.
      *
      * @param id - The registry key to stop
-     * @returns True when the child was live and stopped, false when the id was not live
+     * @returns True when the child was live and its exit was confirmed; false when the id was not live or the confirmation deadline elapsed
      */
     stop(id: string): Promise<boolean>;
     /**
      * Terminate every live child and await their exit.
      *
-     * @returns A promise that resolves after all children stop
+     * @returns A promise that resolves after every child stops
      */
     stop(): Promise<void>;
     /**
      * Stop every child, then destroy the registry emitter last.
      *
+     * @remarks
+     * Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
+     * destroyed rather than merely stopped, so its own observation emitter is destroyed too and every
+     * subscription on it goes silently inert.
+     *
      * @returns The stable barrier shared by every call
      */
     destroy(): Promise<void>;
 }
 
 /**
- * Checks whether a command file must be spawned through a shell on the current host.
+ * Quotes one command-line token for a `cmd.exe` command line.
  *
  * @remarks
- * Node v22+ refuses to spawn a Windows `.cmd` or `.bat` batch file directly and returns `EINVAL`,
- * and a bare command name such as `git` resolves through `PATHEXT` to a batch shim rather than an
- * executable. Both cases run through the shell. A POSIX host, and a Windows path carrying a real
- * executable extension such as `.exe`, spawn directly. When the result is `true`, treat the
- * command file and arguments as trusted: shell invocation exposes shell metacharacters.
+ * A token carrying whitespace or a shell metacharacter is wrapped in double quotes so `cmd.exe`
+ * passes it as one literal argument; an embedded double quote is doubled, which is how `cmd.exe`
+ * reads a literal quote inside a quoted token. The quoted set includes `%`, although quoting cannot
+ * stop `cmd.exe` expansion; {@link buildSpawn} therefore refuses `%` in an argument to a Windows
+ * batch target.
  *
- * @param file - The command executable name or path
- * @returns True when the file must run through a shell; false when it spawns directly
+ * @param value - The token to quote
+ * @returns The token, quoted only when `cmd.exe` would otherwise split or interpret it
  *
  * @example
  * ```ts
- * requiresShell('git') // true on Windows, false on POSIX
+ * quoteArgument('a&b') // '"a&b"'
  * ```
  */
-export declare function requiresShell(file: string): boolean;
+export declare function quoteArgument(value: string): string;
 
 /**
- * Runs one command to completion, buffering its output, and settles with the outcome.
+ * Reads one environment variable under an explicit platform's key rules.
  *
  * @remarks
- * The child is spawned through the cross-platform command resolver ({@link requiresShell}) and, on
- * a POSIX host, detached so its whole process group can be terminated. Standard output and error
- * are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` arms a
- * timer that terminates the child through `SIGTERM`, then `SIGKILL` after `grace`
- * (default {@link PROCESS_GRACE}); aborting `signal` terminates the same way. The child's
- * `environment` merges over the parent, then `options.environment` on top, and `options.input`
- * overrides `command.input`. Unless `reject` is `false`, a failed run rejects with a
- * {@link createRunError} carrying the {@link RunResult}.
+ * Windows environment keys are case-insensitive, so a merged record can hold `Path` where the
+ * caller asks for `PATH`. The exact key is tried first and a folded scan runs only for `win32`.
  *
- * @param command - The executable, arguments, and optional environment and input
- * @param options - Working directory, timeout, grace, signal, capture limit, and reject behavior
- * @returns The settled run outcome
- * @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+ * @param environment - The environment record to read
+ * @param name - The variable name
+ * @param platform - The platform whose key rules apply
+ * @returns The value, or `undefined` when the environment declares no such variable
  *
  * @example
  * ```ts
- * const result = await run({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+ * readPlatformVariable({ Path: 'C:\\Windows' }, 'PATH', 'win32') // 'C:\\Windows'
  * ```
  */
-export declare function run(command: ProcessCommand, options?: RunOptions): Promise<RunResult>;
+export declare function readPlatformVariable(environment: Readonly<Record<string, string | undefined>>, name: string, platform: NodeJS.Platform): string | undefined;
 
 /**
- * Runs one command to completion synchronously, buffering its output, and returns the outcome.
+ * Reads one environment variable the way the current host resolves it.
+ *
+ * @param environment - The environment record to read
+ * @param name - The variable name
+ * @returns The value, or `undefined` when the environment declares no such variable
+ *
+ * @example
+ * ```ts
+ * readVariable({ PATH: '/usr/bin' }, 'PATH') // '/usr/bin'
+ * ```
+ */
+export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
+
+/**
+ * Resolves a command file to the executable path the host would launch.
+ *
+ * @param file - The command executable name or path
+ * @param options - The directory searched first and the child's effective environment
+ * @returns The resolved absolute path, or `undefined` when no candidate is a regular file
+ *
+ * @example
+ * ```ts
+ * resolveExecutable('git', {}) ?? 'git' // an absolute path on Windows, 'git' elsewhere
+ * ```
+ */
+export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
+
+/**
+ * Accumulates byte totals while retaining a bounded stream head.
+ *
+ * @example
+ * ```ts
+ * const retention = new Retention()
+ * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
+ * retention.retained // 3
+ * ```
+ */
+export declare class Retention implements RetentionInterface {
+    #private;
+    /** The bytes delivered by the stream. */
+    get delivered(): number;
+    /** The bytes retained from the stream head. */
+    get retained(): number;
+    /**
+     * Retains a delivered chunk within a byte limit.
+     *
+     * @param chunk - The delivered chunk, ignored when it is not a buffer
+     * @param limit - The maximum retained byte count
+     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
+     */
+    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
+}
+
+/** Exposes byte totals and bounded stream-head retention. */
+export declare interface RetentionInterface {
+    /** The bytes delivered by the stream. */
+    readonly delivered: number;
+    /** The bytes retained from the stream head. */
+    readonly retained: number;
+    /**
+     * Retains a delivered chunk within a byte limit.
+     *
+     * @param chunk - The delivered chunk, ignored when it is not a buffer
+     * @param limit - The maximum retained byte count
+     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
+     */
+    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
+}
+
+/**
+ * Takes one owned frozen snapshot of a caller's command.
  *
  * @remarks
- * The synchronous counterpart of {@link run}. The child is spawned through the same cross-platform
- * command resolver ({@link requiresShell}). Standard output and error are each byte-bounded by
- * `limit` (default {@link PROCESS_OUTPUT}). A positive `timeout` is enforced by the host, which
- * ends the child with `SIGKILL` when it elapses. The environment and input follow the same merge
- * as {@link run}. Unless `reject` is `false`, a failed run throws a {@link createRunError} carrying
- * the {@link RunResult}.
+ * Every public entry point snapshots before it validates, so the object validated is the object
+ * spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
+ * command whose `file` changes between reads would otherwise validate one executable and spawn
+ * another. The argument vector and the environment record are copied and frozen, so a caller
+ * mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
+ * becoming an explicit `undefined`.
  *
- * @param command - The executable, arguments, and optional environment and input
- * @param options - Working directory, timeout, signal, capture limit, and reject behavior
- * @returns The run outcome
- * @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+ * @param command - The caller's command, whose properties may be getters
+ * @returns A frozen command carrying the values read at this instant
  *
  * @example
  * ```ts
- * const result = runSync({ file: 'git', arguments: ['--version'] }, { reject: false })
+ * snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
  * ```
  */
-export declare function runSync(command: ProcessCommand, options?: RunOptions): RunResult;
+export declare function snapshotCommand(command: ProcessCommand): ProcessCommand;
+
+/**
+ * Terminates one child process tree and reports whether its native exit was observed.
+ *
+ * @remarks
+ * Windows ends the whole tree at once through {@link killTree}, falling back to a direct kill after
+ * the utility fails, because the host has no cooperative termination to offer. A POSIX host signals
+ * the process group `SIGTERM`, falls back to the direct child when no group owns its pid, waits
+ * `grace`, then sends `SIGKILL` through the same route. No signal is initiated after the native exit
+ * is observed; the window between initiating a signal and the host delivering it belongs to the
+ * operating system. `confirm` bounds each awaited step rather than the call as a whole: on Windows
+ * it bounds the `taskkill` call and then the final wait, and on a POSIX host `grace` bounds the
+ * cooperative wait and `confirm` the final one. Never rejects.
+ *
+ * @param child - The child boundary
+ * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
+ * @param confirm - The milliseconds the native exit is awaited after the final kill
+ * @returns True when the native exit was observed; false when `confirm` elapsed without it
+ *
+ * @example
+ * ```ts
+ * const confirmed = await stopChild(child, 5_000, 5_000)
+ * ```
+ */
+export declare function stopChild(child: ProcessChild, grace: number, confirm: number): Promise<boolean>;
 
 /**
  * Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
@@ -347,7 +776,7 @@ export declare function runSync(command: ProcessCommand, options?: RunOptions):
  * a multibyte sequence, the end retreats to the sequence's start so the retained bytes always end
  * on a code-point boundary and decode without a replacement character.
  *
- * @param buffer - The accumulated bytes
+ * @param bytes - The accumulated bytes
  * @param limit - The maximum retained byte count
  * @returns The leading bytes, at most `limit` and never ending mid-sequence
  *
@@ -356,7 +785,7 @@ export declare function runSync(command: ProcessCommand, options?: RunOptions):
  * trimHead(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
  * ```
  */
-export declare function trimHead(buffer: Buffer_2, limit: number): Buffer_2;
+export declare function trimHead(bytes: Uint8Array, limit: number): Buffer_2;
 
 /**
  * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -366,7 +795,7 @@ export declare function trimHead(buffer: Buffer_2, limit: number): Buffer_2;
  * multibyte sequence, the start advances past the leading continuation bytes so the retained
  * bytes always begin on a code-point boundary.
  *
- * @param buffer - The accumulated bytes
+ * @param bytes - The accumulated bytes
  * @param limit - The maximum retained byte count
  * @returns The trailing bytes, at most `limit` and never starting mid-sequence
  *
@@ -375,6 +804,121 @@ export declare function trimHead(buffer: Buffer_2, limit: number): Buffer_2;
  * trimTail(Buffer.from('hello'), 3) // <Buffer 6c 6c 6f>
  * ```
  */
-export declare function trimTail(buffer: Buffer_2, limit: number): Buffer_2;
+export declare function trimTail(bytes: Uint8Array, limit: number): Buffer_2;
+
+/**
+ * Validates one byte-valued option.
+ *
+ * @param value - The value to inspect, or `undefined` when the option was omitted
+ * @param subject - The rejected input named as the caller wrote it, such as `option 'limit'`
+ * @param minimum - The smallest accepted value
+ * @returns Nothing; a successful return means the value bounds a real byte count
+ * @throws A {@link ProcessError} coded `invalid` when the value is not a safe integer at or above `minimum`
+ *
+ * @example
+ * ```ts
+ * validateBytes(1_024, "option 'limit'", 0) // returns
+ * ```
+ */
+export declare function validateBytes(value: number | undefined, subject: string, minimum: number): void;
+
+/**
+ * Validates every spawn-bound string of one command.
+ *
+ * @param command - The executable, arguments, and optional environment overrides
+ * @returns Nothing; a successful return means the command reaches the host intact
+ * @throws A {@link ProcessError} coded `invalid` when the file is empty or any string carries a NUL
+ *
+ * @example
+ * ```ts
+ * validateCommand({ file: 'git', arguments: ['status'] }) // returns
+ * ```
+ */
+export declare function validateCommand(command: ProcessCommand): void;
+
+/**
+ * Validates every spawn-bound string of one environment override map.
+ *
+ * @remarks
+ * The host refuses a NUL in a variable name or value with a raw `ERR_INVALID_ARG_VALUE`, so the same
+ * refusal runs here for a command's own overrides and for a per-invocation override map alike.
+ *
+ * @param environment - The override map, or `undefined` when none was supplied
+ * @returns Nothing; a successful return means every name and value reaches the host intact
+ * @throws A {@link ProcessError} coded `invalid` when a name is empty or a name or value carries a NUL
+ *
+ * @example
+ * ```ts
+ * validateEnvironment({ TOKEN: 'a' }) // returns
+ * ```
+ */
+export declare function validateEnvironment(environment: Readonly<Record<string, string | undefined>> | undefined): void;
+
+/**
+ * Validates one spawn-bound string.
+ *
+ * @remarks
+ * A NUL character terminates a string for the host, so it is refused everywhere rather than
+ * reaching the spawn as a raw `ERR_INVALID_ARG_VALUE`.
+ *
+ * @param value - The value to inspect
+ * @param subject - The rejected input named as the caller wrote it, such as `command file`
+ * @param required - If `true`, an empty string is refused; if `false`, it is accepted
+ * @returns Nothing; a successful return means the string is spawn-safe
+ * @throws A {@link ProcessError} coded `invalid` when the value is not a string, carries a NUL, or is required and empty
+ *
+ * @example
+ * ```ts
+ * validateText('status', 'command argument', false) // returns
+ * ```
+ */
+export declare function validateText(value: unknown, subject: string, required: boolean): void;
+
+/**
+ * Validates one timer-valued option in milliseconds.
+ *
+ * @remarks
+ * The host truncates a fractional delay and converts anything above {@link PROCESS_TIMER} to one
+ * millisecond, so a requested 25-day timeout would otherwise fire immediately.
+ *
+ * @param value - The value to inspect, or `undefined` when the option was omitted
+ * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
+ * @returns Nothing; a successful return means the value schedules as written
+ * @throws A {@link ProcessError} coded `invalid` when the value is not a non-negative integer at or below `PROCESS_TIMER`
+ *
+ * @example
+ * ```ts
+ * validateTimer(5_000, "option 'grace'") // returns
+ * ```
+ */
+export declare function validateTimer(value: number | undefined, subject: string): void;
+
+/**
+ * Validates the working directory one child starts in.
+ *
+ * @param workspace - The directory, or `undefined` when the option was omitted
+ * @returns Nothing; a successful return means the directory reaches the host intact
+ * @throws A {@link ProcessError} coded `invalid` when the directory is empty or carries a NUL
+ *
+ * @example
+ * ```ts
+ * validateWorkspace(process.cwd()) // returns
+ * ```
+ */
+export declare function validateWorkspace(workspace: string | undefined): void;
+
+/**
+ * Waits for one child process's native exit, bounded by a deadline.
+ *
+ * @param child - The child boundary
+ * @param timeout - The milliseconds to wait before giving up
+ * @returns A promise that resolves on the native exit or when the deadline elapses, whichever comes first
+ *
+ * @example
+ * ```ts
+ * await waitForExit(child, 5_000)
+ * ```
+ */
+export declare function waitForExit(child: Pick<ProcessChild, 'exitCode' | 'signalCode' | 'once' | 'off'>, timeout: number): Promise<void>;
 
 export { }