@orkestrel/process 0.0.3 → 0.0.4

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

@@ -2,7 +2,13 @@ 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';
@@ -10,19 +16,43 @@ 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 run's captured bytes and terminal facts.
+ * Builds the executable candidates an explicit platform would search.
+ *
+ * @remarks
+ * 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. Both byte fields are bounded by `limit` on a code-point boundary here, which is the one
+ * 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
@@ -30,7 +60,7 @@ import { SpawnInput } from '@orkestrel/process';
  *
  * @example
  * ```ts
- * buildRunResult({
+ * buildExecuteResult({
  * 	command: 'git status',
  * 	stdout: Buffer.from('ok'),
  * 	stderr: Buffer.alloc(0),
@@ -43,20 +73,37 @@ import { SpawnInput } from '@orkestrel/process';
  * }).failed // false
  * ```
  */
-export declare function buildRunResult(input: RunInput): RunResult;
+export declare function buildExecuteResult(input: ExecuteInput): ExecuteResult;
 
 /**
- * Builds the resolved spawn form of one command.
+ * Builds a spawn form from a resolved file and an explicit platform.
  *
  * @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.
+ * 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
  * @param options - The directory searched first and the child's effective environment
@@ -123,13 +170,70 @@ export declare function createProcessManager(options?: ProcessManagerOptions): P
  * detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function detach(command: ProcessCommand, options?: DetachOptions): void;
+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 a {@link RunResult} and error messages
+ * @returns The space-joined command line, for an {@link ExecuteResult} and error messages
  *
  * @example
  * ```ts
@@ -178,10 +282,11 @@ export declare function isFile(target: string): boolean;
  *
  * @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 between the
- * caller's liveness check and this call, and the child's native exit 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 boundary
  * @param signal - The signal to deliver
@@ -216,13 +321,30 @@ export declare function killProcess(child: Pick<ProcessChild, 'pid' | 'kill'>, s
 export declare function killTree(pid: number, timeout: number): Promise<boolean>;
 
 /**
- * Merges environment overrides into the environment one child receives.
+ * 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 layers under an explicit platform's key rules.
  *
  * @remarks
- * Later maps override earlier ones and an `undefined` value unsets a key. On Windows the keys fold
+ * 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
@@ -230,30 +352,32 @@ export declare function killTree(pid: number, timeout: number): Promise<boolean>
  *
  * @example
  * ```ts
- * mergeEnvironment(false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
+ * mergePlatformEnvironment('linux', {}, false, { TOKEN: 'a' }, { TOKEN: undefined }) // TOKEN unset
  * ```
  */
-export declare function mergeEnvironment(isolated: boolean, 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 framed output, a bounded backlog, and bounded termination.
  *
  * @remarks
  * 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
+ * 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 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.
+ * 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
@@ -276,12 +400,20 @@ export declare class Process implements ProcessInterface {
      * @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 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>;
     /**
@@ -329,11 +461,16 @@ export declare class Process implements ProcessInterface {
  * The child boundary the termination helpers drive.
  *
  * @remarks
- * A `ChildProcess` satisfies this structurally, and so does any object carrying the same four
+ * 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,
- * and `once` reports the native exit.
+ * `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. */
@@ -353,10 +490,22 @@ export declare interface ProcessChild {
      * Register a one-shot listener for the native exit.
      *
      * @param event - The `exit` event name
-     * @param listener - The listener invoked once the process exits
+     * @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;
 }
 
 /**
@@ -421,8 +570,9 @@ export declare class ProcessManager implements ProcessManagerInterface {
      * 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.
+     * 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
@@ -469,8 +619,9 @@ export declare class ProcessManager implements ProcessManagerInterface {
  * @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.
+ * 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 value - The token to quote
  * @returns The token, quoted only when `cmd.exe` would otherwise split or interpret it
@@ -483,139 +634,127 @@ export declare class ProcessManager implements ProcessManagerInterface {
 export declare function quoteArgument(value: string): string;
 
 /**
- * Reads one environment variable the way the host resolves it.
+ * Reads one environment variable under an explicit platform's key rules.
  *
  * @remarks
  * 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.
+ * caller asks for `PATH`. The exact key is tried first and a folded scan runs only for `win32`.
  *
  * @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
- * readVariable({ Path: 'C:\\Windows' }, 'PATH') // 'C:\\Windows' on Windows
+ * readPlatformVariable({ Path: 'C:\\Windows' }, 'PATH', 'win32') // 'C:\\Windows'
  * ```
  */
-export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
+export declare function readPlatformVariable(environment: Readonly<Record<string, string | undefined>>, name: string, platform: NodeJS.Platform): 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.
+ * Reads one environment variable the way the current host resolves it.
  *
- * @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
+ * @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
- * resolveExecutable('git', {}) ?? 'git' // an absolute path on Windows, 'git' elsewhere
+ * readVariable({ PATH: '/usr/bin' }, 'PATH') // '/usr/bin'
  * ```
  */
-export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
+export declare function readVariable(environment: Readonly<Record<string, string | undefined>>, name: string): string | undefined;
 
 /**
- * Retains one delivered chunk up to a byte limit and records what the stream delivered.
+ * Resolves a command file to the executable path the host would launch.
  *
- * @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
+ * @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
- * const chunks: Buffer[] = []
- * const counts = [0, 0]
- * retainChunk(Buffer.from('hello'), chunks, counts, 3)
- * counts[1] // 3
+ * resolveExecutable('git', {}) ?? 'git' // an absolute path on Windows, 'git' elsewhere
  * ```
  */
-export declare function retainChunk(chunk: unknown, chunks: Buffer_2[], counts: number[], limit: number): void;
+export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
 
 /**
- * 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 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 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 RunResult} when the run failed and `strict` is not `false`
+ * Accumulates byte totals while retaining a bounded stream head.
  *
  * @example
  * ```ts
- * const result = await run({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
+ * const retention = new Retention()
+ * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
+ * retention.retained // 3
  * ```
  */
-export declare function run(command: ProcessCommand, options?: RunOptions): Promise<RunResult>;
+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;
+}
 
 /**
- * Runs one command to completion synchronously, buffering its output, and returns the outcome.
+ * Takes one owned frozen snapshot of a caller's command.
  *
  * @remarks
- * 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}.
+ * 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, 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 RunResult} when the run failed and `strict` 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'] }, { strict: false })
+ * snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
  * ```
  */
-export declare function runSync(command: ProcessCommand, options?: RunSyncOptions): 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 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.
+ * 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`
@@ -780,6 +919,6 @@ export declare function validateWorkspace(workspace: string | undefined): void;
  * await waitForExit(child, 5_000)
  * ```
  */
-export declare function waitForExit(child: Pick<ProcessChild, 'exitCode' | 'signalCode' | 'once'>, timeout: number): Promise<void>;
+export declare function waitForExit(child: Pick<ProcessChild, 'exitCode' | 'signalCode' | 'once' | 'off'>, timeout: number): Promise<void>;
 
 export { }