@orkestrel/process 0.0.5 → 0.0.7

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

@@ -362,29 +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 a
- * child `error` cause on a spawn fault, a `protocol` {@link ProcessError} on a host-reported stdin
- * fault after the constructor input phase, and the terminal `exit`, alongside the `exit` promise.
- * A fault arising from the constructor-supplied `input` write or its closing `end` stays quiet
- * because the package initiated that sequence. `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
@@ -415,13 +409,17 @@ 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.
@@ -442,19 +440,22 @@ export declare class Process implements ProcessInterface {
      */
     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
      */
@@ -477,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`
@@ -499,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;
 }
 
 /**
@@ -532,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
@@ -580,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
@@ -759,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`
@@ -919,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

@@ -362,29 +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 a
- * child `error` cause on a spawn fault, a `protocol` {@link ProcessError} on a host-reported stdin
- * fault after the constructor input phase, and the terminal `exit`, alongside the `exit` promise.
- * A fault arising from the constructor-supplied `input` write or its closing `end` stays quiet
- * because the package initiated that sequence. `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
@@ -415,13 +409,17 @@ 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.
@@ -442,19 +440,22 @@ export declare class Process implements ProcessInterface {
      */
     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
      */
@@ -477,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`
@@ -499,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;
 }
 
 /**
@@ -532,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
@@ -580,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
@@ -759,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`
@@ -919,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.
  *