@orkestrel/process 0.0.3 → 0.0.5

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

@@ -10,6 +10,20 @@ import { EmitterInterface } from '@orkestrel/emitter';
  */
 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 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.
  *
@@ -32,19 +46,6 @@ export declare function createInvalidError(subject: string, value: unknown): Pro
  */
 export declare function createProtocolError(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 RunResult}.
- *
- * @param result - The buffered run outcome that failed
- * @param cause - The underlying host fault, when one ended the run
- * @returns A typed run failure carrying its {@link RunResult}
- */
-export declare function createRunError(result: RunResult, cause?: unknown): ProcessError;
-
 /**
  * Options for a detached fire-and-forget spawn.
  *
@@ -71,9 +72,139 @@ export declare interface ExecutableOptions {
     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 run timed out, was aborted, ended on a host fault, was ended by a
+ * signal, or exited with a code other than `0`. `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` 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. For a `strict: false`
+ * caller, `failed: true` with `expired`, `aborted`, and `truncated` false, `code: 0`, and
+ * `signal: null` is the residual signature that a host fault ended the run. 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
  *
@@ -91,6 +222,9 @@ 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", "input", "duplicate", "protocol", "invalid"];
+
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 export declare const PROCESS_EVIDENCE = 2048;
 
@@ -110,13 +244,13 @@ 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 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 RunResult} / run** — a one-shot runner that buffers a child to completion and settles
+ * - **{@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}.
@@ -131,16 +265,19 @@ export declare const PROCESS_TIMER = 2147483647;
  * @remarks
  * `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 written to the child's
- * stdin immediately after spawn. Every string here is spawn-bound: an empty `file`, or a NUL
- * character anywhere, is refused with a {@link ProcessError} coded `invalid`.
+ * 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`, the child environment is `environment` alone; if `false` or omitted, it merges over the parent environment. */
+    /** If `true`, exclude the parent environment; on POSIX this leaves no `PATH`, while Windows libuv still injects a host set. */
     readonly isolated?: boolean;
 }
 
@@ -150,7 +287,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.
      *
