@orkestrel/process 0.0.2 → 0.0.4

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

@@ -13,15 +13,196 @@ export declare function createDuplicateError(id: string): ProcessError;
 /**
  * Creates the failure raised when a run does not complete successfully and rejection is requested.
  *
+ * @remarks
+ * The category is `timeout` only when the run's own timeout elapsed; every other failure,
+ * including an abort and an output overflow, is a `spawn` failure carrying its
+ * {@link ExecuteResult}.
+ *
  * @param result - The buffered run outcome that failed
- * @param cause - The underlying spawn error, when one ended the run
- * @returns A typed run failure carrying its {@link RunResult}
+ * @param cause - The underlying host fault, when one ended the run
+ * @returns A typed run failure carrying its {@link ExecuteResult}
+ */
+export declare function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError;
+
+/**
+ * Creates the failure raised when a public input is refused before anything is spawned.
+ *
+ * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
+ * @param value - The rejected value, carried as `context.value`
+ * @returns A typed validation failure
+ *
+ * @example
+ * ```ts
+ * createInvalidError("option 'grace'", -1).code // 'invalid'
+ * ```
+ */
+export declare function createInvalidError(subject: string, value: unknown): ProcessError;
+
+/**
+ * Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+ *
+ * @param id - The id the refused launch asked for
+ * @returns A typed protocol failure
  */
