@orkestrel/process 0.0.4 → 0.0.6

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

@@ -187,9 +187,13 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * 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.
+ * overrides `command.input`. A host fault while writing that input terminates the run by design and
+ * marks its result failed; a strict rejection carries the host fault as its cause. This differs
+ * from `Process` constructor input, whose package-initiated input phase stays quiet. Unless `strict`
+ * is `false`, a failed run rejects with a {@link ProcessError} carrying the {@link ExecuteResult};
+ * {@link createExecuteError} constructs every rejection outside the input-fault door. 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
@@ -358,26 +362,23 @@ export declare function mergeEnvironment(isolated: boolean, base?: Readonly<Reco
 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.
+ * Supervises one child while keeping every observation channel aligned at termination.
  *
  * @remarks
- * Standard output is framed through `readline` into a single-consumer stream: each line goes to
- * exactly one waiting iterator, so concurrent iterators split the output rather than each receiving
- * all of it. While no consumer has ever requested an iterator, stdout keeps draining so `exit` still
- * resolves, and retention stops at the `backlog` mark: a
- * consumer attaching later receives the retained head, a gap, then the live stream. After an iterator
- * has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
- * nothing before termination and the child feels real backpressure. The mark is soft — the ordinary backlog can
- * overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
- * reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
- * and `truncated` reports the omission. Standard error is decoded and forwarded live as the `stderr`
- * event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries the
- * child `error` cause on a spawn fault and the terminal `exit`, alongside the `exit` promise. `pid`,
- * `code`, and `signal` read the spawned child directly, so the native exit is readable before the
- * `exit` promise settles on stdio close. `stop` ends the whole tree and reports whether the native
- * exit was observed; `destroy` stops the child, destroys stdin so every pending `send` settles, and
- * destroys the emitter last. `destroy` resolving does not imply the child's stdio has closed, so
- * `exit` and `lines` can still be outstanding when a descendant holds an inherited pipe.
+ * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
+ * the host child directly, so they expose native exit as soon as the host records it. `settled`,
+ * `exit`, `evidence`, and `lines` reach one terminal moment after the read channels close or the
+ * bounded `drain` window cuts them off. That window is armed by the child's native exit and by a
+ * termination this package initiated, so every way a child can end reaches the moment. The terminal
+ * routine freezes `evidence` and ends `lines` before it destroys stdout, stderr, or the emitter, so
+ * the push channel never disappears while a pull channel can still change or wait indefinitely.
+ *
+ * Standard output is framed through `readline` into a single-consumer stream. Lines already framed
+ * and queued remain available through the terminal moment, while bytes arriving after a requested
+ * termination may be cut off. Standard error is forwarded through the live `stderr` event and
+ * retained as a byte-bounded raw tail until that same moment. `stop` ends the child tree and the
+ * observation surfaces. `destroy` performs that stop and then destroys the emitter after the
+ * frozen terminal state exists.
  *
  * @example
  * ```ts
@@ -408,41 +409,53 @@ export declare class Process implements ProcessInterface {
     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. */
+    /** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
     get lines(): AsyncIterable<string>;
-    /** The decoded byte-bounded stderr tail. */
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
     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. */
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after termination began, including after the terminal moment. */
+    get stopping(): boolean;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
     get exit(): Promise<ProcessExit>;
     /**
      * Write one line to the open standard-input channel.
      *
      * @remarks
-     * Never rejects. The promise settles when the host reports the line handled, so a line written to
-     * a child that is not reading stays pending until the child drains it or the channel closes. Every
-     * terminal teardown path destroys stdin, so a pending write always settles by teardown; a caller
-     * that needs its own deadline arms a timer and calls `stop`.
+     * 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>;
     /**
-     * Terminate the child process tree and await its observed exit.
+     * Terminates the child process tree and reaches the terminal observation moment.
      *
      * @remarks
-     * Never rejects, and every call shares one termination.
+     * Never rejects, and every call shares one termination. After the termination sequence returns,
+     * confirmed or not, it waits at most `drain` for the read channels to close, then cuts them off
+     * and settles `exit` when they remain open. A cutoff reached before the native exit reports the
+     * `code` and `signal` the host had recorded by then, which is `null` for a child still running.
      *
      * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
      */
     stop(): Promise<boolean>;
     /**
-     * Stop the child, close its standard-input channel, and destroy the observation emitter.
+     * Stops the child and destroys the observation emitter after the terminal state freezes.
      *
      * @remarks
-     * Always resolves, including when termination was never confirmed.
+     * Always resolves, including when termination was never confirmed. Every call shares one barrier.
      *
      * @returns The stable barrier shared by every call
      */
@@ -465,8 +478,8 @@ export declare class Process implements ProcessInterface {
  * members, which is what lets a caller drive `stopChild` over a child it spawned itself. Each helper
  * takes the slice of this contract it reads: `exitCode` and `signalCode` are the host's
  * authoritative liveness answer, `pid` addresses a POSIX process group, `kill` delivers one signal,
- * `once` reports the native exit, and `off` releases that listener when the wait ends at its
- * deadline instead.
+ * `once` reports the native exit to `waitForExit` or the stream close to `waitForClose`, and `off`
+ * releases the corresponding listener when either wait ends.
  *
  * 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`
@@ -487,25 +500,25 @@ export declare interface ProcessChild {
      */
     kill(signal: NodeJS.Signals): boolean;
     /**
-     * Register a one-shot listener for the native exit.
+     * Register a one-shot listener for the native exit or stream close.
      *
-     * @param event - The `exit` event name
-     * @param listener - The listener invoked after the process exits
+     * @param event - The `exit` or `close` event name
+     * @param listener - The listener invoked after the selected event
      * @returns Whatever the emitter returns, which the helpers ignore
      */
-    once(event: 'exit', listener: () => void): unknown;
+    once(event: 'exit' | 'close', listener: () => void): unknown;
     /**
-     * Release one previously registered exit listener.
+     * Release one previously registered exit or close listener.
      *
      * @remarks
-     * `waitForExit` calls this when its deadline elapses before the exit, so a child that outlives
-     * several bounded waits accumulates no listeners.
+     * `waitForExit` releases its `exit` listener, and `waitForClose` releases its `close` listener, so
+     * a child that outlives several bounded waits accumulates neither.
      *
-     * @param event - The `exit` event name
+     * @param event - The `exit` or `close` event name
      * @param listener - The listener registered through `once`
      * @returns Whatever the emitter returns, which the helpers ignore
      */
-    off(event: 'exit', listener: () => void): unknown;
+    off(event: 'exit' | 'close', listener: () => void): unknown;
 }
 
 /**
@@ -520,9 +533,9 @@ export declare interface ProcessChild {
  * the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
  * and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
  * getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
- * `exit`, never from `launch`. `destroy` awaits every child's own teardown, which destroys each
- * child's observation emitter and leaves every subscription on it silently inert, then destroys the
- * registry emitter last.
+ * `exit`, never from `launch`. `destroy` awaits every child's own teardown, including the teardown
+ * of a child a lost race refused, which destroys each child's observation emitter and leaves every
+ * subscription on it silently inert, then destroys the registry emitter last.
  *
  * @example
  * ```ts
@@ -568,11 +581,11 @@ export declare class ProcessManager implements ProcessManagerInterface {
      * @remarks
      * {@link Process} reads every option before it spawns, so a caller's own option getter runs while
      * nothing has started and a throw from one strands no process. A getter that begins `destroy`
-     * without throwing is the one remaining race, and it leaves a bounded residual: the child is
-     * already spawned, so the launch is refused with a {@link createProtocolError} and that child is
-     * torn down asynchronously, bounded by `grace` plus the confirmation window. The `protocol`
-     * refusal throws synchronously before the `destroy` barrier settles. The barrier does not cover
-     * that child's asynchronous teardown.
+     * without throwing is the one remaining race: the child is already spawned, so the launch is
+     * refused with a {@link createProtocolError} and that child is destroyed rather than adopted, its
+     * teardown bounded by `grace` plus the confirmation window. The `protocol` refusal throws
+     * synchronously, and the `destroy` barrier covers that teardown, so the refused child reaches its
+     * terminal moment before the barrier resolves.
      *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
@@ -747,14 +760,16 @@ export declare function snapshotCommand(command: ProcessCommand): ProcessCommand
  * Terminates one child process tree and reports whether its native exit was observed.
  *
  * @remarks
- * Windows ends the whole tree at once through {@link killTree}, falling back to a direct kill after
- * the utility fails, because the host has no cooperative termination to offer. A POSIX host signals
- * the process group `SIGTERM`, falls back to the direct child when no group owns its pid, waits
- * `grace`, then sends `SIGKILL` through the same route. No signal is initiated after the native exit
- * is observed; the window between initiating a signal and the host delivering it belongs to the
- * operating system. `confirm` bounds each awaited step rather than the call as a whole: on Windows
- * it bounds the `taskkill` call and then the final wait, and on a POSIX host `grace` bounds the
- * cooperative wait and `confirm` the final one. Never rejects.
+ * An already-exited child is returned on before any route to its pid runs, because the host has
+ * reaped that number and may have handed it to another process. 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`
@@ -907,6 +922,20 @@ export declare function validateTimer(value: number | undefined, subject: string
  */
 export declare function validateWorkspace(workspace: string | undefined): void;
 
+/**
+ * Waits for one child process's streams to close, bounded by a deadline.
+ *
+ * @param child - The child boundary
+ * @param timeout - The milliseconds to wait before giving up
+ * @returns True when the host close arrived inside the deadline; false otherwise
+ *
+ * @example
+ * ```ts
+ * const closed = await waitForClose(child, 5_000)
+ * ```
+ */
+export declare function waitForClose(child: Pick<ProcessChild, 'once' | 'off'>, timeout: number): Promise<boolean>;
+
 /**
  * Waits for one child process's native exit, bounded by a deadline.
  *

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

@@ -187,9 +187,13 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * 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.
+ * overrides `command.input`. A host fault while writing that input terminates the run by design and
+ * marks its result failed; a strict rejection carries the host fault as its cause. This differs
+ * from `Process` constructor input, whose package-initiated input phase stays quiet. Unless `strict`
+ * is `false`, a failed run rejects with a {@link ProcessError} carrying the {@link ExecuteResult};
+ * {@link createExecuteError} constructs every rejection outside the input-fault door. 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
@@ -358,26 +362,23 @@ export declare function mergeEnvironment(isolated: boolean, base?: Readonly<Reco
 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.
+ * Supervises one child while keeping every observation channel aligned at termination.
  *
  * @remarks
- * Standard output is framed through `readline` into a single-consumer stream: each line goes to
- * exactly one waiting iterator, so concurrent iterators split the output rather than each receiving
- * all of it. While no consumer has ever requested an iterator, stdout keeps draining so `exit` still
- * resolves, and retention stops at the `backlog` mark: a
- * consumer attaching later receives the retained head, a gap, then the live stream. After an iterator
- * has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
- * nothing before termination and the child feels real backpressure. The mark is soft — the ordinary backlog can
- * overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
- * reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
- * and `truncated` reports the omission. Standard error is decoded and forwarded live as the `stderr`
- * event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries the
- * child `error` cause on a spawn fault and the terminal `exit`, alongside the `exit` promise. `pid`,
- * `code`, and `signal` read the spawned child directly, so the native exit is readable before the
- * `exit` promise settles on stdio close. `stop` ends the whole tree and reports whether the native
- * exit was observed; `destroy` stops the child, destroys stdin so every pending `send` settles, and
- * destroys the emitter last. `destroy` resolving does not imply the child's stdio has closed, so
- * `exit` and `lines` can still be outstanding when a descendant holds an inherited pipe.
+ * The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
+ * the host child directly, so they expose native exit as soon as the host records it. `settled`,
+ * `exit`, `evidence`, and `lines` reach one terminal moment after the read channels close or the
+ * bounded `drain` window cuts them off. That window is armed by the child's native exit and by a
+ * termination this package initiated, so every way a child can end reaches the moment. The terminal
+ * routine freezes `evidence` and ends `lines` before it destroys stdout, stderr, or the emitter, so
+ * the push channel never disappears while a pull channel can still change or wait indefinitely.
+ *
+ * Standard output is framed through `readline` into a single-consumer stream. Lines already framed
+ * and queued remain available through the terminal moment, while bytes arriving after a requested
+ * termination may be cut off. Standard error is forwarded through the live `stderr` event and
+ * retained as a byte-bounded raw tail until that same moment. `stop` ends the child tree and the
+ * observation surfaces. `destroy` performs that stop and then destroys the emitter after the
+ * frozen terminal state exists.
  *
  * @example
  * ```ts
@@ -408,41 +409,53 @@ export declare class Process implements ProcessInterface {
     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. */
+    /** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
     get lines(): AsyncIterable<string>;
-    /** The decoded byte-bounded stderr tail. */
+    /** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
     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. */
+    /** True after the terminal moment arrived and `exit` settled. */
+    get settled(): boolean;
+    /** True after termination began, including after the terminal moment. */
+    get stopping(): boolean;
+    /** The terminal child state, observed once after stream close or the drain cutoff. */
     get exit(): Promise<ProcessExit>;
     /**
      * Write one line to the open standard-input channel.
      *
      * @remarks
-     * Never rejects. The promise settles when the host reports the line handled, so a line written to
-     * a child that is not reading stays pending until the child drains it or the channel closes. Every
-     * terminal teardown path destroys stdin, so a pending write always settles by teardown; a caller
-     * that needs its own deadline arms a timer and calls `stop`.
+     * 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>;
     /**
-     * Terminate the child process tree and await its observed exit.
+     * Terminates the child process tree and reaches the terminal observation moment.
      *
      * @remarks
-     * Never rejects, and every call shares one termination.
+     * Never rejects, and every call shares one termination. After the termination sequence returns,
+     * confirmed or not, it waits at most `drain` for the read channels to close, then cuts them off
+     * and settles `exit` when they remain open. A cutoff reached before the native exit reports the
+     * `code` and `signal` the host had recorded by then, which is `null` for a child still running.
      *
      * @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
      */
     stop(): Promise<boolean>;
     /**
-     * Stop the child, close its standard-input channel, and destroy the observation emitter.
+     * Stops the child and destroys the observation emitter after the terminal state freezes.
      *
      * @remarks
-     * Always resolves, including when termination was never confirmed.
+     * Always resolves, including when termination was never confirmed. Every call shares one barrier.
      *
      * @returns The stable barrier shared by every call
      */
@@ -465,8 +478,8 @@ export declare class Process implements ProcessInterface {
  * members, which is what lets a caller drive `stopChild` over a child it spawned itself. Each helper
  * takes the slice of this contract it reads: `exitCode` and `signalCode` are the host's
  * authoritative liveness answer, `pid` addresses a POSIX process group, `kill` delivers one signal,
- * `once` reports the native exit, and `off` releases that listener when the wait ends at its
- * deadline instead.
+ * `once` reports the native exit to `waitForExit` or the stream close to `waitForClose`, and `off`
+ * releases the corresponding listener when either wait ends.
  *
  * 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`
@@ -487,25 +500,25 @@ export declare interface ProcessChild {
      */
     kill(signal: NodeJS.Signals): boolean;
     /**
-     * Register a one-shot listener for the native exit.
+     * Register a one-shot listener for the native exit or stream close.
      *
-     * @param event - The `exit` event name
-     * @param listener - The listener invoked after the process exits
+     * @param event - The `exit` or `close` event name
+     * @param listener - The listener invoked after the selected event
      * @returns Whatever the emitter returns, which the helpers ignore
      */
-    once(event: 'exit', listener: () => void): unknown;
+    once(event: 'exit' | 'close', listener: () => void): unknown;
     /**
-     * Release one previously registered exit listener.
+     * Release one previously registered exit or close listener.
      *
      * @remarks
-     * `waitForExit` calls this when its deadline elapses before the exit, so a child that outlives
-     * several bounded waits accumulates no listeners.
+     * `waitForExit` releases its `exit` listener, and `waitForClose` releases its `close` listener, so
+     * a child that outlives several bounded waits accumulates neither.
      *
-     * @param event - The `exit` event name
+     * @param event - The `exit` or `close` event name
      * @param listener - The listener registered through `once`
      * @returns Whatever the emitter returns, which the helpers ignore
      */
-    off(event: 'exit', listener: () => void): unknown;
+    off(event: 'exit' | 'close', listener: () => void): unknown;
 }
 
 /**
@@ -520,9 +533,9 @@ export declare interface ProcessChild {
  * the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
  * and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
  * getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
- * `exit`, never from `launch`. `destroy` awaits every child's own teardown, which destroys each
- * child's observation emitter and leaves every subscription on it silently inert, then destroys the
- * registry emitter last.
+ * `exit`, never from `launch`. `destroy` awaits every child's own teardown, including the teardown
+ * of a child a lost race refused, which destroys each child's observation emitter and leaves every
+ * subscription on it silently inert, then destroys the registry emitter last.
  *
  * @example
  * ```ts
@@ -568,11 +581,11 @@ export declare class ProcessManager implements ProcessManagerInterface {
      * @remarks
      * {@link Process} reads every option before it spawns, so a caller's own option getter runs while
      * nothing has started and a throw from one strands no process. A getter that begins `destroy`
-     * without throwing is the one remaining race, and it leaves a bounded residual: the child is
-     * already spawned, so the launch is refused with a {@link createProtocolError} and that child is
-     * torn down asynchronously, bounded by `grace` plus the confirmation window. The `protocol`
-     * refusal throws synchronously before the `destroy` barrier settles. The barrier does not cover
-     * that child's asynchronous teardown.
+     * without throwing is the one remaining race: the child is already spawned, so the launch is
+     * refused with a {@link createProtocolError} and that child is destroyed rather than adopted, its
+     * teardown bounded by `grace` plus the confirmation window. The `protocol` refusal throws
+     * synchronously, and the `destroy` barrier covers that teardown, so the refused child reaches its
+     * terminal moment before the barrier resolves.
      *
      * @param id - The registry key, unique among live children
      * @param options - The child construction options
@@ -747,14 +760,16 @@ export declare function snapshotCommand(command: ProcessCommand): ProcessCommand
  * Terminates one child process tree and reports whether its native exit was observed.
  *
  * @remarks
- * Windows ends the whole tree at once through {@link killTree}, falling back to a direct kill after
- * the utility fails, because the host has no cooperative termination to offer. A POSIX host signals
- * the process group `SIGTERM`, falls back to the direct child when no group owns its pid, waits
- * `grace`, then sends `SIGKILL` through the same route. No signal is initiated after the native exit
- * is observed; the window between initiating a signal and the host delivering it belongs to the
- * operating system. `confirm` bounds each awaited step rather than the call as a whole: on Windows
- * it bounds the `taskkill` call and then the final wait, and on a POSIX host `grace` bounds the
- * cooperative wait and `confirm` the final one. Never rejects.
+ * An already-exited child is returned on before any route to its pid runs, because the host has
+ * reaped that number and may have handed it to another process. 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`
@@ -907,6 +922,20 @@ export declare function validateTimer(value: number | undefined, subject: string
  */
 export declare function validateWorkspace(workspace: string | undefined): void;
 
+/**
+ * Waits for one child process's streams to close, bounded by a deadline.
+ *
+ * @param child - The child boundary
+ * @param timeout - The milliseconds to wait before giving up
+ * @returns True when the host close arrived inside the deadline; false otherwise
+ *
+ * @example
+ * ```ts
+ * const closed = await waitForClose(child, 5_000)
+ * ```
+ */
+export declare function waitForClose(child: Pick<ProcessChild, 'once' | 'off'>, timeout: number): Promise<boolean>;
+
 /**
  * Waits for one child process's native exit, bounded by a deadline.
  *