@@ -160,8 +297,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' | 'invalid';
+/** 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 {
@@ -185,8 +322,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;
 }
 
 /**
@@ -195,14 +332,18 @@ export declare interface ProcessErrorOptions {
  *
  * @remarks
  * Declared as a `type` alias so it satisfies the emitter's `EventMap` constraint structurally. The
- * `error` event carries a child fault — a failure to spawn or a process-level error. It is distinct
- * from the `error` handler in {@link ProcessOptions}: a listener throw is isolated by the emitter and
+ * `error` event carries a child fault — a failure to spawn, a process-level error, or a
+ * host-reported standard-input channel fault after the constructor input phase. A fault arising
+ * from the constructor-supplied `input` write or its closing `end` stays quiet because the package
+ * initiated that sequence. A surfaced standard-input fault is wrapped in a
+ * {@link ProcessError} coded `protocol` with the host fault as its cause. The event is distinct from
+ * the `error` handler in {@link ProcessOptions}: a listener throw is isolated by the emitter and
  * routed to that handler, never emitted as this `error` event.
  */
 export declare type ProcessEventMap = {
     /** A decoded standard-error chunk arrived. */
     readonly stderr: readonly [chunk: string];
-    /** The child emitted an error — a spawn fault or process-level failure — carrying its cause. */
+    /** The child or its open standard-input channel reported a fault, carrying the host cause directly or through a `protocol` {@link ProcessError}. */
     readonly error: readonly [error: unknown];
     /** The child settled — its terminal state, delivered once. */
     readonly exit: readonly [exit: ProcessExit];
@@ -210,7 +351,7 @@ 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;
@@ -221,37 +362,70 @@ export declare interface ProcessExit {
  *
  * @remarks
  * `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 two iterators split the output between them rather than each
- * receiving all of it. The policy for an unconsumed backlog follows
- * consumer intent. Once an iterator has been requested, stdout pauses at the `backlog` mark and
- * resumes at half of it, so the consumer loses nothing and the child feels real backpressure. While
+ * 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. 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.
+ * 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 captured stdout lines, in arrival order, for one consumer, ending when the child's stdout closes. */
+    /**
+     * The captured stdout lines, in arrival order, for one consumer, ending when the child's stdout closes.
+     *
+     * @remarks
+     * A line feed, a CRLF pair, and a bare carriage return each terminate a line, and a CRLF split
+     * across delivered chunks joins as one break. A child that redraws a progress bar with a carriage
+     * return therefore yields one line per redraw, and consecutive carriage returns yield an empty
+     * line between them. A final line written with no trailing terminator is delivered when 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`.
+     * Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
+     * prove that the child read them. An ordinary write settles when the kernel accepts it. Only a
+     * full pipe can hold the write unconfirmed. The `delivery` option can bound that wait, and every
+     * terminal teardown path settles pending writes. On Windows 11 with Node v24.18.1, measured on
+     * 2026-08-21, a child that closes its own file descriptor 0 can leave the parent pipe writable:
+     * the write can settle `true` without a callback error or a stream error while the child remains
+     * alive. After `stop` or `destroy` begins, a later call settles `false`. Version 0.0.4 could settle
+     * that call `true` before teardown destroyed the pipe; returning `false` avoids claiming delivery
+     * for bytes the package is about to discard.
      *
      * @param text - The line text without its trailing newline
-     * @returns True when the line reached the host without error; false when the channel was closed, destroyed, ended, or the write failed
+     * @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
      */
     send(text: string): Promise<boolean>;
     /**
@@ -331,8 +505,9 @@ export declare interface 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 `protocol` 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.
+     * 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
@@ -393,10 +568,14 @@ export declare interface ProcessManagerOptions {
  * `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.
- * `on` installs initial {@link ProcessEventMap} listeners and `error` receives isolated listener
- * failures. Every numeric option is validated at construction: a timer value outside
+ * 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`.
+ * {@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>;
@@ -408,127 +587,16 @@ export declare interface ProcessOptions {
     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. Default: {@link PROCESS_BACKLOG}. */
+    /** 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;
+    /** Milliseconds an unconfirmed {@link ProcessInterface.send} waits before resolving `false`. `0` or omitted disables the bound. */
+    readonly delivery?: 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`. */
     readonly signal?: AbortSignal;
 }
 
-/**
- * The captured bytes and terminal facts one settled {@link RunResult} is built from.
- *
- * @remarks
- * Both byte fields are 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 RunInput {
-    /** 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`, both fit. */
-    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 RunResult}; `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`. 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.
- */
-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 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` are the two ways the run ended the child rather than the
- * child ending itself, and only the first of them observed is recorded. `truncated` is independent of
- * both: it reports that a stream exceeded `limit`, which fails a synchronous run and does not fail an
- * asynchronous one.
- */
-export declare interface RunResult {
-    /** 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;
-    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 if either stream exceeded `limit`, so the captured text is the retained head. */
-    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` and an output overflow both end
- * the child with `SIGKILL`; an overflow reports `truncated` and `failed` together, which is where
- * the synchronous and asynchronous runners genuinely differ.
- */
-export declare interface RunSyncOptions {
-    /** 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 host kills the child. `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;
-}
-
 /**
  * The resolved spawn form of one command: the executable to launch, the argument vector to pass,
  * and whether the host receives that vector verbatim.

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { holds } from "@orkestrel/contract";
+import { holds, isError } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
@@ -14,6 +14,15 @@ var PROCESS_OUTPUT = 10485760;
 var PROCESS_TIMER = 2147483647;
 /** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
 var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+var PROCESS_ERROR_CODES = Object.freeze([
+	"spawn",
+	"timeout",
+	"input",
+	"duplicate",
+	"protocol",
+	"invalid"
+]);
 //#endregion
 //#region src/core/errors.ts
 /** A child-process failure with a stable machine-readable category. */
@@ -32,6 +41,7 @@ var ProcessError = class extends Error {
 	constructor(message, options) {
 		const cause = options.cause;
 		super(message, cause === void 0 ? void 0 : { cause });
+		Object.defineProperty(this, Symbol.for("@orkestrel/process.error"), { value: true });
 		this.code = options.code;
 		if (options.context !== void 0) this.context = options.context;
 		if (options.result !== void 0) this.result = options.result;
@@ -40,6 +50,13 @@ var ProcessError = class extends Error {
 /**
 * 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
 *
@@ -50,7 +67,14 @@ var ProcessError = class extends Error {
 * ```
 */
 function isProcessError(value) {
-	return holds(() => value instanceof ProcessError);
+	if (!isError(value)) return false;
+	return holds(() => {
+		if (Object.getPrototypeOf(value) === Error.prototype) return false;
+		if (value.name !== "ProcessError" || !("code" in value)) return false;
+		if (Object.getOwnPropertyDescriptor(value, Symbol.for("@orkestrel/process.error"))?.value !== true) return false;
+		const code = value.code;
+		return PROCESS_ERROR_CODES.some((declared) => declared === code);
+	});
 }
 /**
 * Creates the failure raised when a manager launch reuses a live id.
@@ -98,14 +122,15 @@ function createInvalidError(subject, value) {
 * 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 RunResult}.
+* 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 host fault, when one ended the run
-* @returns A typed run failure carrying its {@link RunResult}
+* @returns A typed run failure carrying its {@link ExecuteResult}
 */
-function createRunError(result, cause) {
+function createExecuteError(result, cause) {
 	let reason = `exited with code ${String(result.code)}`;
 	if (result.signal !== null) reason = `was killed by ${result.signal}`;
 	if (result.truncated) reason = "exceeded its output limit";
@@ -123,6 +148,6 @@ function createRunError(result, cause) {
 	});
 }
 //#endregion
-export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createInvalidError, createProtocolError, createRunError, isProcessError };
+export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_ERROR_CODES, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError, isProcessError };
 
 //# sourceMappingURL=index.js.map