-export declare function createRunError(result: RunResult, cause?: unknown): ProcessError;
+export declare function createProtocolError(id: string): ProcessError;
+
+/**
+ * Options for a detached fire-and-forget spawn.
+ *
+ * @remarks
+ * A detached child owns no stdio and is never awaited, so the contract carries only the directory it
+ * starts in. Its environment comes from the command's own `environment` and `isolated`.
+ */
+export declare interface DetachOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+}
+
+/**
+ * Lookup inputs for resolving a command file to an executable path.
+ *
+ * @remarks
+ * `workspace` is searched before `PATH`, matching Windows command semantics. `environment` is the
+ * child's effective environment, so the lookup reads the same `PATH` and `PATHEXT` the child will.
+ */
+export declare interface ExecutableOptions {
+    /** The directory searched first. Default: the current working directory. */
+    readonly workspace?: string;
+    /** The child's effective environment. Default: the parent process environment. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * The captured bytes and terminal facts one settled {@link ExecuteResult} is built from.
+ *
+ * @remarks
+ * Each byte field is trimmed to `limit` on a code-point boundary when the result is built, so a
+ * caller passes the raw retained head and never a decoded string. `cause` carries the host fault
+ * that ended the run, when one did; its presence alone marks the run failed.
+ */
+export declare interface ExecuteInput {
+    /** The diagnostic command line. */
+    readonly command: string;
+    /** The retained standard-output bytes. */
+    readonly stdout: Uint8Array;
+    /** The retained standard-error bytes. */
+    readonly stderr: Uint8Array;
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** If `true`, the run's own timeout elapsed; if `false`, it did not. */
+    readonly expired: boolean;
+    /** If `true`, the caller's signal aborted the run; if `false`, it did not. */
+    readonly aborted: boolean;
+    /** If `true`, a stream exceeded `limit`; if `false`, neither did. */
+    readonly truncated: boolean;
+    /** The maximum retained bytes for each stream. */
+    readonly limit: number;
+    /** The host fault that ended the run, when one did. */
+    readonly cause?: unknown;
+}
+
+/**
+ * Options for a one-shot run.
+ *
+ * @remarks
+ * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `strict`
+ * decides how a failure is delivered: by default a non-zero exit rejects with a
+ * {@link ProcessError} carrying the {@link ExecuteResult}; `strict: false` resolves with the result
+ * instead, so the caller inspects `failed`. An invalid option or command rejects before the child is
+ * spawned, with a {@link ProcessError} coded `invalid`. `input` is standard-input payload and carries
+ * no NUL restriction. An unbounded run awaits stdio completion rather than process exit, so give
+ * `timeout` a value wherever a descendant may inherit the child's stdio and hold the pipe open past
+ * the child's own exit. Every option is read once, before the child is spawned, so the value
+ * validated is the value spawned and a caller's own getter runs while nothing has started: a getter
+ * that throws strands no process.
+ */
+export declare interface ExecuteOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Standard-input payload written to the child, including any NUL characters. */
+    readonly input?: string;
+    /** Milliseconds before the child is terminated. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** Cooperative POSIX window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
+    readonly grace?: number;
+    /** Aborting this signal terminates the run and reports `aborted`. */
+    readonly signal?: AbortSignal;
+    /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
+    readonly strict?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
+
+/**
+ * The settled outcome of a one-shot run: the buffered output and the terminal state.
+ *
+ * @remarks
+ * `failed` is `true` when the child exited non-zero, was killed by a signal, expired, was aborted, or
+ * failed to spawn. `expired` and `aborted` name the ways the run ended the child rather than the
+ * child ending itself, and only the earliest observed is recorded. `truncated` is independent of
+ * both: it reports that a captured stream omitted output because it exceeded `limit`, which fails a
+ * synchronous run and does not fail an asynchronous one. `ProcessInterface` carries the same name for
+ * the same fact against a supervised child's retention bounds. A spawn fault reports the host's negative errno for `execute`. A spawn fault reports
+ * `null` for `executeSync`.
+ */
+export declare interface ExecuteResult {
+    /** The command line that was run, for diagnostics. */
+    readonly command: string;
+    /** The captured standard output, byte-bounded by `limit`. */
+    readonly stdout: string;
+    /** The captured standard error, byte-bounded by `limit`. */
+    readonly stderr: string;
+    /** The exit code. A spawn fault reports the host's negative errno for `execute` and `null` for `executeSync`. */
+    readonly code: number | null;
+    readonly signal: string | null;
+    /** True if the run did not complete successfully. */
+    readonly failed: boolean;
+    /** True if the run's `timeout` elapsed before completion. */
+    readonly expired: boolean;
+    /** True if the caller's `signal` aborted the run before completion. */
+    readonly aborted: boolean;
+    /** True when either captured stream omitted output because it exceeded `limit`. */
+    readonly truncated: boolean;
+}
+
+/**
+ * Options for a synchronous one-shot run.
+ *
+ * @remarks
+ * The synchronous host offers neither a cooperative termination window nor in-flight cancellation,
+ * so this contract carries no `grace` and no `signal`. A `timeout` ends only the root process and can
+ * leave descendants running; use `execute` or {@link ProcessInterface} 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, which is where `execute` and `executeSync` genuinely differ.
+ * `input` is standard-input payload and carries no NUL restriction.
+ */
+export declare interface ExecuteSyncOptions {
+    /** The working directory. Default: the current working directory. */
+    readonly workspace?: string;
+    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Standard-input payload written to the child, including any NUL characters. */
+    readonly input?: string;
+    /** Milliseconds before the host kills the root process alone. `0` or omitted disables the timeout. */
+    readonly timeout?: number;
+    /** If `false`, return the result on failure instead of throwing. Default: `true`. */
+    readonly strict?: boolean;
+    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
+    readonly limit?: number;
+}
 
 /**
  * Checks whether an unknown value is a {@link ProcessError}.
  *
+ * @remarks
+ * Recognition combines a global own-property brand with the native `Error` base, the subclass
+ * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is
+ * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy
+ * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a
+ * plain or property-only lookalike.
+ *
  * @param value - The value to inspect
  * @returns True only for a `ProcessError` instance; false otherwise
  *
@@ -33,46 +214,69 @@ export declare function createRunError(result: RunResult, cause?: unknown): Proc
  */
 export declare function isProcessError(value: unknown): value is ProcessError;
 
+/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+export declare const PROCESS_BACKLOG = 10485760;
+
+/** The window in milliseconds a termination waits for the child's native exit after the final kill. */
+export declare const PROCESS_CONFIRMATION = 5000;
+
+/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+export declare const PROCESS_ERROR_CODES: readonly ["spawn", "timeout", "duplicate", "protocol", "invalid"];
+
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
-/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 export declare const PROCESS_GRACE = 5000;
 
 /** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */
 export declare const PROCESS_OUTPUT = 10485760;
 
+/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+export declare const PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+/** The largest timer delay in milliseconds the host schedules without truncating it to one. */
+export declare const PROCESS_TIMER = 2147483647;
+
 /**
  * The public contracts for `@orkestrel/process`: a typed child-process toolkit.
  *
  * @remarks
- * Three tiers, smallest to largest:
+ * The tiers divide by lifetime:
  *
- * - **{@link ProcessInterface}** — one supervised child with eagerly framed stdout lines, a
- *   byte-bounded stderr tail, a live stderr event, a writable stdin channel, a typed lifecycle
- *   {@link ProcessEventMap} emitter, and bounded `SIGTERM` → grace → `SIGKILL` termination. The
- *   low-level streaming primitive.
- * - **{@link RunResult} / run** — a one-shot runner that buffers a child to completion and settles
+ * - **{@link ProcessInterface}** — one supervised child with framed stdout lines under a bounded
+ *   backlog, a byte-bounded stderr tail, a live stderr event, a writable stdin channel, a typed
+ *   lifecycle {@link ProcessEventMap} emitter, and bounded termination. The low-level streaming
+ *   primitive.
+ * - **{@link ExecuteResult} / execute** — a one-shot spawn that buffers a child to completion and settles
  *   with its output and exit, the ergonomic layer for fire-and-collect commands.
  * - **{@link ProcessManagerInterface}** — a keyed registry of live {@link ProcessInterface}
  *   children, launched and stopped by id, observed through its own {@link ProcessManagerEventMap}.
  *
- * Every contract here is host-independent (`AbortSignal`, `AsyncIterable`, `Promise`, and plain
- * `string` signal names). The Node implementations live in `@orkestrel/process/server`.
+ * Every contract here is host-independent (`AbortSignal`, `AsyncIterable`, `Promise`, `Uint8Array`,
+ * and plain `string` signal names). The Node implementations live in `@orkestrel/process/server`.
  */
 /**
  * One spawnable command: the executable, its argument vector, and optional environment overrides
  * and initial standard input.
  *
  * @remarks
- * `environment` merges over the parent process environment; an `undefined` value unsets a key.
- * `input` is written to the child's stdin immediately after spawn.
+ * `environment` merges over the parent process environment unless `isolated` is `true`, and an
+ * `undefined` value unsets a key. On Windows the merge is case-insensitive and the last writer
+ * wins, matching how the host resolves an environment variable. `input` is standard-input payload
+ * written immediately after spawn, so it carries no NUL restriction. Every spawn-bound string here
+ * is validated: an empty `file`, or a NUL character in `file`, `arguments`, or `environment`, is
+ * refused with a {@link ProcessError} coded `invalid`. On a POSIX host, `isolated: true` leaves no
+ * `PATH`, so pass an absolute `file` or include `PATH` in `environment`. On Windows, libuv injects a
+ * host environment set even when `isolated` is `true`.
  */
 export declare interface ProcessCommand {
     readonly file: string;
     readonly arguments: readonly string[];
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly input?: string;
+    /** If `true`, exclude the parent environment; on POSIX this leaves no `PATH`, while Windows libuv still injects a host set. */
+    readonly isolated?: boolean;
 }
 
 /** A child-process failure with a stable machine-readable category. */
@@ -81,7 +285,7 @@ export declare class ProcessError extends Error {
     readonly code: ProcessErrorCode;
     readonly context?: ProcessErrorContext;
     /** The buffered run outcome, present when a one-shot run produced the failure. */
-    readonly result?: RunResult;
+    readonly result?: ExecuteResult;
     /**
      * Create a process error.
      *
@@ -91,8 +295,8 @@ export declare class ProcessError extends Error {
     constructor(message: string, options: ProcessErrorOptions);
 }
 
-/** The machine-readable {@link ProcessError} categories. */
-export declare type ProcessErrorCode = 'spawn' | 'timeout' | 'duplicate' | 'protocol';
+/** The machine-readable {@link ProcessError} categories, derived from {@link PROCESS_ERROR_CODES}. */
+export declare type ProcessErrorCode = (typeof PROCESS_ERROR_CODES)[number];
 
 /** Structured context carried by a {@link ProcessError}. */
 export declare interface ProcessErrorContext {
@@ -116,8 +320,8 @@ export declare interface ProcessErrorOptions {
     readonly context?: ProcessErrorContext;
     /** The underlying cause, when one exists. */
     readonly cause?: unknown;
-    /** The buffered run outcome, present when a {@link RunResult} produced the failure. */
-    readonly result?: RunResult;
+    /** The buffered run outcome, present when an {@link ExecuteResult} produced the failure. */
+    readonly result?: ExecuteResult;
 }
 
 /**
@@ -141,46 +345,88 @@ export declare type ProcessEventMap = {
 
 /** The observed terminal state of a child process: its exit code, or the signal that ended it. */
 export declare interface ProcessExit {
-    /** The exit code, or `null` when a signal ended the process. */
+    /** The exit code, or `null` when a signal ended the process. A spawn fault reports the host's negative errno for `Process` and `execute`. */
     readonly code: number | null;
     /** The terminating signal name, or `null` when the process exited on its own. */
     readonly signal: string | null;
 }
 
 /**
- * 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
- * `lines` is pumped eagerly: stdout is drained whether or not a consumer iterates, so `exit`
- * resolves and a late consumer still receives every line. `evidence` is the decoded, byte-bounded
- * stderr tail — the diagnostic to attach to a failed exit. The typed `emitter` carries the live
- * `stderr` chunks, the child `error` cause, and the terminal `exit`, alongside the `exit` promise.
- * `send` never throws; it returns whether the line reached an open channel. `stop` is idempotent.
+ * `lines` is pumped as soon as the child writes, and it is a single-consumer stream: each line goes
+ * to exactly one waiting iterator, so concurrent iterators split the output between them rather
+ * than each receiving all of it. The policy for an unconsumed backlog follows consumer intent. After an iterator has been requested, stdout pauses at the `backlog` mark and
+ * resumes at half of it, so the consumer loses nothing before termination and the child feels real
+ * backpressure. Termination never reapplies the pause, so from the moment a stop begins retention is
+ * capped at twice `backlog` and later lines are dropped. While
+ * no iterator has ever been requested, stdout keeps draining so `exit` still resolves, and retention
+ * stops at the mark: a consumer attaching after that point receives the retained head, a gap, then
+ * the live stream. `evidence` is the decoded, byte-bounded stderr tail — the diagnostic to attach to
+ * a failed exit. `truncated` reports that the `lines` stream omitted output, because a retention
+ * bound was reached; the one-shot `ExecuteResult` carries the same name for the same fact against
+ * its own capture `limit`. The typed `emitter` carries the live `stderr` chunks, the child `error` cause, and the
+ * terminal `exit`, alongside the `exit` promise. `stop` and `destroy` are idempotent and never reject.
+ *
+ * The spawn is eager, so `pid` is fixed by the time construction returns; a spawn that produced no
+ * child reports `undefined` for that child's whole lifetime. An assigned id survives the exit and
+ * reports no liveness on its own, because the host reuses a dead child's id. Derive liveness as
+ * `pid !== undefined && code === null && signal === null`, and derive it again before every use of
+ * the id. `code` and `signal` mirror the host child's own terminal record, so they carry the native
+ * exit as soon as the host has it, while the `exit` promise settles on stdio close — a descendant
+ * holding inherited stdio keeps that close pending past the native exit, and a supervisor inside
+ * that window reads the terminal state here.
  */
 export declare interface ProcessInterface {
+    /** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+    readonly pid: number | undefined;
+    /** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. A spawn fault reports the host's negative errno. */
+    readonly 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. */
+    readonly signal: string | null;
     /** The typed lifecycle observation surface. */
     readonly 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, for one consumer, ending when the child's stdout closes. */
     readonly lines: AsyncIterable<string>;
     /** The decoded byte-bounded stderr tail. */
     readonly evidence: string;
+    /** True when the `lines` stream omitted output because a retention bound was reached. */
+    readonly truncated: boolean;
     /** The terminal child state, observed once from the close event. */
     readonly 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. On Windows the whole tree is killed immediately through `taskkill`, with a
+     * direct kill as the fallback; on a POSIX host the process group receives `SIGTERM`, then
+     * `SIGKILL` after `grace`. No signal is initiated after the child's native exit is observed; the
+     * window between initiating a signal and the host delivering it belongs to the operating system.
+     *
+     * @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. Resolving does not imply the
+     * child's stdio has closed: a descendant holding an inherited pipe keeps the close event pending,
+     * so `exit` and `lines` can still be outstanding after this barrier settles.
      *
      * @returns The stable barrier shared by every call
      */
@@ -206,10 +452,12 @@ export declare type ProcessManagerEventMap = {
  *
  * @remarks
  * A child that settles removes itself from the registry, so `count` and `processes` reflect only
- * live children, and its departure emits `exit`. `launch` throws a {@link ProcessError} coded
- * `duplicate` when the id is already live — spawn faults surface through the returned child's
- * `exit`, not from `launch`. The typed `emitter` carries the `launch` and `exit` moments across
- * every child.
+ * live children, and its departure emits `exit`. 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 ProcessError}
+ * coded `duplicate` when the id is already live and `protocol` after `destroy` has begun — spawn
+ * faults surface through the returned child's `exit`, not from `launch`. The typed `emitter` carries
+ * the `launch` and `exit` moments across every child.
  */
 export declare interface ProcessManagerInterface {
     /** The typed fleet-level observation surface. */
@@ -232,35 +480,50 @@ export declare interface ProcessManagerInterface {
     /**
      * Spawn and register one child under `id`.
      *
+     * @remarks
+     * Every option is read before the child is spawned, 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 `protocol` 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 ProcessError} coded `protocol`.
+     * Every child is destroyed, not merely stopped, so each child's own observation emitter is
+     * destroyed too and every subscription on it goes silently inert. The registry emitter is
+     * destroyed last.
+     *
      * @returns The stable barrier shared by every call
      */
     destroy(): Promise<void>;
@@ -282,10 +545,17 @@ export declare interface ProcessManagerOptions {
  * Construction options for one supervised child process.
  *
  * @remarks
- * `grace` is the sole timing knob: after `stop`, the child is sent `SIGTERM`, then `SIGKILL` if it
- * has not exited within `grace` milliseconds. There is no completion deadline — a caller that wants
- * one arms its own timer and calls `stop`. `on` installs initial {@link ProcessEventMap} listeners
- * and `error` receives isolated listener failures.
+ * `grace` is the cooperative window between `SIGTERM` and `SIGKILL` on a POSIX host; Windows has no
+ * cooperative phase, so the value is unused there. There is no completion deadline — a caller that
+ * wants one arms its own timer and calls `stop`. `backlog` bounds the unconsumed `lines` backlog.
+ * During termination, retained lines are capped at twice `backlog`; later lines are dropped without
+ * pausing stdout, and {@link ProcessInterface.truncated} reports the omission. `on` installs initial
+ * {@link ProcessEventMap} listeners and `error` receives isolated listener failures. Every numeric
+ * option is validated at construction: a timer value outside
+ * `[0, PROCESS_TIMER]`, a negative or fractional byte value, or a `backlog` below `1` throws a
+ * {@link ProcessError} coded `invalid`. POSIX detachment creates the process group used for tree
+ * termination, so the child survives the supervisor's `SIGKILL` and does not receive the terminal's
+ * `SIGINT`. A consumer must call `stop` or `destroy` during an orderly shutdown.
  */
 export declare interface ProcessOptions {
     readonly on?: EmitterHooks<ProcessEventMap>;
@@ -293,10 +563,12 @@ export declare interface ProcessOptions {
     readonly command: ProcessCommand;
     /** The working directory the child runs in. */
     readonly workspace: string;
-    /** Cooperative termination window in milliseconds between `SIGTERM` and `SIGKILL`. */
-    readonly grace: number;
+    /** Cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`. Default: {@link PROCESS_GRACE}. */
+    readonly grace?: number;
     /** Maximum retained stderr tail in bytes. Default: {@link PROCESS_EVIDENCE}. */
     readonly evidence?: number;
+    /** Soft high-water mark in bytes for the unconsumed `lines` backlog; termination retains at most twice this value. Default: {@link PROCESS_BACKLOG}. */
+    readonly backlog?: number;
     /** If `true`, stdin stays open for {@link ProcessInterface.send}; if `false` or omitted, stdin closes after any initial `input`. */
     readonly writable?: boolean;
     /** Aborting this signal terminates the child through the same bounded `stop`. */
@@ -304,53 +576,21 @@ export declare interface ProcessOptions {
 }
 
 /**
- * Options for a one-shot run.
- *
- * @remarks
- * A run is a fire-and-collect function, not a lifecycle entity, so it carries no emitter. `reject`
- * follows the command-runner convention: by default a non-zero exit rejects with a
- * {@link ProcessError} carrying the {@link RunResult}; `reject: false` resolves with the result
- * instead, so the caller inspects `failed`.
- */
-export declare interface RunOptions {
-    /** The working directory. Default: the current working directory. */
-    readonly workspace?: string;
-    /** Environment overrides merged over the parent environment; an `undefined` value unsets a key. */
-    readonly environment?: Readonly<Record<string, string | undefined>>;
-    /** Standard input written to the child. */
-    readonly input?: string;
-    /** Milliseconds before the child is terminated. `0` or omitted disables the timeout. */
-    readonly timeout?: number;
-    /** Cooperative window between `SIGTERM` and `SIGKILL` when terminating. Default: {@link PROCESS_GRACE}. */
-    readonly grace?: number;
-    /** Aborting this signal terminates the run. */
-    readonly signal?: AbortSignal;
-    /** If `false`, resolve with the result on failure instead of rejecting. Default: `true`. */
-    readonly reject?: boolean;
-    /** Maximum captured bytes for stdout and for stderr, each. Default: {@link PROCESS_OUTPUT}. */
-    readonly limit?: number;
-}
-
-/**
- * The settled outcome of a one-shot run: the buffered output and the terminal state.
+ * The resolved spawn form of one command: the executable to launch, the argument vector to pass,
+ * and whether the host receives that vector verbatim.
  *
  * @remarks
- * `failed` is `true` when the child exited non-zero, was killed by a signal, timed out, or failed to
- * spawn. `timedOut` is `true` only when the run's own `timeout` elapsed.
+ * No spawn in this package uses an implicit shell. `verbatim` is `true` only for a Windows `.cmd` or
+ * `.bat` script, which runs through an explicitly quoted `cmd.exe /d /s /c` command line, and an
+ * argument that batch target could corrupt — one carrying `%`, which `cmd.exe` expands before it
+ * parses quotes — is refused rather than passed. A shell metacharacter in an argument is therefore
+ * data rather than syntax on every path.
  */
-export declare interface RunResult {
-    /** The command line that was run, for diagnostics. */
-    readonly command: string;
-    /** The complete captured standard output, byte-bounded by `limit`. */
-    readonly stdout: string;
-    /** The complete captured standard error, byte-bounded by `limit`. */
-    readonly stderr: string;
-    readonly code: number | null;
-    readonly signal: string | null;
-    /** True if the run did not complete successfully. */
-    readonly failed: boolean;
-    /** True if the run's `timeout` elapsed before completion. */
-    readonly timedOut: boolean;
+export declare interface SpawnInput {
+    readonly file: string;
+    readonly arguments: readonly string[];
+    /** If `true`, pass the argument vector to the host verbatim; if `false`, let the host quote it. */
+    readonly verbatim: boolean;
 }
 
 export { }