@orkestrel/process 0.0.1 → 0.0.3

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

@@ -1,5 +1,7 @@
 import { Buffer as Buffer_2 } from 'node:buffer';
+import { DetachOptions } from '@orkestrel/process';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { ExecutableOptions } from '@orkestrel/process';
 import { ProcessCommand } from '@orkestrel/process';
 import { ProcessEventMap } from '@orkestrel/process';
 import { ProcessExit } from '@orkestrel/process';
@@ -8,45 +10,65 @@ import { ProcessManagerEventMap } from '@orkestrel/process';
 import { ProcessManagerInterface } from '@orkestrel/process';
 import { ProcessManagerOptions } from '@orkestrel/process';
 import { ProcessOptions } from '@orkestrel/process';
+import { RunInput } from '@orkestrel/process';
 import { RunOptions } from '@orkestrel/process';
 import { RunResult } from '@orkestrel/process';
+import { RunSyncOptions } 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 one settled {@link RunResult} from a completed run's captured bytes and terminal facts.
  *
  * @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
+ * `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. Both byte fields are 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)
+ * buildRunResult({
+ * 	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 buildRunResult(input: RunInput): RunResult;
 
 /**
- * Renders one command into its diagnostic command line.
+ * Builds the resolved spawn form of one command.
+ *
+ * @remarks
+ * The executable is resolved against the child's effective environment. 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
- * @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 +104,86 @@ 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, options?: DetachOptions): void;
+
+/**
+ * Renders one command into its diagnostic command line.
+ *
+ * @param command - The executable and its argument vector
+ * @returns The space-joined command line, for a {@link RunResult} 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.
+ * the child directly. A 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,39 +192,68 @@ 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 over the current process environment.
+ * Merges environment overrides into the environment one child receives.
  *
  * @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. On Windows 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 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
+ * mergeEnvironment(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 mergeEnvironment(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 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 two 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. Once an iterator
+ * has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
+ * nothing and the child feels real backpressure. The mark is soft — the host delivers whole chunks,
+ * so the backlog overshoots it by up to one delivered chunk plus the drain that termination
+ * releases. 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` 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
@@ -141,7 +262,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()
@@ -150,14 +270,15 @@ 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 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;
@@ -166,32 +287,92 @@ export declare class Process implements ProcessInterface {
     /**
      * 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 four
+ * 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,
+ * and `once` reports the native exit.
+ */
+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 once the process exits
+     * @returns Whatever the emitter returns, which the helpers ignore
+     */
+    once(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
@@ -202,7 +383,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()
@@ -236,77 +416,163 @@ 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 `destroy` barrier
+     * settled before the refusal, so awaiting it does not cover that 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
+ * 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. Every other token is left exactly as written, so a
+ * batch script still receives `%1` without added quotes.
+ *
+ * @param value - The token to quote
+ * @returns The token, quoted only when `cmd.exe` would otherwise split or interpret it
+ *
+ * @example
+ * ```ts
+ * quoteArgument('a&b') // '"a&b"'
+ * ```
+ */
+export declare function quoteArgument(value: string): string;
+
+/**
+ * Reads one environment variable the way the host resolves it.
  *
  * @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.
+ * 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 on Windows.
+ *
+ * @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: 'C:\\Windows' }, 'PATH') // 'C:\\Windows' on Windows
+ * ```
+ */
+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.
+ *
+ * @remarks
+ * Windows alone needs this: 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 answer there is always `undefined`. 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.
  *
  * @param file - The command executable name or path
- * @returns True when the file must run through a shell; false when it spawns directly
+ * @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;
+
+/**
+ * Retains one delivered chunk up to a byte limit and records what the stream delivered.
+ *
+ * @remarks
+ * The retained head is kept as chunk slices and joined once, so a long stream never repeatedly
+ * concatenates a growing buffer. `counts` is a two-slot tally: slot `0` counts every delivered byte
+ * and slot `1` counts the retained bytes, so a caller compares slot `0` against `limit` to learn
+ * whether the capture was truncated.
+ *
+ * @param chunk - The delivered chunk, ignored when it is not a buffer
+ * @param chunks - The retained head, appended to in place
+ * @param counts - The `[delivered, retained]` tally, updated in place
+ * @param limit - The maximum retained byte count
+ * @returns Nothing
  *
  * @example
  * ```ts
- * requiresShell('git') // true on Windows, false on POSIX
+ * const chunks: Buffer[] = []
+ * const counts = [0, 0]
+ * retainChunk(Buffer.from('hello'), chunks, counts, 3)
+ * counts[1] // 3
  * ```
  */
-export declare function requiresShell(file: string): boolean;
+export declare function retainChunk(chunk: unknown, chunks: Buffer_2[], counts: number[], limit: number): void;
 
 /**
  * Runs one command to completion, buffering its output, and settles with the outcome.
  *
  * @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}.
+ * 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 first of them 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 createRunError} carrying the {@link RunResult}. 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 reject behavior
+ * @param options - Working directory, timeout, grace, signal, capture limit, and failure delivery
  * @returns The settled run outcome
- * @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+ * @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link RunResult} when the run failed and `strict` is not `false`
  *
  * @example
  * ```ts
@@ -319,24 +585,49 @@ export declare function run(command: ProcessCommand, options?: RunOptions): Prom
  * Runs one command to completion synchronously, buffering its output, and returns the outcome.
  *
  * @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}.
+ * The synchronous counterpart of {@link run}, 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` and an output overflow both end the child with
+ * `SIGKILL`: an overflow reports `truncated` and `failed` together and trims the partial output to
+ * `limit`, where {@link run} keeps reading and reports `truncated` without failing. The environment
+ * and input follow the same merge as {@link run}. Unless `strict` is `false`, a failed run throws a
+ * {@link createRunError} carrying the {@link RunResult}.
  *
  * @param command - The executable, arguments, and optional environment and input
- * @param options - Working directory, timeout, signal, capture limit, and reject behavior
+ * @param options - Working directory, timeout, capture limit, and failure delivery
  * @returns The run outcome
- * @throws A {@link ProcessError} carrying the {@link RunResult} when the run failed and `reject` is not `false`
+ * @throws A {@link ProcessError} coded `invalid` for a malformed option, command string, or batch-bound argument, or one carrying the {@link RunResult} when the run failed and `strict` is not `false`
  *
  * @example
  * ```ts
- * const result = runSync({ file: 'git', arguments: ['--version'] }, { reject: false })
+ * const result = runSync({ file: 'git', arguments: ['--version'] }, { strict: false })
  * ```
  */
-export declare function runSync(command: ProcessCommand, options?: RunOptions): RunResult;
+export declare function runSync(command: ProcessCommand, options?: RunSyncOptions): RunResult;
+
+/**
+ * Terminates one child process tree and reports whether its native exit was observed.
+ *
+ * @remarks
+ * Windows ends the tree at once through {@link killTree}, falling back to a direct kill when the
+ * utility fails, because the host has no cooperative termination to offer. A POSIX host signals the
+ * process group `SIGTERM`, waits `grace`, then signals `SIGKILL`. No signal is initiated once 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.
@@ -346,7 +637,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
  *
@@ -355,7 +646,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.
@@ -365,7 +656,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
  *
@@ -374,6 +665,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'>, timeout: number): Promise<void>;
 
 export { }